@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/tests/modules/detector/ObfuscationDetector.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('@src/modules/deobfuscator/JSVMPDeobfuscator', () => {
+    return {
+        JSVMPDeobfuscator: class {
+            detectJSVMP(code) {
+                if (code.includes('vmhit')) {
+                    return {
+                        instructionCount: 64,
+                        interpreterLocation: 'line:10',
+                        complexity: 'high',
+                        hasSwitch: true,
+                        hasInstructionArray: true,
+                        hasProgramCounter: true,
+                    };
+                }
+                throw new Error('not-vm');
+            }
+        },
+    };
+});
+import { ObfuscationDetector } from '../../../src/modules/detector/ObfuscationDetector.js';
+describe('ObfuscationDetector', () => {
+    it('returns unknown for clean code', () => {
+        const detector = new ObfuscationDetector();
+        const result = detector.detect('const answer = 42;');
+        expect(result.types).toEqual(['unknown']);
+        expect(result.confidence.unknown).toBe(0.5);
+    });
+    it('detects webpack obfuscation pattern', () => {
+        const detector = new ObfuscationDetector();
+        const result = detector.detect('function x(){ return __webpack_require__(1); }');
+        expect(result.types).toContain('webpack');
+    });
+    it('detects JSFuck payload', () => {
+        const detector = new ObfuscationDetector();
+        const jsfuck = '[](!+[]+!![])[+!![]]';
+        const result = detector.detect(jsfuck);
+        expect(result.types).toContain('jsfuck');
+    });
+    it('uses direct VM detection result when available', () => {
+        const detector = new ObfuscationDetector();
+        const result = detector.detect('vmhit');
+        expect(result.types).toContain('vm-protection');
+        expect(result.vmFeatures?.instructionCount).toBe(64);
+        expect(result.features.some((f) => f.includes('JSVMP'))).toBe(true);
+    });
+    it('falls back to heuristic VM detection when parser throws', () => {
+        const detector = new ObfuscationDetector();
+        const heuristicVmCode = `
+      while (true) {
+        switch (state) {
+          case 0: state = vm[pc++]; break;
+        }
+      }
+      var vm = [1,2,3,4,5,6,7,8,9,10,11,12];
+    `;
+        const result = detector.detect(heuristicVmCode);
+        expect(result.types).toContain('vm-protection');
+        expect(result.vmFeatures?.interpreterLocation).toBe('Unknown');
+    });
+    it('generateReport includes types, features and recommendations', () => {
+        const detector = new ObfuscationDetector();
+        const detected = detector.detect('eval(function(p,a,c,k,e,d){})');
+        const report = detector.generateReport(detected);
+        expect(report).toContain('Obfuscation Detection Report');
+        expect(report).toContain('Detected Types');
+        expect(report).toContain('Recommendations');
+    });
+});

