@jshookmcp/jshook 0.1.3 → 0.1.5

package/dist/utils/environmentDoctor.js

@@ -0,0 +1,195 @@
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { ToolRegistry } from '../modules/external/ToolRegistry.js';
+import { GHIDRA_BRIDGE_ENDPOINT, IDA_BRIDGE_ENDPOINT } from '../constants.js';
+import { getProjectRoot } from './outputPaths.js';
+import { getArtifactRetentionConfig } from './artifactRetention.js';
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+export async function runEnvironmentDoctor(options) {
+    const includeBridgeHealth = options?.includeBridgeHealth ?? true;
+    const registry = new ToolRegistry();
+    const externalResults = await registry.probeAll(true);
+    const packages = [
+        checkPackage('@modelcontextprotocol/sdk'),
+        checkPackage('rebrowser-puppeteer-core'),
+        checkPackage('camoufox-js', 'Optional Firefox anti-detect driver'),
+        checkPackage('playwright-core', 'Optional browser automation dependency'),
+    ];
+    const commands = [
+        await checkCommand('git', ['--version']),
+        await checkCommand('python', ['--version']),
+        await checkCommand('pnpm', ['--version']),
+        ...Object.entries(externalResults).map(([name, result]) => ({
+            name,
+            status: (result.available ? 'ok' : 'missing'),
+            detail: result.available
+                ? `${result.path ?? 'PATH'}${result.version ? ` (${result.version})` : ''}`
+                : result.reason ?? 'Unavailable',
+        })),
+    ];
+    const bridges = includeBridgeHealth
+        ? await Promise.all([
+            checkHttpEndpoint('ghidra-bridge', `${GHIDRA_BRIDGE_ENDPOINT.replace(/\/$/, '')}/health`),
+            checkHttpEndpoint('ida-bridge', `${IDA_BRIDGE_ENDPOINT.replace(/\/$/, '')}/health`),
+            checkHttpEndpoint('burp-mcp-sse', process.env.BURP_MCP_SSE_URL?.trim() || 'http://127.0.0.1:9876'),
+        ])
+        : [];
+    const limitations = buildPlatformLimitations();
+    const recommendations = buildRecommendations(packages, commands, bridges, limitations);
+    const success = [...packages, ...commands, ...bridges].every((item) => item.status !== 'error');
+    return {
+        success,
+        generatedAt: new Date().toISOString(),
+        runtime: {
+            platform: process.platform,
+            arch: process.arch,
+            node: process.version,
+            cwd: process.cwd(),
+            projectRoot: getProjectRoot(),
+        },
+        packages,
+        commands,
+        bridges,
+        config: {
+            transport: (process.env.MCP_TRANSPORT ?? 'stdio').toLowerCase(),
+            toolProfile: (process.env.MCP_TOOL_PROFILE ?? 'search').toLowerCase(),
+            pluginRoots: process.env.MCP_PLUGIN_ROOTS ?? '<jshook-install>/plugins',
+            workflowRoots: process.env.MCP_WORKFLOW_ROOTS ?? '<jshook-install>/workflows',
+            pluginSignatureRequired: process.env.MCP_PLUGIN_SIGNATURE_REQUIRED ?? (process.env.NODE_ENV === 'production' ? 'true (production default)' : 'false'),
+            pluginStrictLoad: process.env.MCP_PLUGIN_STRICT_LOAD ?? (process.env.NODE_ENV === 'production' ? 'true (production default)' : 'false'),
+            artifactRetention: getArtifactRetentionConfig(),
+        },
+        limitations,
+        recommendations,
+    };
+}
+export function formatEnvironmentDoctorReport(report) {
+    const lines = [];
+    lines.push(`JSHook Environment Doctor — ${report.generatedAt}`);
+    lines.push('');
+    lines.push(`Runtime: ${report.runtime.platform} ${report.runtime.arch} | Node ${report.runtime.node}`);
+    lines.push(`CWD: ${report.runtime.cwd}`);
+    lines.push(`Project root: ${report.runtime.projectRoot}`);
+    lines.push('');
+    lines.push('Packages:');
+    for (const item of report.packages)
+        lines.push(`- [${item.status}] ${item.name}: ${item.detail}`);
+    lines.push('');
+    lines.push('Commands:');
+    for (const item of report.commands)
+        lines.push(`- [${item.status}] ${item.name}: ${item.detail}`);
+    if (report.bridges.length > 0) {
+        lines.push('');
+        lines.push('Bridge health:');
+        for (const item of report.bridges)
+            lines.push(`- [${item.status}] ${item.name}: ${item.detail}`);
+    }
+    lines.push('');
+    lines.push('Config:');
+    for (const [key, value] of Object.entries(report.config)) {
+        lines.push(`- ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    }
+    if (report.limitations.length > 0) {
+        lines.push('');
+        lines.push('Platform limitations:');
+        for (const item of report.limitations)
+            lines.push(`- ${item}`);
+    }
+    if (report.recommendations.length > 0) {
+        lines.push('');
+        lines.push('Recommendations:');
+        for (const item of report.recommendations)
+            lines.push(`- ${item}`);
+    }
+    lines.push('');
+    lines.push(`Overall: ${report.success ? 'ok' : 'review warnings above'}`);
+    return lines.join('\n');
+}
+function checkPackage(packageName, missingHint) {
+    try {
+        const packageJsonPath = require.resolve(`${packageName}/package.json`);
+        const packageJson = require(packageJsonPath);
+        return {
+            name: packageName,
+            status: 'ok',
+            detail: packageJson.version ? `installed (${packageJson.version})` : 'installed',
+        };
+    }
+    catch {
+        return {
+            name: packageName,
+            status: 'missing',
+            detail: missingHint ?? 'Not installed',
+        };
+    }
+}
+async function checkCommand(command, args) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, {
+            timeout: 4000,
+            windowsHide: true,
+        });
+        const detail = `${stdout || stderr}`.trim().split(/\r?\n/)[0] || 'available';
+        return { name: command, status: 'ok', detail };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const missing = /ENOENT|not recognized|not found/i.test(detail);
+        return {
+            name: command,
+            status: missing ? 'missing' : 'warn',
+            detail,
+        };
+    }
+}
+async function checkHttpEndpoint(name, url) {
+    try {
+        const res = await fetch(url, {
+            method: 'GET',
+            signal: AbortSignal.timeout(3000),
+        });
+        return {
+            name,
+            status: res.ok ? 'ok' : 'warn',
+            detail: `${url} -> HTTP ${res.status}`,
+        };
+    }
+    catch (error) {
+        return {
+            name,
+            status: 'warn',
+            detail: `${url} -> ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function buildPlatformLimitations() {
+    const limitations = [];
+    if (process.platform !== 'win32') {
+        limitations.push('Memory write / injection tools are Windows-only; on Linux/macOS prefer browser hooks, network capture, or Frida-based alternatives.');
+    }
+    if (process.platform === 'linux') {
+        limitations.push('Camoufox runs on Linux, but some Chrome/CDP-heavy workflows are better served by the Chrome driver.');
+    }
+    if (process.platform === 'darwin') {
+        limitations.push('macOS users should expect some Windows-native process tooling to be unavailable.');
+    }
+    return limitations;
+}
+function buildRecommendations(packages, commands, bridges, limitations) {
+    const recommendations = [];
+    if (packages.some((item) => item.name === 'camoufox-js' && item.status !== 'ok')) {
+        recommendations.push('Install optional browser dependencies with `pnpm run install:full` if you need Camoufox support.');
+    }
+    if (commands.some((item) => item.name.startsWith('wabt.') && item.status !== 'ok')) {
+        recommendations.push('Install wabt if you need full WASM disassembly/decompilation; otherwise the server will stay in basic mode.');
+    }
+    if (bridges.some((item) => item.status !== 'ok')) {
+        recommendations.push('Check local bridge endpoints (Ghidra / IDA / Burp) before relying on native-bridge workflows.');
+    }
+    if (limitations.length > 0) {
+        recommendations.push('Review platform limitations before using process/memory tooling on non-Windows hosts.');
+    }
+    return recommendations;
+}

package/dist/utils/logger.d.ts

@@ -13,4 +13,3 @@ declare class Logger {
 }
 export declare const logger: Logger;
 export {};
-//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.js

@@ -63,4 +63,3 @@ class Logger {
     }
 }
 export const logger = new Logger(process.env.LOG_LEVEL || 'info');
-//# sourceMappingURL=logger.js.map

package/dist/utils/outputPaths.d.ts

@@ -10,4 +10,3 @@ export declare function resolveScreenshotOutputPath(options: {
     displayPath: string;
     pathRewritten: boolean;
 }>;
-//# sourceMappingURL=outputPaths.d.ts.map

package/dist/utils/outputPaths.js

@@ -68,4 +68,3 @@ export async function resolveScreenshotOutputPath(options) {
         : relative(projectRoot, absolutePath).replace(/\\/g, '/');
     return { absolutePath, displayPath, pathRewritten };
 }
-//# sourceMappingURL=outputPaths.js.map

package/dist/utils/parallel.d.ts

@@ -37,4 +37,3 @@ export declare class RateLimiter {
     acquire(tokens?: number): Promise<void>;
     getTokens(): number;
 }
-//# sourceMappingURL=parallel.d.ts.map

package/dist/utils/parallel.js

@@ -146,4 +146,3 @@ export class RateLimiter {
         return this.tokens;
     }
 }
-//# sourceMappingURL=parallel.js.map

package/package.json

@@ -1,115 +1,135 @@
-{
-  "name": "@jshookmcp/jshook",
-  "version": "0.1.3",
-  "packageManager": "pnpm@10.28.2",
-  "description": "MCP server with 242 built-in tools (234 domain tools across 16 domains) for AI-assisted JavaScript analysis and security analysis — browser automation, CDP debugging, network monitoring, JS hooks, code analysis, and workflow orchestration",
-  "mcpName": "io.github.vmoranv/jshookmcp",
-  "main": "dist/index.js",
-  "type": "module",
-  "files": [
-    "dist",
-    "src/native/scripts"
-  ],
-  "bin": {
-    "jshook": "dist/index.js",
-    "jshookmcp": "dist/index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vmoranv/jshookmcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/vmoranv/jshookmcp/issues"
-  },
-  "homepage": "https://github.com/vmoranv/jshookmcp#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json --resolve-full-paths && pnpm -C packages/extension-sdk build && node scripts/copy-native-scripts.mjs",
-    "typecheck": "tsc --noEmit -p tsconfig.json && pnpm -C packages/extension-sdk typecheck",
-    "dev": "tsx --conditions=development watch src/index.ts",
-    "start": "node dist/index.js",
-    "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "test": "vitest run",
-    "prepare": "pnpm run build",
-    "audit:tools": "node scripts/audit-tools.mjs",
-    "check": "pnpm run lint && pnpm run typecheck && pnpm run test",
-    "package": "pnpm pack",
-    "prepublishOnly": "pnpm run check",
-    "install:full": "pnpm install && pnpm exec camoufox-js fetch"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "javascript",
-    "javascript-analysis",
-    "security-analysis",
-    "hook",
-    "hooking",
-    "deobfuscation",
-    "ai",
-    "claude",
-    "puppeteer",
-    "chrome-devtools",
-    "debugger",
-    "web-scraping",
-    "anti-detection",
-    "captcha",
-    "browser-automation",
-    "network-monitoring",
-    "ast",
-    "obfuscation",
-    "cryptography-detection",
-    "code-analysis"
-  ],
-  "author": {
-    "name": "vmoranv",
-    "url": "https://github.com/vmoranv"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.78.0",
-    "@babel/generator": "^7.29.1",
-    "@babel/parser": "^7.29.0",
-    "@babel/traverse": "^7.29.0",
-    "@babel/types": "^7.29.0",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
-    "dotenv": "^17.3.1",
-    "koffi": "^2.15.1",
-    "openai": "^6.25.0",
-    "ora": "^9.3.0",
-    "rebrowser-puppeteer-core": "^24.8.1",
-    "zod": "^4.3.6"
-  },
-  "optionalDependencies": {
-    "camoufox-js": "^0.9.1",
-    "playwright-core": "^1.58.2"
-  },
-  "devDependencies": {
-    "@types/babel__generator": "^7.27.0",
-    "@types/babel__traverse": "^7.28.0",
-    "@types/node": "^25.3.0",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "eslint": "^10.0.2",
-    "nodemon": "^3.1.14",
-    "prettier": "^3.8.1",
-    "tsc-alias": "^1.8.16",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "better-sqlite3"
-    ]
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}
+{
+  "name": "@jshookmcp/jshook",
+  "version": "0.1.5",
+  "packageManager": "pnpm@10.28.2",
+  "description": "MCP server with 244 built-in tools (236 domain tools across 16 domains) for AI-assisted JavaScript analysis and security analysis — browser automation, CDP debugging, network monitoring, JS hooks, code analysis, and workflow orchestration",
+  "mcpName": "io.github.vmoranv/jshookmcp",
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "dist",
+    "src/native/scripts"
+  ],
+  "bin": {
+    "jshook": "dist/index.js",
+    "jshookmcp": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vmoranv/jshookmcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vmoranv/jshookmcp/issues"
+  },
+  "homepage": "https://github.com/vmoranv/jshookmcp#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json && tsc-alias -p tsconfig.json --resolve-full-paths && pnpm -C packages/extension-sdk build && node scripts/copy-native-scripts.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && pnpm -C packages/extension-sdk typecheck",
+    "dev": "tsx --conditions=development watch src/index.ts",
+    "start": "node dist/index.js",
+    "doctor": "tsx src/cli/doctor.ts",
+    "docs:generate": "node scripts/generate-vitepress-reference.mjs && prettier \"docs/reference/**/*.md\" \"docs/en/reference/**/*.md\" --write",
+    "docs:dev": "vitepress dev docs --host 127.0.0.1 --port 5173",
+    "docs:build": "pnpm run docs:generate && vitepress build docs",
+    "docs:preview": "vitepress preview docs --host 127.0.0.1 --port 4173",
+    "lint:md": "pnpm dlx markdownlint-cli2",
+    "format:docs": "pnpm run docs:generate && prettier docs .github README.md README.zh.md CONTRIBUTING.md --write",
+    "check:docs-format": "prettier docs .github README.md README.zh.md CONTRIBUTING.md --check",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "vitest run",
+    "prepack": "pnpm run build",
+    "audit:tools": "node scripts/audit-tools.mjs",
+    "check": "pnpm run lint && pnpm run typecheck && pnpm run test",
+    "package": "pnpm pack",
+    "prepublishOnly": "pnpm run check",
+    "install:full": "pnpm install && pnpm exec camoufox-js fetch"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "javascript",
+    "javascript-analysis",
+    "security-analysis",
+    "hook",
+    "hooking",
+    "deobfuscation",
+    "ai",
+    "claude",
+    "puppeteer",
+    "chrome-devtools",
+    "debugger",
+    "web-scraping",
+    "anti-detection",
+    "captcha",
+    "browser-automation",
+    "network-monitoring",
+    "ast",
+    "obfuscation",
+    "cryptography-detection",
+    "code-analysis"
+  ],
+  "author": {
+    "name": "vmoranv",
+    "url": "https://github.com/vmoranv"
+  },
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@babel/generator": "^7.29.1",
+    "@babel/parser": "^7.29.0",
+    "@babel/traverse": "^7.29.0",
+    "@babel/types": "^7.29.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "koffi": "^2.15.1",
+    "openai": "^6.25.0",
+    "ora": "^9.3.0",
+    "rebrowser-puppeteer-core": "^24.8.1",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "camoufox-js": "^0.9.1",
+    "playwright-core": "^1.58.2"
+  },
+  "devDependencies": {
+    "@types/babel__generator": "^7.27.0",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^10.0.2",
+    "estree-walker": "^2.0.2",
+    "nodemon": "^3.1.14",
+    "prettier": "^3.8.1",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitepress": "1.6.4",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "overrides": {
+      "hono": "4.12.5",
+      "@hono/node-server": "1.19.11",
+      "express-rate-limit": "8.3.0",
+      "basic-ftp": "5.2.0",
+      "minimatch": "10.2.4",
+      "esbuild": "0.27.3"
+    },
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "koffi"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/native/scripts/linux/enum-windows.sh

