@jshookmcp/jshook 0.2.3 → 0.2.5

package/dist/src/utils/UnifiedCacheManager.js

@@ -125,7 +125,7 @@ export class UnifiedCacheManager {
     async cleanupLargeItems() {
         logger.info('Cleaning up large caches...');
         const stats = await this.getGlobalStats();
-        const sortedCaches = stats.caches.sort((a, b) => b.size - a.size);
+        const sortedCaches = stats.caches.toSorted((a, b) => b.size - a.size);
         for (const cacheStats of sortedCaches.slice(0, 2)) {
             const cache = this.caches.get(cacheStats.name);
             if (cache?.clear) {

package/dist/src/utils/artifactRetention.js

@@ -38,7 +38,7 @@ export async function cleanupArtifacts(options) {
     if (cutoff > 0) {
         const agedOut = remaining
             .filter((entry) => entry.mtimeMs < cutoff)
-            .sort((a, b) => a.mtimeMs - b.mtimeMs);
+            .toSorted((a, b) => a.mtimeMs - b.mtimeMs);
         if (agedOut.length > 0) {
             const agedOutPaths = new Set(agedOut.map((entry) => entry.path));
             remaining = remaining.filter((entry) => !agedOutPaths.has(entry.path));
@@ -54,7 +54,7 @@ export async function cleanupArtifacts(options) {
     if (config.maxTotalBytes > 0) {
         let totalBytes = remaining.reduce((sum, entry) => sum + entry.size, 0);
         if (totalBytes > config.maxTotalBytes) {
-            const sizeCandidates = [...remaining].sort((a, b) => a.mtimeMs - b.mtimeMs);
+            const sizeCandidates = [...remaining].toSorted((a, b) => a.mtimeMs - b.mtimeMs);
             const removedPaths = new Set();
             for (const entry of sizeCandidates) {
                 if (totalBytes <= config.maxTotalBytes)

package/dist/src/utils/betterSqlite3.d.ts

@@ -0,0 +1,11 @@
+export type BetterSqlite3Issue = 'missing' | 'abi-mismatch' | 'load-failed';
+export interface BetterSqlite3ProbeResult {
+    status: 'ok' | 'missing' | 'warn';
+    detail: string;
+    version: string | null;
+    issue?: BetterSqlite3Issue;
+}
+export declare function isBetterSqlite3RelatedError(error: unknown): boolean;
+export declare function classifyBetterSqlite3Issue(error: unknown): BetterSqlite3Issue;
+export declare function formatBetterSqlite3Error(error: unknown): string;
+export declare function probeBetterSqlite3(): BetterSqlite3ProbeResult;

package/dist/src/utils/betterSqlite3.js

@@ -0,0 +1,88 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const BETTER_SQLITE3_VERSION = '12.6.2';
+const INSTALL_HINT = `pnpm add -O better-sqlite3@${BETTER_SQLITE3_VERSION}`;
+const REBUILD_HINT = 'npm rebuild better-sqlite3 --foreground-scripts';
+function extractErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export function isBetterSqlite3RelatedError(error) {
+    return /better-sqlite3|better_sqlite3\.node|NODE_MODULE_VERSION|compiled against a different Node\.js version/i.test(extractErrorMessage(error));
+}
+export function classifyBetterSqlite3Issue(error) {
+    const message = extractErrorMessage(error);
+    if (/Cannot find module 'better-sqlite3'|Cannot find package 'better-sqlite3'|better-sqlite3 is not installed/i.test(message)) {
+        return 'missing';
+    }
+    if (/better_sqlite3\.node|NODE_MODULE_VERSION|compiled against a different Node\.js version|module was compiled against/i.test(message)) {
+        return 'abi-mismatch';
+    }
+    return 'load-failed';
+}
+export function formatBetterSqlite3Error(error) {
+    const issue = classifyBetterSqlite3Issue(error);
+    const message = extractErrorMessage(error);
+    if (issue === 'missing') {
+        return `better-sqlite3 is not installed. Install the optional trace backend with \`${INSTALL_HINT}\`.`;
+    }
+    if (issue === 'abi-mismatch') {
+        return `better-sqlite3 is installed but its native binary is incompatible with the current Node.js runtime (${process.version}, ABI ${process.versions.modules}). Rebuild it with \`${REBUILD_HINT}\` or reinstall dependencies under the active Node version. Original error: ${message}`;
+    }
+    return `better-sqlite3 failed to initialize. Try \`${REBUILD_HINT}\` or reinstall dependencies under the active Node version. Original error: ${message}`;
+}
+function readBetterSqlite3Version() {
+    try {
+        const packageJsonPath = require.resolve('better-sqlite3/package.json');
+        const packageJson = require(packageJsonPath);
+        return packageJson.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function probeBetterSqlite3() {
+    const version = readBetterSqlite3Version();
+    if (!version) {
+        return {
+            status: 'missing',
+            detail: `Optional SQLite backend for trace tools is not installed. Install it with: ${INSTALL_HINT}`,
+            version: null,
+            issue: 'missing',
+        };
+    }
+    try {
+        const Database = require('better-sqlite3');
+        const db = new Database(':memory:');
+        try {
+            db.prepare('SELECT 1 AS ok').get();
+        }
+        finally {
+            db.close();
+        }
+        return {
+            status: 'ok',
+            detail: `installed (${version}) — native trace backend healthy`,
+            version,
+        };
+    }
+    catch (error) {
+        const issue = classifyBetterSqlite3Issue(error);
+        if (issue === 'missing') {
+            return {
+                status: 'missing',
+                detail: `Optional SQLite backend for trace tools is not installed. Install it with: ${INSTALL_HINT}`,
+                version,
+                issue,
+            };
+        }
+        return {
+            status: 'warn',
+            detail: `installed (${version}) but ${formatBetterSqlite3Error(error)}`,
+            version,
+            issue,
+        };
+    }
+}

package/dist/src/utils/browserExecutable.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'fs';
-import puppeteer from 'rebrowser-puppeteer-core';
+import { executablePath } from 'rebrowser-puppeteer-core';
 const ENV_KEYS = ['CHROME_PATH', 'PUPPETEER_EXECUTABLE_PATH', 'BROWSER_EXECUTABLE_PATH'];
 let cachedBrowserPath = null;
 function resolveFromEnvironment() {
@@ -13,7 +13,7 @@ function resolveFromEnvironment() {
 }
 function resolveFromPuppeteer() {
     try {
-        const candidate = puppeteer.executablePath('chrome');
+        const candidate = executablePath('chrome');
         if (candidate && existsSync(candidate)) {
             return candidate;
         }

package/dist/src/utils/cliFastPath.js

@@ -1,22 +1,21 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
 function getPackageVersion(moduleUrl) {
     try {
-        let dir = dirname(fileURLToPath(moduleUrl));
+        let dirUrl = new URL('.', moduleUrl);
         for (let i = 0; i < 5; i++) {
             try {
-                const candidate = join(dir, 'package.json');
+                const candidate = fileURLToPath(new URL('package.json', dirUrl));
                 const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
                 if (pkg.version)
                     return pkg.version;
             }
             catch {
             }
-            const parent = dirname(dir);
-            if (parent === dir)
+            const parentUrl = new URL('../', dirUrl);
+            if (parentUrl.href === dirUrl.href)
                 break;
-            dir = parent;
+            dirUrl = parentUrl;
         }
     }
     catch {
@@ -35,8 +34,6 @@ function buildHelpText(version) {
         '  Starts the MCP server by default.',
         '',
         'Common environment variables:',
-        '  OPENAI_API_KEY',
-        '  DEFAULT_LLM_PROVIDER=openai|anthropic',
         '  MCP_TRANSPORT=stdio|http',
         '  MCP_TOOL_PROFILE=search|workflow|full',
         '',

package/dist/src/utils/config.js

@@ -1,12 +1,10 @@
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 import { config as dotenvConfig } from 'dotenv';
 import { z } from 'zod';
 import { DEFAULT_SEARCH_CONFIG } from '../config/search-defaults.js';
-const currentFilename = fileURLToPath(import.meta.url);
-const currentDirname = dirname(currentFilename);
-export const projectRoot = join(currentDirname, '..', '..');
-const envPath = join(projectRoot, '.env');
+export const projectRoot = fileURLToPath(new URL('../..', import.meta.url));
+const envPath = fileURLToPath(new URL('../../.env', import.meta.url));
 let envLoaded = false;
 function loadEnvIfNeeded() {
     if (envLoaded) {
@@ -34,13 +32,6 @@ const envBool = (fallback) => z
     .optional()
     .transform((v) => (v === undefined ? fallback : v === 'true'));
 const ConfigSchema = z.object({
-    DEFAULT_LLM_PROVIDER: z.enum(['openai', 'anthropic']).optional().default('openai'),
-    OPENAI_API_KEY: z.string().optional().default(''),
-    OPENAI_MODEL: z.string().optional().default('gpt-4-turbo-preview'),
-    OPENAI_BASE_URL: z.string().optional(),
-    ANTHROPIC_API_KEY: z.string().optional().default(''),
-    ANTHROPIC_MODEL: z.string().optional().default('claude-3-5-sonnet-20241022'),
-    ANTHROPIC_BASE_URL: z.string().optional(),
     PUPPETEER_HEADLESS: envBool(false),
     PUPPETEER_TIMEOUT: envInt(30000).pipe(z.number().min(1000).max(300000)),
     PUPPETEER_EXECUTABLE_PATH: z.string().optional(),
@@ -192,19 +183,6 @@ export function getConfig() {
         : join(projectRoot, cacheDir);
     const search = buildSearchConfig();
     return {
-        llm: {
-            provider: (env.DEFAULT_LLM_PROVIDER || 'openai'),
-            openai: {
-                apiKey: env.OPENAI_API_KEY || '',
-                model: env.OPENAI_MODEL || 'gpt-4-turbo-preview',
-                baseURL: env.OPENAI_BASE_URL,
-            },
-            anthropic: {
-                apiKey: env.ANTHROPIC_API_KEY || '',
-                model: env.ANTHROPIC_MODEL || 'claude-3-5-sonnet-20241022',
-                baseURL: env.ANTHROPIC_BASE_URL,
-            },
-        },
         puppeteer: {
             headless: parsed.success
                 ? env.PUPPETEER_HEADLESS

package/dist/src/utils/environmentDoctor.js

@@ -5,22 +5,30 @@ 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';
+import { probeBetterSqlite3 } from './betterSqlite3.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 gitCommand = await checkCommand('git', ['--version']);
+    const pythonCommand = await checkCommand('python', ['--version']);
+    const pnpmCommand = await checkPnpmCommand();
+    const corepackCommand = normalizeCorepackCheck(await checkCommand('corepack', ['--version']), pnpmCommand);
     const packages = [
         checkPackage('@modelcontextprotocol/sdk'),
         checkPackage('rebrowser-puppeteer-core'),
+        checkBetterSqlite3(),
         checkPackage('camoufox-js', 'Optional Firefox anti-detect driver'),
         checkPackage('playwright-core', 'Optional browser automation dependency'),
+        checkNativeMemory(),
     ];
     const commands = [
-        await checkCommand('git', ['--version']),
-        await checkCommand('python', ['--version']),
-        await checkCommand('pnpm', ['--version']),
+        gitCommand,
+        pythonCommand,
+        pnpmCommand,
+        corepackCommand,
         ...Object.entries(externalResults).map(([name, result]) => ({
             name,
             status: (result.available ? 'ok' : 'missing'),
@@ -127,17 +135,118 @@ function checkPackage(packageName, missingHint) {
         };
     }
 }
-async function checkCommand(command, args) {
+function checkBetterSqlite3() {
+    const result = probeBetterSqlite3();
+    return {
+        name: 'better-sqlite3',
+        status: result.status,
+        detail: result.detail,
+    };
+}
+function isPnpmOperational(pnpm) {
+    return pnpm.status === 'ok' || pnpm.detail.includes('npx fallback works');
+}
+async function checkPnpmCommand() {
+    const direct = await checkCommand('pnpm', ['--version']);
+    if (direct.status === 'ok') {
+        return direct;
+    }
+    const npxFallback = await checkCommand('npx', ['pnpm', '--version'], 10_000);
+    if (npxFallback.status === 'ok') {
+        return {
+            name: 'pnpm',
+            status: 'warn',
+            detail: `direct pnpm command unavailable; npx fallback works (${npxFallback.detail})`,
+        };
+    }
+    return direct;
+}
+function normalizeCorepackCheck(corepack, pnpm) {
+    if (corepack.status !== 'missing' || !isPnpmOperational(pnpm)) {
+        return corepack;
+    }
+    return {
+        name: corepack.name,
+        status: 'warn',
+        detail: process.platform === 'win32'
+            ? pnpm.detail.includes('npx fallback works')
+                ? 'corepack not found; use `npx pnpm` directly (common with nvm4w-managed Node on Windows)'
+                : 'corepack not found; standalone pnpm is available (common with nvm4w-managed Node on Windows)'
+            : pnpm.detail.includes('npx fallback works')
+                ? 'corepack not found; use `npx pnpm` directly'
+                : 'corepack not found; standalone pnpm is available',
+    };
+}
+function checkNativeMemory() {
+    try {
+        const koffiPkg = require.resolve('koffi/package.json');
+        const koffiJson = require(koffiPkg);
+        const koffiVersion = koffiJson.version ?? 'unknown';
+        if (process.platform === 'win32') {
+            return {
+                name: 'native-memory',
+                status: 'ok',
+                detail: `koffi ${koffiVersion} — Win32 kernel32.dll available`,
+            };
+        }
+        if (process.platform === 'darwin') {
+            try {
+                const koffi = require('koffi');
+                const lib = koffi.load('/usr/lib/libSystem.B.dylib');
+                lib.unload();
+                return {
+                    name: 'native-memory',
+                    status: 'ok',
+                    detail: `koffi ${koffiVersion} — macOS libSystem.B.dylib available (Mach APIs need root + SIP config)`,
+                };
+            }
+            catch {
+                return {
+                    name: 'native-memory',
+                    status: 'warn',
+                    detail: `koffi ${koffiVersion} installed but cannot load libSystem.B.dylib`,
+                };
+            }
+        }
+        return {
+            name: 'native-memory',
+            status: 'warn',
+            detail: `koffi ${koffiVersion} — no native FFI memory provider for ${process.platform} (proc-based ops available on Linux)`,
+        };
+    }
+    catch {
+        return {
+            name: 'native-memory',
+            status: 'missing',
+            detail: 'koffi not installed — native memory tools unavailable. Install with: pnpm add koffi',
+        };
+    }
+}
+async function checkCommand(command, args, timeout = 4000) {
     try {
         const { stdout, stderr } = await execFileAsync(command, args, {
-            timeout: 4000,
+            timeout,
             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);
+        let finalError = error;
+        if (process.platform === 'win32') {
+            try {
+                const { stdout, stderr } = await execFileAsync('cmd', ['/c', command, ...args], {
+                    timeout,
+                    windowsHide: true,
+                });
+                const detail = `${stdout || stderr}`.trim().split(/\r?\n/)[0] || 'available';
+                return { name: command, status: 'ok', detail: `${detail} (via cmd)` };
+            }
+            catch (cmdError) {
+                finalError = cmdError;
+            }
+        }
+        const detail = finalError instanceof Error ? finalError.message : String(finalError);
         const missing = /ENOENT|not recognized|not found/i.test(detail);
         return {
             name: command,
@@ -168,25 +277,43 @@ async function checkHttpEndpoint(name, url) {
 }
 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 === 'darwin') {
+        limitations.push('26 cross-platform memory tools available (scan, pointer-chain, structure-analysis, heap). ' +
+            '15 Windows-only tools unavailable (PE analysis, anti-cheat, code injection, speedhack, hardware breakpoints).');
+        limitations.push('Native memory operations (mach_vm_read/write) require root privileges and may require SIP configuration on ARM64.');
     }
-    if (process.platform === 'linux') {
+    else if (process.platform === 'linux') {
+        limitations.push('Process management available via /proc. Native FFI memory provider not implemented — memory read/write uses /proc/pid/mem (requires root or CAP_SYS_PTRACE).');
         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.');
+    else if (process.platform !== 'win32') {
+        limitations.push(`Platform ${process.platform} is not supported for native memory operations. Use Windows or macOS.`);
     }
     return limitations;
 }
 function buildRecommendations(packages, commands, bridges, limitations) {
     const recommendations = [];
+    const pnpmCommand = commands.find((item) => item.name === 'pnpm');
+    const corepackCommand = commands.find((item) => item.name === 'corepack');
+    if (packages.some((item) => item.name === 'better-sqlite3' && item.status !== 'ok')) {
+        recommendations.push('Install or rebuild the optional SQLite trace backend with `pnpm add -O better-sqlite3@12.6.2` or `npm rebuild better-sqlite3 --foreground-scripts` under the active Node version if you need trace tooling.');
+    }
     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 (pnpmCommand && !isPnpmOperational(pnpmCommand)) {
+        recommendations.push('Install pnpm or enable Corepack (`corepack enable`) before running package-management workflows.');
+    }
+    else if (pnpmCommand?.detail.includes('npx fallback works')) {
+        recommendations.push('Use `npx pnpm` directly on this machine or repair the local pnpm/Corepack shim if scripts expect bare `pnpm`.');
+    }
+    else if (corepackCommand?.status === 'warn' &&
+        corepackCommand.detail.includes('standalone pnpm')) {
+        recommendations.push('Use `pnpm` or `npx pnpm` directly on this machine; `corepack` is optional and may be absent on nvm4w-managed Windows installs.');
+    }
     if (bridges.some((item) => item.status !== 'ok')) {
         recommendations.push('Check local bridge endpoints (Ghidra / IDA / Burp) before relying on native-bridge workflows.');
     }

package/dist/src/utils/outputPaths.js

@@ -1,9 +1,14 @@
 import { mkdir } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, normalize, relative, resolve, sep, } from 'node:path';
 import { fileURLToPath } from 'node:url';
-const currentFile = fileURLToPath(import.meta.url);
-const currentDir = dirname(currentFile);
-const projectRoot = resolve(currentDir, '..', '..');
+const defaultProjectRoot = fileURLToPath(new URL('../..', import.meta.url));
+function resolveProjectRoot(env = process.env) {
+    const requestedRoot = env.MCP_PROJECT_ROOT?.trim();
+    if (!requestedRoot) {
+        return defaultProjectRoot;
+    }
+    return normalize(isAbsolute(requestedRoot) ? requestedRoot : resolve(defaultProjectRoot, requestedRoot));
+}
 function isInside(baseDir, targetPath) {
     const rel = relative(baseDir, targetPath);
     if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
@@ -11,11 +16,11 @@ function isInside(baseDir, targetPath) {
     }
     return true;
 }
-function resolveWithinProject(inputPath) {
-    const candidate = isAbsolute(inputPath) ? normalize(inputPath) : resolve(projectRoot, inputPath);
-    return isInside(projectRoot, candidate)
+function resolveWithinProject(inputPath, baseRoot = getProjectRoot()) {
+    const candidate = isAbsolute(inputPath) ? normalize(inputPath) : resolve(baseRoot, inputPath);
+    return isInside(baseRoot, candidate)
         ? candidate
-        : resolve(projectRoot, 'screenshots', 'external', normalize(inputPath).split(/[\\/]/).pop() || 'output.bin');
+        : resolve(baseRoot, 'screenshots', 'external', normalize(inputPath).split(/[\\/]/).pop() || 'output.bin');
 }
 function withDefaultExtension(filePath, extension) {
     if (extname(filePath)) {
@@ -24,20 +29,22 @@ function withDefaultExtension(filePath, extension) {
     return `${filePath}.${extension.replace(/^\./, '')}`;
 }
 export function getProjectRoot() {
-    return projectRoot;
+    return resolveProjectRoot();
 }
 export function resolveOutputDirectory(inputDir, fallbackDir = 'screenshots') {
+    const projectRoot = getProjectRoot();
     const requested = inputDir?.trim();
     if (!requested) {
         return resolve(projectRoot, fallbackDir);
     }
-    const resolved = resolveWithinProject(requested);
+    const resolved = resolveWithinProject(requested, projectRoot);
     if (isInside(projectRoot, resolved)) {
         return resolved;
     }
     return resolve(projectRoot, fallbackDir);
 }
 export async function resolveScreenshotOutputPath(options) {
+    const projectRoot = getProjectRoot();
     const extension = options.type === 'jpeg' ? 'jpg' : 'png';
     const fallbackDir = options.fallbackDir || 'screenshots/manual';
     const fallbackName = options.fallbackName || 'page';

package/dist/src/utils/parallel.js

@@ -44,9 +44,7 @@ export async function parallelExecute(items, executor, options = {}) {
                 duration: Date.now() - startTime,
             };
         })();
-        const wrappedTask = task.then(() => {
-            executing.delete(wrappedTask);
-        }, () => {
+        const wrappedTask = task.finally(() => {
             executing.delete(wrappedTask);
         });
         executing.add(wrappedTask);