package/dist/tests/modules/emulator/AIEnvironmentAnalyzer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/emulator/AIEnvironmentAnalyzer.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+const promptState = vi.hoisted(() => ({
+    generateBrowserEnvAnalysisMessages: vi.fn(() => [{ role: 'user', content: 'analyze' }]),
+    generateAntiCrawlAnalysisMessages: vi.fn(() => [{ role: 'user', content: 'anti' }]),
+    generateAPIImplementationMessages: vi.fn(() => [{ role: 'user', content: 'api' }]),
+    generateEnvironmentSuggestionsMessages: vi.fn(() => [{ role: 'user', content: 'suggest' }]),
+}));
+vi.mock('@src/services/prompts/environment', () => ({
+    generateBrowserEnvAnalysisMessages: promptState.generateBrowserEnvAnalysisMessages,
+    generateAntiCrawlAnalysisMessages: promptState.generateAntiCrawlAnalysisMessages,
+    generateAPIImplementationMessages: promptState.generateAPIImplementationMessages,
+    generateEnvironmentSuggestionsMessages: promptState.generateEnvironmentSuggestionsMessages,
+}));
+vi.mock('@src/utils/logger', () => ({
+    logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+    },
+}));
+import { AIEnvironmentAnalyzer } from '../../../src/modules/emulator/AIEnvironmentAnalyzer.js';
+const detectedBase = {
+    window: [],
+    document: [],
+    navigator: [],
+    location: [],
+    screen: [],
+    other: [],
+};
+describe('AIEnvironmentAnalyzer', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('returns empty result when LLM is unavailable', async () => {
+        const analyzer = new AIEnvironmentAnalyzer();
+        const result = await analyzer.analyze('window.x', detectedBase, []);
+        expect(result).toEqual({
+            recommendedVariables: {},
+            recommendedAPIs: [],
+            antiCrawlFeatures: [],
+            suggestions: [],
+            confidence: 0,
+        });
+    });
+    it('parses fenced JSON analysis response', async () => {
+        const llm = {
+            chat: vi.fn().mockResolvedValue({
+                content: `\`\`\`json
+{"recommendedVariables":{"window.foo":"bar"},"recommendedAPIs":[{"path":"window.fetch","implementation":"function(){}","reason":"needed"}],"antiCrawlFeatures":[{"feature":"fp","severity":"high","description":"x","mitigation":"y"}],"suggestions":["a"],"confidence":0.88}
+\`\`\``,
+            }),
+        };
+        const analyzer = new AIEnvironmentAnalyzer(llm);
+        const result = await analyzer.analyze('window.foo', detectedBase, []);
+        expect(llm.chat).toHaveBeenCalledOnce();
+        expect(result.recommendedVariables['window.foo']).toBe('bar');
+        expect(result.recommendedAPIs[0]?.path).toBe('window.fetch');
+        expect(result.confidence).toBe(0.88);
+    });
+    it('falls back to empty result on invalid JSON', async () => {
+        const llm = {
+            chat: vi.fn().mockResolvedValue({ content: 'not-json-response' }),
+        };
+        const analyzer = new AIEnvironmentAnalyzer(llm);
+        const result = await analyzer.analyze('window.foo', detectedBase, []);
+        expect(result.confidence).toBe(0);
+        expect(result.recommendedAPIs).toEqual([]);
+    });
+    it('extracts anti-crawl list from JSON array response', async () => {
+        const llm = {
+            chat: vi.fn().mockResolvedValue({
+                content: `\`\`\`json
+[{"feature":"webdriver","severity":"critical","description":"d","mitigation":"m"}]
+\`\`\``,
+            }),
+        };
+        const analyzer = new AIEnvironmentAnalyzer(llm);
+        const features = await analyzer.analyzeAntiCrawl('navigator.webdriver');
+        expect(features).toHaveLength(1);
+        expect(features[0]?.feature).toBe('webdriver');
+    });
+    it('infers API implementation from fenced code block', async () => {
+        const llm = {
+            chat: vi.fn().mockResolvedValue({
+                content: '```js\nfunction test(){ return 1; }\n```',
+            }),
+        };
+        const analyzer = new AIEnvironmentAnalyzer(llm);
+        const impl = await analyzer.inferAPIImplementation('window.test', 'ctx');
+        expect(impl).toBe('function test(){ return 1; }');
+    });
+    it('generates default suggestions when LLM output is unusable', async () => {
+        const llm = {
+            chat: vi.fn().mockResolvedValue({ content: '{"unexpected":true}' }),
+        };
+        const analyzer = new AIEnvironmentAnalyzer(llm);
+        const suggestions = await analyzer.generateSuggestions({
+            ...detectedBase,
+            window: ['window.browserRuntime'],
+            navigator: ['navigator.webdriver', 'navigator.plugins'],
+        }, new Array(11).fill({}), 'browser');
+        expect(suggestions).toContain('11 browser APIs missing, enable API emulation');
+        expect(suggestions).toContain('webdriver flag detected, set navigator.webdriver = false');
+        expect(suggestions).toContain('Empty plugins list detected, enable plugin emulation');
+    });
+});