@@ -1,12 +1,12 @@
-#!/bin/bash
-# enum-windows.sh
-# Linux window enumeration script (placeholder)
-
-TARGET_PID=$1
-
-# Use xdotool or wmctrl for window enumeration
-# This is a placeholder for future implementation
-
-if command -v xdotool &> /dev/null; then
-    xdotool search --pid "$TARGET_PID" --name "" get-window-name
-fi
+#!/bin/bash
+# enum-windows.sh
+# Linux window enumeration script (placeholder)
+
+TARGET_PID=$1
+
+# Use xdotool or wmctrl for window enumeration
+# This is a placeholder for future implementation
+
+if command -v xdotool &> /dev/null; then
+    xdotool search --pid "$TARGET_PID" --name "" get-window-name
+fi

package/src/native/scripts/macos/darwin/{process-list.py → process_list.py}

@@ -4,6 +4,7 @@
 """
 
 # pyright: reportMissingImports=false
+# pylint: disable=import-error,invalid-name
 import json
 import Quartz  # type: ignore[import-not-found]
 

package/src/native/scripts/macos/enum-windows.applescript

@@ -1,22 +1,22 @@
--- enum-windows.applescript
--- macOS window enumeration script (placeholder)
-
-param TargetPid
-
--- AppleScript implementation for window enumeration
--- This is a placeholder for future implementation
-
-tell application "System Events"
-    set windowList to {}
-    repeat with proc in (every process whose unix id is TargetPid)
-        repeat with win in windows of proc
-            set end of windowList to {¬
-                title: name of win, ¬
-                position: position of win, ¬
-                size: size of win ¬
-            }
-        end repeat
-    end repeat
-end tell
-
-return windowList
+-- enum-windows.applescript
+-- macOS window enumeration script (placeholder)
+
+param TargetPid
+
+-- AppleScript implementation for window enumeration
+-- This is a placeholder for future implementation
+
+tell application "System Events"
+    set windowList to {}
+    repeat with proc in (every process whose unix id is TargetPid)
+        repeat with win in windows of proc
+            set end of windowList to {¬
+                title: name of win, ¬
+                position: position of win, ¬
+                size: size of win ¬
+            }
+        end repeat
+    end repeat
+end tell
+
+return windowList