debug-toolkit 0.4.0

package/dist/memory.js

@@ -0,0 +1,291 @@
+/**
+ * memory.ts — Debug session memory across conversations.
+ *
+ * Three tiers of intelligence:
+ *   1. Recall — search past diagnoses for similar errors (keyword overlap)
+ *   2. Staleness — flag outdated diagnoses when code has changed since
+ *   3. Patterns — detect recurring errors, hot files, regression trends
+ *
+ * Implementation: JSON file + in-memory inverted index.
+ * Zero native dependencies. Fast enough for hundreds of sessions.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join, resolve } from "node:path";
+// ━━━ Git helpers ━━━
+function getGitSha(cwd) {
+    try {
+        return execSync("git rev-parse --short HEAD 2>/dev/null", { cwd, timeout: 3000 })
+            .toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check how many commits have touched a file since a given SHA.
+ * Returns null if git isn't available, 0 if unchanged, N if changed.
+ */
+function commitsSince(cwd, sha, file) {
+    try {
+        const count = execSync(`git rev-list --count ${sha}..HEAD -- "${file}" 2>/dev/null`, { cwd, timeout: 3000 }).toString().trim();
+        return parseInt(count, 10);
+    }
+    catch {
+        return null;
+    }
+}
+function checkStaleness(cwd, entry) {
+    if (!entry.gitSha)
+        return { stale: false, reason: null, commitsBehind: 0, filesChanged: [] };
+    let totalCommits = 0;
+    const changed = [];
+    for (const f of entry.files) {
+        // Resolve relative to cwd
+        const fullPath = resolve(cwd, f);
+        if (!existsSync(fullPath)) {
+            changed.push(f);
+            totalCommits += 1; // file deleted = definitely stale
+            continue;
+        }
+        const n = commitsSince(cwd, entry.gitSha, f);
+        if (n !== null && n > 0) {
+            changed.push(f);
+            totalCommits += n;
+        }
+    }
+    // Also check causeFile if it's different from the error files
+    if (entry.rootCause?.causeFile && !entry.files.includes(entry.rootCause.causeFile)) {
+        const n = commitsSince(cwd, entry.gitSha, entry.rootCause.causeFile);
+        if (n !== null && n > 0) {
+            changed.push(entry.rootCause.causeFile);
+            totalCommits += n;
+        }
+    }
+    if (changed.length === 0)
+        return { stale: false, reason: null, commitsBehind: 0, filesChanged: [] };
+    return {
+        stale: true,
+        reason: `${changed.length} file(s) changed in ${totalCommits} commit(s) since this diagnosis`,
+        commitsBehind: totalCommits,
+        filesChanged: changed,
+    };
+}
+/**
+ * Detect patterns across all stored debug sessions.
+ * Cheap — just scans the JSON array, no external calls.
+ */
+export function detectPatterns(cwd) {
+    const store = loadStore(cwd);
+    if (store.entries.length < 2)
+        return [];
+    const insights = [];
+    // 1. Recurring errors — same errorType in the same file
+    const errorFileMap = new Map();
+    for (const e of store.entries) {
+        for (const f of e.files) {
+            const key = `${e.errorType}:${f}`;
+            const arr = errorFileMap.get(key);
+            if (arr)
+                arr.push(e);
+            else
+                errorFileMap.set(key, [e]);
+        }
+    }
+    for (const [key, entries] of errorFileMap) {
+        if (entries.length >= 3) {
+            const [errType, file] = key.split(":", 2);
+            insights.push({
+                type: "recurring_error",
+                severity: entries.length >= 5 ? "critical" : "warning",
+                message: `${errType} has occurred ${entries.length} times in ${file}`,
+                data: { errorType: errType, file, count: entries.length, dates: entries.map((e) => e.timestamp) },
+            });
+        }
+    }
+    // 2. Hot files — files that appear in many debug sessions
+    const fileCount = new Map();
+    for (const e of store.entries) {
+        for (const f of e.files) {
+            fileCount.set(f, (fileCount.get(f) ?? 0) + 1);
+        }
+    }
+    const threshold = Math.max(3, Math.ceil(store.entries.length * 0.15));
+    for (const [file, count] of fileCount) {
+        if (count >= threshold) {
+            insights.push({
+                type: "hot_file",
+                severity: count >= threshold * 2 ? "critical" : "warning",
+                message: `${file} appears in ${count}/${store.entries.length} debug sessions (${Math.round(count / store.entries.length * 100)}%)`,
+                data: { file, sessions: count, total: store.entries.length },
+            });
+        }
+    }
+    // 3. Regressions — same problem diagnosed more than once (diagnosis keywords overlap)
+    for (let i = store.entries.length - 1; i >= 1; i--) {
+        const current = store.entries[i];
+        for (let j = i - 1; j >= Math.max(0, i - 20); j--) { // only check recent 20
+            const past = store.entries[j];
+            if (current.id === past.id)
+                continue;
+            // Check if same files AND same errorType — likely a regression
+            const sharedFiles = current.files.filter((f) => past.files.includes(f));
+            if (sharedFiles.length > 0 && current.errorType === past.errorType) {
+                insights.push({
+                    type: "regression",
+                    severity: "warning",
+                    message: `Possible regression: ${current.errorType} in ${sharedFiles[0]} was fixed before (${past.timestamp.slice(0, 10)}) but reappeared`,
+                    data: {
+                        currentId: current.id, pastId: past.id,
+                        file: sharedFiles[0], errorType: current.errorType,
+                        pastDiagnosis: past.diagnosis, currentProblem: current.problem,
+                    },
+                });
+                break; // Only report the most recent regression per entry
+            }
+        }
+    }
+    // 4. Error clusters — multiple different errors happening in a short time window
+    const sorted = [...store.entries].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    for (let i = 0; i < sorted.length - 2; i++) {
+        const window = sorted.slice(i, i + 3);
+        const t0 = new Date(window[0].timestamp).getTime();
+        const t2 = new Date(window[2].timestamp).getTime();
+        const hoursDiff = (t2 - t0) / (1000 * 60 * 60);
+        if (hoursDiff < 2 && hoursDiff > 0) {
+            const uniqueErrors = new Set(window.map((e) => e.errorType));
+            if (uniqueErrors.size >= 2) {
+                insights.push({
+                    type: "error_cluster",
+                    severity: "info",
+                    message: `${window.length} errors in ${Math.round(hoursDiff * 60)} minutes — possible cascading failure`,
+                    data: {
+                        errors: window.map((e) => ({ type: e.errorType, file: e.files[0], time: e.timestamp })),
+                        timeWindowMinutes: Math.round(hoursDiff * 60),
+                    },
+                });
+                i += 2; // Skip past this cluster
+            }
+        }
+    }
+    return insights;
+}
+// ━━━ Paths & Persistence ━━━
+function memoryPath(cwd) {
+    return join(cwd, ".debug", "memory.json");
+}
+function loadStore(cwd) {
+    const p = memoryPath(cwd);
+    if (!existsSync(p))
+        return { version: 2, entries: [] };
+    try {
+        const store = JSON.parse(readFileSync(p, "utf-8"));
+        // Migrate v1 entries (no gitSha/rootCause)
+        for (const e of store.entries) {
+            if (e.gitSha === undefined)
+                e.gitSha = null;
+            if (e.rootCause === undefined)
+                e.rootCause = null;
+        }
+        store.version = 2;
+        return store;
+    }
+    catch {
+        return { version: 2, entries: [] };
+    }
+}
+function saveStore(cwd, store) {
+    const p = memoryPath(cwd);
+    const tmp = `${p}.tmp_${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2));
+    renameSync(tmp, p);
+}
+// ━━━ Tokenizer ━━━
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9_./\-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+}
+// ━━━ Public API ━━━
+/**
+ * Save a completed debug session to memory.
+ * Auto-captures the current git SHA for staleness tracking.
+ */
+export function remember(cwd, entry) {
+    const store = loadStore(cwd);
+    const allText = [
+        entry.problem, entry.errorType, entry.category, entry.diagnosis,
+        ...entry.files,
+        entry.rootCause?.trigger ?? "",
+        entry.rootCause?.fixDescription ?? "",
+    ].join(" ");
+    const keywords = [...new Set(tokenize(allText))];
+    const full = {
+        ...entry,
+        keywords,
+        gitSha: getGitSha(cwd),
+        rootCause: entry.rootCause ?? null,
+    };
+    store.entries = store.entries.filter((e) => e.id !== full.id);
+    store.entries.push(full);
+    if (store.entries.length > 200) {
+        store.entries = store.entries.slice(-200);
+    }
+    saveStore(cwd, store);
+    return full;
+}
+/**
+ * Search past debug sessions for similar errors.
+ * Returns matches ranked by relevance, with staleness info and causal chains.
+ */
+export function recall(cwd, query, limit = 5) {
+    const store = loadStore(cwd);
+    if (store.entries.length === 0)
+        return [];
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0)
+        return [];
+    const scored = store.entries.map((entry) => {
+        let hits = 0;
+        for (const qt of queryTokens) {
+            for (const ek of entry.keywords) {
+                if (ek.includes(qt) || qt.includes(ek)) {
+                    hits++;
+                    break;
+                }
+            }
+        }
+        return {
+            ...entry,
+            relevance: hits / queryTokens.length,
+            staleness: checkStaleness(cwd, entry),
+        };
+    });
+    return scored
+        .filter((e) => e.relevance > 0.2)
+        .sort((a, b) => {
+        // Prefer fresh over stale, then by relevance
+        if (a.staleness.stale !== b.staleness.stale)
+            return a.staleness.stale ? 1 : -1;
+        return b.relevance - a.relevance;
+    })
+        .slice(0, limit);
+}
+/**
+ * Get memory stats.
+ */
+export function memoryStats(cwd) {
+    const store = loadStore(cwd);
+    if (store.entries.length === 0) {
+        return { entries: 0, oldestDate: null, newestDate: null, patterns: [] };
+    }
+    return {
+        entries: store.entries.length,
+        oldestDate: store.entries[0].timestamp,
+        newestDate: store.entries[store.entries.length - 1].timestamp,
+        patterns: detectPatterns(cwd),
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}

package/dist/methodology.d.ts

@@ -0,0 +1,7 @@
+/**
+ * methodology.ts — The debugging methodology, served as an MCP resource.
+ *
+ * This is the "hot memory" tier — always available, always loaded.
+ * It teaches the agent HOW to debug, not just gives it tools.
+ */
+export declare const METHODOLOGY = "# Debug Toolkit \u2014 Methodology\n\n## The Rule\nDiagnosis quality matters more than fix quality.\nA wrong diagnosis wastes 5-10 agent turns. A wrong fix wastes 1.\nInvest time understanding the error before touching the code.\n\n## The Workflow\n\n### Step 1: Investigate (ALWAYS start here)\nCall `debug_investigate` with the error text.\nYou get back: error classification, source code at the crash site,\ngit context, runtime environment, AND any past solutions for similar errors.\n\nIf past solutions are returned, check the `stale` field:\n- `stale: false` \u2192 the code hasn't changed since. Trust the diagnosis.\n- `stale: true` \u2192 the code has changed. The diagnosis may still apply but verify.\n\nIf a `rootCause` is included, it tells you exactly which file caused\nthe error last time and what was done to fix it. Start there.\n\n### Step 2: Form Hypotheses\nBased on the investigation, form 2-3 theories about the root cause.\nRank them by likelihood. The most common causes are:\n- Null/undefined access (TypeError)\n- Missing import or dependency (ReferenceError, ModuleNotFoundError)\n- Wrong API usage (check framework version in environment)\n- Stale state (recent git changes may have introduced it)\n- Environment mismatch (wrong Node version, missing env var)\n\n### Step 3: Probe (only if needed)\nIf the investigation didn't reveal the cause, use `debug_instrument`\nto add logging at the suspicious code path. Then `debug_capture` to\nsee what values flow through at runtime.\n\nTag each instrument with a hypothesis so captures are linked.\n\n### Step 4: Fix\nApply the minimal fix. Change as few lines as possible.\nIf you're changing more than 10 lines, you probably have the wrong diagnosis.\n\n### Step 5: Verify\nCall `debug_verify` with the test command. Check exit code AND error output.\nDo not trust \"it compiles\" \u2014 silent failures are the #1 problem.\n\n### Step 6: Cleanup\nCall `debug_cleanup` with:\n- `diagnosis`: one-line root cause summary\n- `rootCause`: the causal chain (trigger, errorFile, causeFile, fixDescription)\n\nThis removes all instrumentation and saves BOTH the diagnosis and the\ncausal chain to memory. Future agents can follow the chain directly.\n\n## Causal Chains\nWhen calling `debug_cleanup`, always provide a rootCause object:\n- `trigger`: what caused the error (\"missing null check\", \"wrong import path\")\n- `errorFile`: where the error appeared (the stack trace pointed here)\n- `causeFile`: where the actual bug was (may be different!)\n- `fixDescription`: what you changed (\"added null check before .map()\")\n\nThis is the most valuable data in the system. It teaches future agents\nnot just WHAT the error was, but WHY it happened and WHERE to look.\n\n## Staleness\nEvery diagnosis is tagged with the git SHA at the time it was saved.\nWhen recalled, the system checks if the referenced files have changed.\nStale diagnoses are ranked lower but still shown \u2014 many bugs recur\neven after code changes.\n\n## Patterns\nCall `debug_patterns` periodically to see:\n- **Recurring errors**: same error type in the same file (3+ times = refactor it)\n- **Hot files**: files that keep appearing in debug sessions (fragile code)\n- **Regressions**: bugs that were fixed but came back (missing test coverage)\n- **Error clusters**: multiple errors in a short time (cascading failure)\n\n## Anti-Patterns\n- DO NOT skip Step 1 and jump to fixing. You will guess wrong.\n- DO NOT instrument 10 files at once. Start with 1-2.\n- DO NOT ignore the `nextStep` field in tool responses.\n- DO NOT leave instrumentation in place after fixing.\n- DO NOT apply a fix without running `debug_verify`.\n- DO NOT skip the `rootCause` in cleanup. It's the highest-value data.\n\n## Error Pattern Shortcuts\n- `TypeError: Cannot read properties of undefined` \u2192 check the variable one level up in the call chain\n- `ECONNREFUSED` \u2192 the server/API is not running, period\n- `Cannot find module` \u2192 run npm install, then check import path\n- `ENOENT` \u2192 the file doesn't exist, check spelling and case\n- `ERR_MODULE_NOT_FOUND` \u2192 ESM issue, check file extensions and type:module\n- `401/403` \u2192 auth problem, check token/env vars\n- `500` \u2192 server-side, look at backend logs not frontend\n";

package/dist/methodology.js

@@ -0,0 +1,100 @@
+/**
+ * methodology.ts — The debugging methodology, served as an MCP resource.
+ *
+ * This is the "hot memory" tier — always available, always loaded.
+ * It teaches the agent HOW to debug, not just gives it tools.
+ */
+export const METHODOLOGY = `# Debug Toolkit — Methodology
+
+## The Rule
+Diagnosis quality matters more than fix quality.
+A wrong diagnosis wastes 5-10 agent turns. A wrong fix wastes 1.
+Invest time understanding the error before touching the code.
+
+## The Workflow
+
+### Step 1: Investigate (ALWAYS start here)
+Call \`debug_investigate\` with the error text.
+You get back: error classification, source code at the crash site,
+git context, runtime environment, AND any past solutions for similar errors.
+
+If past solutions are returned, check the \`stale\` field:
+- \`stale: false\` → the code hasn't changed since. Trust the diagnosis.
+- \`stale: true\` → the code has changed. The diagnosis may still apply but verify.
+
+If a \`rootCause\` is included, it tells you exactly which file caused
+the error last time and what was done to fix it. Start there.
+
+### Step 2: Form Hypotheses
+Based on the investigation, form 2-3 theories about the root cause.
+Rank them by likelihood. The most common causes are:
+- Null/undefined access (TypeError)
+- Missing import or dependency (ReferenceError, ModuleNotFoundError)
+- Wrong API usage (check framework version in environment)
+- Stale state (recent git changes may have introduced it)
+- Environment mismatch (wrong Node version, missing env var)
+
+### Step 3: Probe (only if needed)
+If the investigation didn't reveal the cause, use \`debug_instrument\`
+to add logging at the suspicious code path. Then \`debug_capture\` to
+see what values flow through at runtime.
+
+Tag each instrument with a hypothesis so captures are linked.
+
+### Step 4: Fix
+Apply the minimal fix. Change as few lines as possible.
+If you're changing more than 10 lines, you probably have the wrong diagnosis.
+
+### Step 5: Verify
+Call \`debug_verify\` with the test command. Check exit code AND error output.
+Do not trust "it compiles" — silent failures are the #1 problem.
+
+### Step 6: Cleanup
+Call \`debug_cleanup\` with:
+- \`diagnosis\`: one-line root cause summary
+- \`rootCause\`: the causal chain (trigger, errorFile, causeFile, fixDescription)
+
+This removes all instrumentation and saves BOTH the diagnosis and the
+causal chain to memory. Future agents can follow the chain directly.
+
+## Causal Chains
+When calling \`debug_cleanup\`, always provide a rootCause object:
+- \`trigger\`: what caused the error ("missing null check", "wrong import path")
+- \`errorFile\`: where the error appeared (the stack trace pointed here)
+- \`causeFile\`: where the actual bug was (may be different!)
+- \`fixDescription\`: what you changed ("added null check before .map()")
+
+This is the most valuable data in the system. It teaches future agents
+not just WHAT the error was, but WHY it happened and WHERE to look.
+
+## Staleness
+Every diagnosis is tagged with the git SHA at the time it was saved.
+When recalled, the system checks if the referenced files have changed.
+Stale diagnoses are ranked lower but still shown — many bugs recur
+even after code changes.
+
+## Patterns
+Call \`debug_patterns\` periodically to see:
+- **Recurring errors**: same error type in the same file (3+ times = refactor it)
+- **Hot files**: files that keep appearing in debug sessions (fragile code)
+- **Regressions**: bugs that were fixed but came back (missing test coverage)
+- **Error clusters**: multiple errors in a short time (cascading failure)
+
+## Anti-Patterns
+- DO NOT skip Step 1 and jump to fixing. You will guess wrong.
+- DO NOT instrument 10 files at once. Start with 1-2.
+- DO NOT ignore the \`nextStep\` field in tool responses.
+- DO NOT leave instrumentation in place after fixing.
+- DO NOT apply a fix without running \`debug_verify\`.
+- DO NOT skip the \`rootCause\` in cleanup. It's the highest-value data.
+
+## Error Pattern Shortcuts
+- \`TypeError: Cannot read properties of undefined\` → check the variable one level up in the call chain
+- \`ECONNREFUSED\` → the server/API is not running, period
+- \`Cannot find module\` → run npm install, then check import path
+- \`ENOENT\` → the file doesn't exist, check spelling and case
+- \`ERR_MODULE_NOT_FOUND\` → ESM issue, check file extensions and type:module
+- \`401/403\` → auth problem, check token/env vars
+- \`500\` → server-side, look at backend logs not frontend
+`;
+//# sourceMappingURL=methodology.js.map

package/dist/methodology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methodology.js","sourceRoot":"","sources":["../src/methodology.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4F1B,CAAC"}

package/dist/proxy.d.ts

@@ -0,0 +1,12 @@
+export interface ProxyOptions {
+    targetPort: number;
+    listenPort: number;
+}
+export declare function startProxy(opts: ProxyOptions): {
+    close: () => void;
+};
+/**
+ * Detect the dev server port by watching child process output.
+ * Returns a promise that resolves with the port or rejects after timeout.
+ */
+export declare function detectPort(stdout: NodeJS.ReadableStream, timeoutMs?: number): Promise<number>;

package/dist/proxy.js

@@ -0,0 +1,168 @@
+import { createServer } from "node:http";
+import httpProxy from "http-proxy";
+import { WebSocketServer } from "ws";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { onBrowserEvent } from "./capture.js";
+import { createGunzip } from "node:zlib";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INJECTED_SCRIPT_TAG = `<script src="/__debug_toolkit/injected.js"></script>`;
+export function startProxy(opts) {
+    const { targetPort, listenPort } = opts;
+    const target = `http://127.0.0.1:${targetPort}`;
+    const proxy = httpProxy.createProxyServer({
+        target,
+        ws: true,
+        selfHandleResponse: true,
+    });
+    // Handle proxy responses: inject script into HTML
+    proxy.on("proxyRes", (proxyRes, req, res) => {
+        const contentType = proxyRes.headers["content-type"] ?? "";
+        const isHtml = contentType.includes("text/html");
+        if (!isHtml) {
+            // Pass through non-HTML responses unchanged
+            res.writeHead(proxyRes.statusCode ?? 200, proxyRes.headers);
+            proxyRes.pipe(res);
+            return;
+        }
+        // Buffer and modify HTML responses
+        const chunks = [];
+        const encoding = proxyRes.headers["content-encoding"];
+        let stream = proxyRes;
+        if (encoding === "gzip") {
+            stream = proxyRes.pipe(createGunzip());
+        }
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", () => {
+            let body = Buffer.concat(chunks).toString("utf-8");
+            // Inject our script before </body> or at end of document
+            if (body.includes("</body>")) {
+                body = body.replace("</body>", `${INJECTED_SCRIPT_TAG}\n</body>`);
+            }
+            else if (body.includes("</html>")) {
+                body = body.replace("</html>", `${INJECTED_SCRIPT_TAG}\n</html>`);
+            }
+            else {
+                body += `\n${INJECTED_SCRIPT_TAG}`;
+            }
+            // Send modified response without compression
+            const headers = { ...proxyRes.headers };
+            delete headers["content-encoding"];
+            delete headers["content-length"];
+            headers["content-length"] = String(Buffer.byteLength(body));
+            res.writeHead(proxyRes.statusCode ?? 200, headers);
+            res.end(body);
+        });
+        stream.on("error", () => {
+            // If decompression fails, pass through raw
+            res.writeHead(proxyRes.statusCode ?? 200, proxyRes.headers);
+            proxyRes.pipe(res);
+        });
+    });
+    proxy.on("error", (err, _req, res) => {
+        if (res && "writeHead" in res) {
+            res.writeHead(502, { "Content-Type": "text/plain" });
+            res.end(`debug-toolkit proxy error: ${err.message}`);
+        }
+    });
+    // HTTP server
+    const server = createServer((req, res) => {
+        // Serve our injected script
+        if (req.url === "/__debug_toolkit/injected.js") {
+            const scriptPath = join(__dirname, "injected.js");
+            try {
+                const script = readFileSync(scriptPath, "utf-8");
+                res.writeHead(200, {
+                    "Content-Type": "application/javascript",
+                    "Cache-Control": "no-cache",
+                });
+                res.end(script);
+            }
+            catch {
+                res.writeHead(404);
+                res.end("injected.js not found");
+            }
+            return;
+        }
+        // Proxy everything else
+        proxy.web(req, res);
+    });
+    // WebSocket handling
+    const wss = new WebSocketServer({ noServer: true });
+    wss.on("connection", (ws) => {
+        ws.on("message", (data) => {
+            try {
+                const event = JSON.parse(data.toString());
+                onBrowserEvent(event);
+            }
+            catch {
+                // Ignore malformed messages
+            }
+        });
+    });
+    server.on("upgrade", (req, socket, head) => {
+        // Our debug WebSocket
+        if (req.url === "/__debug_toolkit/ws") {
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                wss.emit("connection", ws, req);
+            });
+            return;
+        }
+        // Proxy all other WebSocket upgrades (e.g., HMR)
+        proxy.ws(req, socket, head);
+    });
+    // Security: bind to localhost only — never expose to network
+    server.listen(listenPort, "127.0.0.1", () => {
+        // Server started
+    });
+    return {
+        close() {
+            wss.close();
+            server.close();
+            proxy.close();
+        },
+    };
+}
+/**
+ * Detect the dev server port by watching child process output.
+ * Returns a promise that resolves with the port or rejects after timeout.
+ */
+export function detectPort(stdout, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        // Ordered from most specific to least. No greedy catch-all patterns.
+        const patterns = [
+            /https?:\/\/localhost:(\d+)/,
+            /https?:\/\/127\.0\.0\.1:(\d+)/,
+            /https?:\/\/0\.0\.0\.0:(\d+)/,
+            /https?:\/\/\[::\]:(\d+)/,
+            /listening\s+(?:on\s+)?(?:port\s+)?(\d{4,5})/i,
+            /localhost:(\d{4,5})/,
+            /127\.0\.0\.1:(\d{4,5})/,
+        ];
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error("Could not auto-detect dev server port within timeout. Use --port to specify."));
+        }, timeoutMs);
+        function onData(chunk) {
+            const text = chunk.toString();
+            for (const pattern of patterns) {
+                const match = pattern.exec(text);
+                if (match) {
+                    const port = parseInt(match[1], 10);
+                    if (port >= 1024 && port <= 65535) {
+                        cleanup();
+                        resolve(port);
+                        return;
+                    }
+                }
+            }
+        }
+        function cleanup() {
+            clearTimeout(timer);
+            stdout.removeListener("data", onData);
+        }
+        stdout.on("data", onData);
+    });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/security.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validate that a file path is within the project root.
+ * Resolves symlinks and rejects paths that escape the boundary.
+ */
+export declare function validateFilePath(filePath: string, projectRoot: string): string;
+/**
+ * Validate a command string for obvious injection attempts.
+ * We allow commands but reject chaining operators.
+ */
+export declare function validateCommand(command: string): string;
+/**
+ * Redact sensitive information from captured text.
+ */
+export declare function redactSensitiveData(text: string): string;
+/**
+ * Redact sensitive headers from captured network requests.
+ */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Ensure .debug/ is in .gitignore.
+ */
+export declare function ensureGitignore(projectRoot: string): void;
+/**
+ * Validate that an instrumentation expression is safe to inject.
+ * Prevents code injection via the expression parameter.
+ */
+export declare function validateExpression(expression: string): string;