package/dist/tests/modules/emulator/BrowserAPIDatabase.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/emulator/BrowserAPIDatabase.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { BrowserAPIDatabase } from '../../../src/modules/emulator/BrowserAPIDatabase.js';
+describe('BrowserAPIDatabase', () => {
+    it('loads core APIs on initialization', () => {
+        const db = new BrowserAPIDatabase();
+        const api = db.getAPI('window.setTimeout');
+        expect(api).toBeDefined();
+        expect(api?.type).toBe('method');
+    });
+    it('filters APIs by type', () => {
+        const db = new BrowserAPIDatabase();
+        const constructors = db.getAPIsByType('constructor');
+        expect(constructors.some((api) => api.path === 'XMLHttpRequest')).toBe(true);
+    });
+    it('searches APIs by name/path/description (case-insensitive)', () => {
+        const db = new BrowserAPIDatabase();
+        const byName = db.searchAPIs('queryselector');
+        const byPath = db.searchAPIs('navigator.permissions');
+        const byDesc = db.searchAPIs('global window object');
+        expect(byName.some((x) => x.path === 'document.querySelector')).toBe(true);
+        expect(byPath.some((x) => x.path === 'navigator.permissions')).toBe(true);
+        expect(byDesc.some((x) => x.path === 'window')).toBe(true);
+    });
+    it('allows runtime API registration', () => {
+        const db = new BrowserAPIDatabase();
+        db.addAPI({
+            name: 'customFn',
+            path: 'window.customFn',
+            type: 'method',
+            returnType: 'void',
+            antiCrawlImportance: 1,
+        });
+        expect(db.getAPI('window.customFn')?.name).toBe('customFn');
+    });
+    it('supports export and re-load from JSON', () => {
+        const db = new BrowserAPIDatabase();
+        db.addAPI({
+            name: 'reloadable',
+            path: 'window.reloadable',
+            type: 'property',
+        });
+        const dump = db.exportToJSON();
+        const restored = new BrowserAPIDatabase();
+        restored.loadFromJSON(dump);
+        expect(restored.getAPI('window.reloadable')).toBeDefined();
+        expect(restored.getAPI('window.setInterval')).toBeDefined();
+    });
+});

package/dist/tests/modules/emulator/BrowserEnvironmentRules.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/emulator/BrowserEnvironmentRules.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { BrowserEnvironmentRulesManager } from '../../../src/modules/emulator/BrowserEnvironmentRules.js';
+describe('BrowserEnvironmentRulesManager', () => {
+    it('loads default rules and exposes lookups', () => {
+        const manager = new BrowserEnvironmentRulesManager();
+        const webdriverRule = manager.getRule('navigator.webdriver');
+        expect(webdriverRule).toBeDefined();
+        expect(webdriverRule?.required).toBe(true);
+        expect(webdriverRule?.defaultValue).toBe(false);
+    });
+    it('returns category-specific rules', () => {
+        const manager = new BrowserEnvironmentRulesManager();
+        const navigatorRules = manager.getRulesByCategory('navigator');
+        expect(navigatorRules.length).toBeGreaterThan(5);
+        expect(navigatorRules.some((r) => r.path === 'navigator.userAgent')).toBe(true);
+    });
+    it('supports runtime rule registration', () => {
+        const manager = new BrowserEnvironmentRulesManager();
+        manager.addRule({
+            path: 'window.__custom',
+            category: 'window',
+            type: 'string',
+            defaultValue: 'ok',
+        });
+        expect(manager.getRule('window.__custom')?.defaultValue).toBe('ok');
+    });
+    it('evaluates function-based default values for userAgent rule', () => {
+        const manager = new BrowserEnvironmentRulesManager();
+        const rule = manager.getRule('navigator.userAgent');
+        const value = typeof rule?.defaultValue === 'function'
+            ? rule.defaultValue('chrome', '120.0-test')
+            : '';
+        expect(typeof value).toBe('string');
+        expect(String(value)).toContain('120.0-test');
+    });
+    it('exports and reloads rules/config JSON', () => {
+        const manager = new BrowserEnvironmentRulesManager();
+        manager.addRule({
+            path: 'navigator.__restored',
+            category: 'navigator',
+            type: 'boolean',
+            defaultValue: true,
+        });
+        const json = manager.exportToJSON();
+        const restored = new BrowserEnvironmentRulesManager();
+        restored.loadFromJSON(json);
+        expect(restored.getRule('navigator.__restored')?.defaultValue).toBe(true);
+        expect(restored.getRule('location.href')).toBeDefined();
+    });
+});

