wowdump 0.2.1 → 0.3.1

package/dist/main.js

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { buildAdapterRegistry } from "./adapters.js";
+import { discoverInstalls } from "./discovery.js";
+import { createDryRunReport } from "./dry-run.js";
+import { listWowProcesses } from "./processes.js";
+const gameRoot = process.env.WOW_ROOT ?? "D:/Game/World of Warcraft";
+const agentFile = resolve(process.env.WOW_AGENT ?? "dist/agent.js");
+const output = resolve(process.env.WOW_ERRORS ?? "data/errors.jsonl");
+const pollMs = Number(process.env.WOW_POLL_MS ?? 1500);
+const installs = discoverInstalls(gameRoot);
+if (process.argv.includes("--discover")) {
+    console.log(JSON.stringify(installs, null, 2));
+}
+else if (process.argv.includes("--dry-run")) {
+    try {
+        const processes = await listWowProcesses(installs);
+        console.log(JSON.stringify(createDryRunReport(installs, processes, buildAdapterRegistry), null, 2));
+    }
+    catch (error) {
+        console.error("process scan:", error);
+        process.exitCode = 1;
+    }
+}
+else {
+    await runCollector();
+}
+async function runCollector() {
+    const [{ ProcessSession }, { JsonlStore }] = await Promise.all([
+        import("./session.js"),
+        import("./storage.js")
+    ]);
+    console.log(`Discovered ${installs.length} WoW installs under ${gameRoot}`);
+    const store = new JsonlStore(output);
+    const sessions = new Map();
+    async function poll() {
+        const processes = await listWowProcesses(installs).catch(error => {
+            console.error("process scan:", error);
+            return [];
+        });
+        const live = new Set(processes.map(process => process.pid));
+        for (const [pid, session] of sessions) {
+            if (!live.has(pid)) {
+                await session.detach();
+                sessions.delete(pid);
+            }
+        }
+        for (const process of processes) {
+            if (sessions.has(process.pid))
+                continue;
+            const session = new ProcessSession(process, agentFile, store);
+            await session.attach()
+                .then(() => sessions.set(process.pid, session))
+                .catch(error => console.error(`attach ${process.pid}:`, error));
+        }
+    }
+    await poll();
+    const timer = setInterval(() => void poll(), pollMs);
+    const shutdown = async () => {
+        clearInterval(timer);
+        for (const session of sessions.values())
+            await session.detach();
+        process.exit(0);
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}

package/dist/processes.js

@@ -29,10 +29,7 @@ export function parseWowProcessRows(stdout, installs) {
                 pid,
                 executable,
                 install,
-                commandLine: String(row.CommandLine ?? ""),
-                ...(typeof row.StartTime === "string" && row.StartTime.length > 0
-                    ? { startTime: row.StartTime }
-                    : {})
+                commandLine: String(row.CommandLine ?? "")
             }];
     });
 }
@@ -41,7 +38,7 @@ export async function listWowProcesses(installs) {
         "-NoProfile",
         "-NonInteractive",
         "-Command",
-        "Get-CimInstance Win32_Process -Filter \"Name = 'Wow.exe'\" | Select-Object Name,ProcessId,ExecutablePath,CommandLine,@{Name='StartTime';Expression={$_.CreationDate.ToUniversalTime().ToString('o')}} | ConvertTo-Json -Compress"
+        "Get-CimInstance Win32_Process -Filter \"Name = 'Wow.exe'\" | Select-Object Name,ProcessId,ExecutablePath,CommandLine | ConvertTo-Json -Compress"
     ], { windowsHide: true });
     return parseWowProcessRows(stdout, installs);
 }

package/dist/reader-broker.js