package/dist/tests/modules/emulator/EmulatorCodeGen.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/emulator/EmulatorCodeGen.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { generateEmulationCode, generateNodeJSCode, generatePythonCode, categorizeManifest, formatValue, formatValueForJS, generateRecommendations, } from '../../../src/modules/emulator/EmulatorCodeGen.js';
+describe('EmulatorCodeGen', () => {
+    it('generates both runtime code blocks when targetRuntime=both', () => {
+        const output = generateEmulationCode({ 'window.innerWidth': 1920 }, 'both', false);
+        expect(output.nodejs).toContain('module.exports');
+        expect(output.python).toContain('import execjs');
+    });
+    it('categorizes manifest paths into expected groups', () => {
+        const categorized = categorizeManifest({
+            'window.a': 1,
+            'navigator.b': 2,
+            'document.c': 3,
+            'foo.bar': 4,
+        });
+        expect(categorized.window).toHaveLength(1);
+        expect(categorized.navigator).toHaveLength(1);
+        expect(categorized.document).toHaveLength(1);
+        expect(categorized.other).toHaveLength(1);
+    });
+    it('formats primitive and nested values', () => {
+        expect(formatValue('a"b')).toContain('\\"');
+        expect(formatValue(123)).toBe('123');
+        expect(formatValue([1, 'x'])).toContain('[1, "x"]');
+        expect(formatValue({ key: true })).toContain('key: true');
+    });
+    it('sanitizes special placeholders in formatValueForJS', () => {
+        expect(formatValueForJS('[Function]')).toBe('function() {}');
+        expect(formatValueForJS('[Circular Reference]')).toBe('{}');
+        expect(formatValueForJS('[Max Depth]')).toBe('null');
+        expect(formatValueForJS({ a: 1, __internal: 'x' })).toContain('a: 1');
+    });
+    it('includes optional comments in generated Node/Python templates', () => {
+        const nodeCode = generateNodeJSCode({ 'window.a': 1 }, true);
+        const pyCode = generatePythonCode({ 'navigator.userAgent': 'ua' }, true);
+        expect(nodeCode).toContain('// === Base Variable Declarations ===');
+        expect(pyCode).toContain('"""');
+    });
+    it('creates recommendations from variable/API counts', () => {
+        const recommendations = generateRecommendations({
+            window: Array.from({ length: 60 }, (_, i) => `window.v${i}`),
+            document: [],
+            navigator: [],
+            location: [],
+            screen: [],
+            other: [],
+        }, [{ name: 'x', path: 'window.x', type: 'property', suggestion: 'y' }]);
+        expect(recommendations).toContain('Enable environment emulation for better compatibility');
+        expect(recommendations.some((r) => r.includes('1 API'))).toBe(true);
+    });
+});

package/dist/tests/modules/emulator/EnvironmentEmulator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/emulator/EnvironmentEmulator.test.js

@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as parser from '@babel/parser';
+const promptState = vi.hoisted(() => ({
+    generateMissingAPIImplementationsMessages: vi.fn(() => [{ role: 'user', content: 'api' }]),
+    generateMissingVariablesMessages: vi.fn(() => [{ role: 'user', content: 'vars' }]),
+}));
+vi.mock('@src/services/prompts/environment', () => ({
+    generateMissingAPIImplementationsMessages: promptState.generateMissingAPIImplementationsMessages,
+    generateMissingVariablesMessages: promptState.generateMissingVariablesMessages,
+}));
+vi.mock('@src/utils/logger', () => ({
+    logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+    },
+}));
+vi.mock('@src/utils/browserExecutable', () => ({
+    findBrowserExecutable: vi.fn(() => undefined),
+}));
+const puppeteerState = vi.hoisted(() => ({
+    launch: vi.fn(),
+}));
+vi.mock('rebrowser-puppeteer-core', () => ({
+    default: {
+        launch: puppeteerState.launch,
+    },
+}));
+import { EnvironmentEmulator } from '../../../src/modules/emulator/EnvironmentEmulator.js';
+describe('EnvironmentEmulator', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('analyzes code and builds manifest from template without autoFetch', async () => {
+        const emulator = new EnvironmentEmulator();
+        const result = await emulator.analyze({
+            code: 'window.innerWidth; navigator.userAgent;',
+            autoFetch: false,
+            targetRuntime: 'nodejs',
+            includeComments: false,
+        });
+        expect(result.detectedVariables.window).toContain('window.innerWidth');
+        expect(result.detectedVariables.navigator).toContain('navigator.userAgent');
+        expect(result.variableManifest['window.innerWidth']).toBe(1920);
+        expect(result.missingAPIs).toHaveLength(0);
+        expect(result.emulationCode.nodejs).toContain('window.innerWidth');
+    });
+    it('falls back to regex detection when parser throws', async () => {
+        const parseSpy = vi.spyOn(parser, 'parse').mockImplementation(() => {
+            throw new Error('parse-failed');
+        });
+        const emulator = new EnvironmentEmulator();
+        const result = await emulator.analyze({
+            code: 'document.title; window.outerWidth;',
+            autoFetch: false,
+            includeComments: false,
+        });
+        expect(result.detectedVariables.document).toContain('document.title');
+        expect(result.detectedVariables.window).toContain('window.outerWidth');
+        parseSpy.mockRestore();
+    });
+    it('applies AI-inferred variables into manifest', async () => {
+        const llm = {
+            chat: vi
+                .fn()
+                .mockResolvedValueOnce({
+                content: '```json\n{"window.customThing":"hello"}\n```',
+            }),
+        };
+        const emulator = new EnvironmentEmulator(llm);
+        const result = await emulator.analyze({
+            code: 'window.customThing;',
+            autoFetch: false,
+            includeComments: false,
+        });
+        expect(llm.chat).toHaveBeenCalledTimes(1);
+        expect(result.variableManifest['window.customThing']).toBe('hello');
+        expect(result.missingAPIs).toHaveLength(0);
+    });
+    it('uses AI API implementation generation for missing APIs', async () => {
+        const llm = {
+            chat: vi
+                .fn()
+                .mockResolvedValueOnce({ content: '```json\n{}\n```' })
+                .mockResolvedValueOnce({
+                content: '```json\n{"window.missingFn":"function() { return 1; }"}\n```',
+            }),
+        };
+        const emulator = new EnvironmentEmulator(llm);
+        const result = await emulator.analyze({
+            code: 'window.missingFn;',
+            autoFetch: false,
+            includeComments: false,
+        });
+        expect(llm.chat).toHaveBeenCalledTimes(2);
+        expect(result.missingAPIs.length).toBeGreaterThan(0);
+        expect(result.variableManifest['window.missingFn']).toContain('function()');
+    });
+    it('cleanup closes browser instance and clears internal reference', async () => {
+        const emulator = new EnvironmentEmulator();
+        const close = vi.fn().mockResolvedValue(undefined);
+        emulator.browser = { close };
+        await emulator.cleanup();
+        expect(close).toHaveBeenCalledOnce();
+        expect(emulator.browser).toBeUndefined();
+    });
+    it('throws when configured executable path does not exist', () => {
+        const emulator = new EnvironmentEmulator();
+        const old = process.env.CHROME_PATH;
+        process.env.CHROME_PATH = '/definitely/not/exist/browser-bin';
+        expect(() => emulator.resolveExecutablePath()).toThrow('Configured browser executable was not found');
+        process.env.CHROME_PATH = old;
+    });
+});