@@ -0,0 +1,460 @@
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+export const DEFAULT_IDLE_TIMEOUT_MS = 20 * 60 * 1000;
+export const DEFAULT_RIGHTS = Object.freeze([
+    "PROCESS_QUERY_INFORMATION",
+    "PROCESS_VM_READ"
+]);
+function hexAddress(value) {
+    const normalized = value.trim();
+    if (!/^0x[0-9a-f]+$/i.test(normalized)) {
+        throw new ReaderProtocolError("INVALID_ADDRESS", "address must be a hexadecimal 0x-prefixed string");
+    }
+    const address = BigInt(normalized);
+    if (address < 0n || address > 0xffffffffffffffffn) {
+        throw new ReaderProtocolError("INVALID_ADDRESS", "address is outside the 64-bit range");
+    }
+    return address;
+}
+function boundedSize(value, name, maximum = 16 * 1024 * 1024) {
+    const size = Number(value);
+    if (!Number.isSafeInteger(size) || size <= 0 || size > maximum) {
+        throw new ReaderProtocolError("INVALID_SIZE", `${name} must be an integer between 1 and ${maximum}`);
+    }
+    return size;
+}
+function boundedPid(value) {
+    const pid = Number(value);
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fffffff) {
+        throw new ReaderProtocolError("INVALID_PID", "pid must be a positive Windows process id");
+    }
+    return pid;
+}
+function toHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function bytesFromResult(result) {
+    if (!result || !(result.bytes instanceof Uint8Array)) {
+        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned no byte buffer");
+    }
+    const bytesRead = result.bytesRead === undefined ? result.bytes.byteLength : Number(result.bytesRead);
+    if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > result.bytes.byteLength) {
+        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned an invalid bytesRead value");
+    }
+    return { bytes: result.bytes.subarray(0, bytesRead), bytesRead };
+}
+export class ReaderProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ReaderProtocolError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Placeholder backend used until the platform adapter is installed.  Keeping
+ * this explicit makes an unavailable native layer observable to the caller.
+ */
+export class UnavailableNativeReader {
+    diagnostic() {
+        throw new ReaderProtocolError("NATIVE_BACKEND_UNAVAILABLE", "Windows native reader backend is not installed", {
+            platform: process.platform,
+            requestedRights: [...DEFAULT_RIGHTS],
+            elevation: this.elevationStatus()
+        });
+    }
+    openProcess(_pid, _rights) {
+        return Promise.reject(this.diagnostic());
+    }
+    readProcessMemory(_handle, _address, _size) {
+        return Promise.reject(this.diagnostic());
+    }
+    elevationStatus() {
+        return {
+            isWindows: process.platform === "win32",
+            elevated: false,
+            state: "unknown",
+            reason: "native elevation probe is not installed"
+        };
+    }
+}
+export class ReaderBroker {
+    idleTimeoutMs;
+    backend;
+    now;
+    onShutdown;
+    handles = new Map();
+    watches = new Map();
+    idleTimer;
+    watchCounter = 0;
+    stopped = false;
+    constructor(options = {}) {
+        this.backend = options.backend ?? new UnavailableNativeReader();
+        this.idleTimeoutMs = Math.max(1, Math.floor(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS));
+        this.now = options.now ?? Date.now;
+        this.onShutdown = options.onShutdown;
+        this.armIdleTimer();
+    }
+    get isStopped() {
+        return this.stopped;
+    }
+    get activeHandleCount() {
+        return this.handles.size;
+    }
+    get activeWatchCount() {
+        return [...this.watches.values()].filter(watch => !watch.stopped).length;
+    }
+    /** Handle one already-decoded request. Suitable for a CLI client or tests. */
+    async handle(request) {
+        const command = typeof request?.command === "string" ? request.command : "unknown";
+        const base = { id: request?.id, ok: true, command, timestamp: this.now() };
+        if (this.stopped) {
+            return { ...base, ok: false, error: { code: "BROKER_STOPPED", message: "reader broker is stopped" } };
+        }
+        try {
+            const result = await this.dispatch(request);
+            this.armIdleTimer();
+            return { ...base, ...result, ok: true };
+        }
+        catch (error) {
+            this.armIdleTimer();
+            return { ...base, ok: false, error: serializeError(error, this.backend) };
+        }
+    }
+    async shutdown(reason = "request") {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        for (const watch of this.watches.values())
+            watch.stopped = true;
+        this.watches.clear();
+        const handles = [...this.handles.values()];
+        this.handles.clear();
+        for (const handle of handles) {
+            await Promise.resolve(handle.close()).catch(() => undefined);
+        }
+        await Promise.resolve(this.backend.close?.()).catch(() => undefined);
+        await Promise.resolve(this.onShutdown?.(reason)).catch(() => undefined);
+    }
+    armIdleTimer() {
+        if (this.stopped)
+            return;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            void this.shutdown("idle");
+        }, this.idleTimeoutMs);
+        // A broker should not keep an otherwise idle CLI event loop alive in tests.
+        this.idleTimer.unref?.();
+    }
+    async dispatch(request) {
+        switch (request.command) {
+            case "status":
+                return {
+                    pid: process.pid,
+                    idleTimeoutMs: this.idleTimeoutMs,
+                    activeHandles: this.handles.size,
+                    activeWatches: this.activeWatchCount,
+                    elevation: await Promise.resolve(this.backend.elevationStatus?.() ?? { state: "unknown" })
+                };
+            case "open":
+                return this.open(request);
+            case "close":
+                return this.close(request);
+            case "read":
+                return this.read(request);
+            case "watch.start":
+                return this.watchStart(request);
+            case "watch.poll":
+                return this.watchPoll(request);
+            case "watch.stop":
+                return this.watchStop(request);
+            case "shutdown":
+                await this.shutdown("request");
+                return { stopped: true };
+            default:
+                throw new ReaderProtocolError("UNKNOWN_COMMAND", `unsupported reader command: ${String(request?.command)}`);
+        }
+    }
+    async getHandle(pid, requested) {
+        const existing = this.handles.get(pid);
+        if (existing && (!requested || requested === existing.id))
+            return existing;
+        if (requested && existing?.id !== requested) {
+            throw new ReaderProtocolError("HANDLE_MISMATCH", `handle ${requested} is not open for pid ${pid}`);
+        }
+        const handle = await this.backend.openProcess(pid, DEFAULT_RIGHTS);
+        this.handles.set(pid, handle);
+        return handle;
+    }
+    async open(request) {
+        const pid = boundedPid(request.pid);
+        const rights = request.rights?.length ? [...request.rights] : [...DEFAULT_RIGHTS];
+        const handle = await this.backend.openProcess(pid, rights);
+        const previous = this.handles.get(pid);
+        if (previous && previous !== handle)
+            await Promise.resolve(previous.close()).catch(() => undefined);
+        this.handles.set(pid, handle);
+        return { pid, handle: handle.id, rights };
+    }
+    async close(request) {
+        const pid = request.pid === undefined ? undefined : boundedPid(request.pid);
+        const handle = pid === undefined
+            ? [...this.handles.values()].find(candidate => candidate.id === request.handle)
+            : this.handles.get(pid);
+        if (!handle)
+            return { closed: false, pid, handle: request.handle };
+        await Promise.resolve(handle.close());
+        if (pid !== undefined)
+            this.handles.delete(pid);
+        else
+            for (const [key, candidate] of this.handles)
+                if (candidate === handle)
+                    this.handles.delete(key);
+        for (const watch of this.watches.values()) {
+            if (watch.handle === handle)
+                watch.stopped = true;
+        }
+        return { closed: true, pid, handle: handle.id };
+    }
+    async read(request) {
+        const pid = boundedPid(request.pid);
+        const address = hexAddress(request.address);
+        const size = boundedSize(request.size, "size");
+        const handle = await this.getHandle(pid, request.handle);
+        const startedAt = this.now();
+        const native = bytesFromResult(await this.backend.readProcessMemory(handle, address, size));
+        return {
+            pid,
+            handle: handle.id,
+            address: `0x${address.toString(16)}`,
+            requestedSize: size,
+            bytesRead: native.bytesRead,
+            dataHex: toHex(native.bytes),
+            complete: native.bytesRead === size,
+            startedAt,
+            finishedAt: this.now()
+        };
+    }
+    async watchStart(request) {
+        const pid = boundedPid(request.pid);
+        const address = hexAddress(request.address);
+        const size = boundedSize(request.size, "size", 1024 * 1024);
+        const intervalMs = Math.min(60 * 60 * 1000, Math.max(10, Math.floor(Number(request.intervalMs ?? 1000))));
+        const maxSamples = Math.min(100000, Math.max(1, Math.floor(Number(request.maxSamples ?? 0) || 100000)));
+        const handle = await this.getHandle(pid, request.handle);
+        const id = `watch-${++this.watchCounter}`;
+        this.watches.set(id, {
+            id,
+            pid,
+            address,
+            size,
+            intervalMs,
+            changeOnly: request.changeOnly === true,
+            maxSamples,
+            handle,
+            sequence: 0,
+            nextDue: this.now(),
+            stopped: false
+        });
+        return { watchId: id, pid, handle: handle.id, address: `0x${address.toString(16)}`, size, intervalMs, changeOnly: request.changeOnly === true, maxSamples };
+    }
+    async watchPoll(request) {
+        if (!request.watchId || typeof request.watchId !== "string")
+            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+        const watch = this.watches.get(request.watchId);
+        if (!watch || watch.stopped)
+            return { watchId: request.watchId, stopped: true, events: [] };
+        const now = this.now();
+        if (now < watch.nextDue)
+            return { watchId: watch.id, stopped: false, events: [], nextDue: watch.nextDue };
+        watch.nextDue = now + watch.intervalMs;
+        if (watch.sequence >= watch.maxSamples) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "max_samples", events: [] };
+        }
+        if (this.backend.isProcessAlive && !(await this.backend.isProcessAlive(watch.pid))) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "target_exited", events: [{ type: "target_exited", pid: watch.pid, sequence: watch.sequence + 1, timestamp: now }] };
+        }
+        try {
+            const native = bytesFromResult(await this.backend.readProcessMemory(watch.handle, watch.address, watch.size));
+            const changed = !watch.lastBytes || !equalBytes(watch.lastBytes, native.bytes);
+            watch.sequence += 1;
+            const event = {
+                type: changed ? "snapshot" : "unchanged",
+                watchId: watch.id,
+                pid: watch.pid,
+                sequence: watch.sequence,
+                timestamp: this.now(),
+                address: `0x${watch.address.toString(16)}`,
+                requestedSize: watch.size,
+                bytesRead: native.bytesRead,
+                complete: native.bytesRead === watch.size,
+                dataHex: toHex(native.bytes),
+                changed
+            };
+            const previous = watch.lastBytes;
+            watch.lastBytes = new Uint8Array(native.bytes);
+            if (watch.changeOnly && !changed)
+                return { watchId: watch.id, stopped: false, events: [], sequence: watch.sequence };
+            return { watchId: watch.id, stopped: false, events: [event], previousHex: previous ? toHex(previous) : undefined, sequence: watch.sequence };
+        }
+        catch (error) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "reader_error", events: [{ type: "reader_error", watchId: watch.id, pid: watch.pid, sequence: watch.sequence + 1, timestamp: this.now(), error: serializeError(error, this.backend) }] };
+        }
+    }
+    async watchStop(request) {
+        if (!request.watchId || typeof request.watchId !== "string")
+            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+        const watch = this.watches.get(request.watchId);
+        if (!watch)
+            return { watchId: request.watchId, stopped: false };
+        watch.stopped = true;
+        this.watches.delete(request.watchId);
+        return { watchId: request.watchId, stopped: true, sequence: watch.sequence };
+    }
+}
+function equalBytes(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    for (let index = 0; index < left.byteLength; index += 1)
+        if (left[index] !== right[index])
+            return false;
+    return true;
+}
+function serializeError(error, backend) {
+    if (error instanceof ReaderProtocolError) {
+        return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: "READER_ERROR",
+        message,
+        elevation: backend.elevationStatus ? backend.elevationStatus() : { state: "unknown" }
+    };
+}
+/** Start a JSONL broker process over stdio. */
+export function serveReaderBroker(options = {}) {
+    const broker = new ReaderBroker({ ...options, attachStdio: false });
+    if (options.attachStdio !== false) {
+        const input = options.input ?? stdin;
+        const output = options.output ?? stdout;
+        const rl = createInterface({ input, crlfDelay: Infinity });
+        // Preserve JSONL request order so open/read/close sequences cannot race.
+        let pending = Promise.resolve();
+        rl.on("line", line => {
+            pending = pending.then(async () => {
+                if (!line.trim())
+                    return;
+                let request;
+                try {
+                    request = JSON.parse(line);
+                }
+                catch (error) {
+                    const response = {
+                        ok: false,
+                        command: "parse",
+                        timestamp: Date.now(),
+                        error: { code: "INVALID_JSON", message: error instanceof Error ? error.message : String(error) }
+                    };
+                    output.write(`${JSON.stringify(response)}\n`);
+                    return;
+                }
+                const response = await broker.handle(request);
+                output.write(`${JSON.stringify(response)}\n`);
+                if (request.command === "shutdown")
+                    rl.close();
+            });
+        });
+        const close = () => { void broker.shutdown("request"); };
+        input.once("close", close);
+        input.once("error", close);
+    }
+    return broker;
+}
+/** Small typed client used by the CLI; transport owns process/UAC reuse. */
+export class ReaderClient {
+    transport;
+    requestTimeoutMs;
+    counter = 0;
+    constructor(options) {
+        this.transport = options.transport;
+        this.requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? 30_000));
+    }
+    async request(request) {
+        const id = request.id ?? `req-${++this.counter}`;
+        const line = await withTimeout(this.transport.request(JSON.stringify({ ...request, id })), this.requestTimeoutMs);
+        const response = JSON.parse(line);
+        if (!response || typeof response !== "object" || typeof response.ok !== "boolean") {
+            throw new ReaderProtocolError("INVALID_RESPONSE", "reader broker returned an invalid JSONL response");
+        }
+        return response;
+    }
+    close() {
+        return Promise.resolve(this.transport.close?.());
+    }
+}
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new ReaderProtocolError("REQUEST_TIMEOUT", `reader request timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer.unref?.();
+        promise.then(value => { clearTimeout(timer); resolve(value); }, error => { clearTimeout(timer); reject(error); });
+    });
+}
+export function createElevatedLaunchSpec(file, args = []) {
+    if (!file.trim())
+        throw new TypeError("elevated broker file must be non-empty");
+    return Object.freeze({ file, args: [...args], verb: "runas", windowsHide: false });
+}
+/** Reuse one broker client and invoke the launcher only after the first miss. */
+export class ReaderBrokerPool {
+    client;
+    launching;
+    launcher;
+    launchSpec;
+    requestTimeoutMs;
+    constructor(launcher, launchSpec, requestTimeoutMs) {
+        this.launcher = launcher;
+        this.launchSpec = launchSpec;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    async request(request) {
+        const client = await this.getClient();
+        try {
+            return await client.request(request);
+        }
+        catch (error) {
+            // A dead broker is discarded; the next request gets a fresh UAC launch.
+            this.client = undefined;
+            throw error;
+        }
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        await client?.close();
+    }
+    async getClient() {
+        if (this.client)
+            return this.client;
+        if (!this.launching) {
+            this.launching = this.launcher.launch(this.launchSpec).then(result => {
+                this.client = new ReaderClient({ transport: result.transport, requestTimeoutMs: this.requestTimeoutMs });
+                return this.client;
+            }).catch(error => {
+                throw new ReaderProtocolError("ELEVATION_FAILED", error instanceof Error ? error.message : String(error), {
+                    verb: this.launchSpec.verb,
+                    requestedRights: [...DEFAULT_RIGHTS],
+                    elevation: "launch rejected or cancelled"
+                });
+            }).finally(() => { this.launching = undefined; });
+        }
+        return this.launching;
+    }
+}

package/dist/reader-client.js

@@ -0,0 +1 @@
+export { ReaderClient, ReaderBrokerPool, ReaderProtocolError, createElevatedLaunchSpec } from "./reader-broker.js";

package/dist/reader-main.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { createServer } from "node:net";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { serveReaderBroker } from "./reader-broker.js";
+import { createWindowsNativeReader } from "./windows-reader.js";
+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(),
+    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);