package/dist/tests/modules/external/ExternalToolRunner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/modules/external/ExternalToolRunner.test.js

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+const state = vi.hoisted(() => {
+    const spawn = vi.fn();
+    const getProjectRoot = vi.fn(() => '/repo/root');
+    const ioLimit = vi.fn(async (task) => task());
+    return { spawn, getProjectRoot, ioLimit };
+});
+vi.mock('node:child_process', () => ({
+    spawn: state.spawn,
+}));
+vi.mock('@src/utils/outputPaths', () => ({
+    getProjectRoot: state.getProjectRoot,
+}));
+vi.mock('@src/utils/concurrency', () => ({
+    ioLimit: state.ioLimit,
+}));
+vi.mock('@src/utils/logger', () => ({
+    logger: {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    },
+}));
+import { ExternalToolRunner } from '../../../src/modules/external/ExternalToolRunner.js';
+function createChildProcessMock() {
+    const child = new EventEmitter();
+    child.stdout = new EventEmitter();
+    child.stderr = new EventEmitter();
+    child.stdin = {
+        write: vi.fn(),
+        end: vi.fn(),
+    };
+    child.kill = vi.fn();
+    return child;
+}
+describe('ExternalToolRunner', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.useRealTimers();
+    });
+    it('delegates probeAll to registry', async () => {
+        const registry = {
+            probeAll: vi.fn().mockResolvedValue({ ok: true }),
+            getSpec: vi.fn(),
+            getCachedProbe: vi.fn(),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const result = await runner.probeAll(true);
+        expect(registry.probeAll).toHaveBeenCalledWith(true);
+        expect(result).toEqual({ ok: true });
+    });
+    it('returns early when cached probe indicates unavailable tool', async () => {
+        const registry = {
+            probeAll: vi.fn(),
+            getSpec: vi.fn().mockReturnValue({ command: 'wasm2wat' }),
+            getCachedProbe: vi.fn().mockReturnValue({ available: false, reason: 'missing' }),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const result = await runner.run({ tool: 'wabt.wasm2wat', args: [] });
+        expect(result.ok).toBe(false);
+        expect(result.stderr).toContain('not available: missing');
+        expect(state.spawn).not.toHaveBeenCalled();
+    });
+    it('spawns process with merged args and captures output', async () => {
+        const child = createChildProcessMock();
+        state.spawn.mockReturnValue(child);
+        const registry = {
+            probeAll: vi.fn(),
+            getSpec: vi.fn().mockReturnValue({
+                command: 'tool-bin',
+                defaultArgs: ['--default'],
+            }),
+            getCachedProbe: vi.fn().mockReturnValue({ available: true }),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const progress = vi.fn();
+        const runPromise = runner.run({
+            tool: 'wabt.wasm2wat',
+            args: ['--foo'],
+            onProgress: progress,
+        });
+        child.stdout.emit('data', Buffer.from('hello'));
+        child.stderr.emit('data', Buffer.from('warn'));
+        child.emit('close', 0, null);
+        const result = await runPromise;
+        expect(state.spawn).toHaveBeenCalledWith('tool-bin', ['--default', '--foo'], expect.objectContaining({ cwd: '/repo/root', shell: false }));
+        expect(result).toMatchObject({
+            ok: true,
+            exitCode: 0,
+            stdout: 'hello',
+            stderr: 'warn',
+            truncated: false,
+        });
+        expect(progress).toHaveBeenCalled();
+    });
+    it('truncates stdout when maxStdoutBytes is exceeded', async () => {
+        const child = createChildProcessMock();
+        state.spawn.mockReturnValue(child);
+        const registry = {
+            probeAll: vi.fn(),
+            getSpec: vi.fn().mockReturnValue({ command: 'tool-bin' }),
+            getCachedProbe: vi.fn().mockReturnValue({ available: true }),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const runPromise = runner.run({
+            tool: 'wabt.wasm2wat',
+            args: [],
+            maxStdoutBytes: 4,
+        });
+        child.stdout.emit('data', Buffer.from('abcdef'));
+        child.emit('close', 0, null);
+        const result = await runPromise;
+        expect(result.stdout).toBe('abcd');
+        expect(result.truncated).toBe(true);
+    });
+    it('uses project root when cwd is outside allowed boundaries', async () => {
+        const child = createChildProcessMock();
+        state.spawn.mockReturnValue(child);
+        const registry = {
+            probeAll: vi.fn(),
+            getSpec: vi.fn().mockReturnValue({ command: 'tool-bin' }),
+            getCachedProbe: vi.fn().mockReturnValue({ available: true }),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const runPromise = runner.run({
+            tool: 'wabt.wasm2wat',
+            args: [],
+            cwd: '/etc',
+        });
+        child.emit('close', 0, null);
+        await runPromise;
+        expect(state.spawn).toHaveBeenCalledWith('tool-bin', [], expect.objectContaining({ cwd: '/repo/root' }));
+    });
+    it('kills hung process on timeout and reports SIGKILL', async () => {
+        vi.useFakeTimers();
+        const child = createChildProcessMock();
+        state.spawn.mockReturnValue(child);
+        const registry = {
+            probeAll: vi.fn(),
+            getSpec: vi.fn().mockReturnValue({ command: 'tool-bin' }),
+            getCachedProbe: vi.fn().mockReturnValue({ available: true }),
+        };
+        const runner = new ExternalToolRunner(registry);
+        const pending = runner.run({
+            tool: 'wabt.wasm2wat',
+            args: [],
+            timeoutMs: 10,
+        });
+        await vi.advanceTimersByTimeAsync(11);
+        await vi.advanceTimersByTimeAsync(2001);
+        const result = await pending;
+        expect(child.kill).toHaveBeenCalledWith('SIGTERM');
+        expect(child.kill).toHaveBeenCalledWith('SIGKILL');
+        expect(result.signal).toBe('SIGKILL');
+        expect(result.ok).toBe(false);
+    });
+});

package/dist/tests/modules/external/ToolProbe.test.d.ts

@@ -0,0 +1 @@
+export {};