@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/tests/constants.test.js

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+const ORIGINAL_ENV = { ...process.env };
+async function loadConstants(overrides = {}) {
+    vi.resetModules();
+    process.env = { ...ORIGINAL_ENV };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    }
+    return import('../src/constants.js');
+}
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    vi.resetModules();
+});
+describe('constants env parsing', () => {
+    it('parses integer env values with fallback semantics', async () => {
+        expect((await loadConstants({ DEFAULT_DEBUG_PORT: undefined })).DEFAULT_DEBUG_PORT).toBe(9222);
+        expect((await loadConstants({ DEFAULT_DEBUG_PORT: '' })).DEFAULT_DEBUG_PORT).toBe(9222);
+        expect((await loadConstants({ DEFAULT_DEBUG_PORT: 'abc' })).DEFAULT_DEBUG_PORT).toBe(9222);
+        expect((await loadConstants({ DEFAULT_DEBUG_PORT: '1337' })).DEFAULT_DEBUG_PORT).toBe(1337);
+    });
+    it('parses float env values with fallback semantics', async () => {
+        expect((await loadConstants({ SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER: undefined }))
+            .SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER).toBe(1.5);
+        expect((await loadConstants({ SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER: '' }))
+            .SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER).toBe(1.5);
+        expect((await loadConstants({ SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER: 'abc' }))
+            .SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER).toBe(1.5);
+        expect((await loadConstants({ SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER: '2.25' }))
+            .SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER).toBe(2.25);
+    });
+    it('parses boolean env values for ENABLE_INJECTION_TOOLS', async () => {
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: undefined })).ENABLE_INJECTION_TOOLS).toBe(true);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: '' })).ENABLE_INJECTION_TOOLS).toBe(true);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: '1' })).ENABLE_INJECTION_TOOLS).toBe(true);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: ' TRUE ' })).ENABLE_INJECTION_TOOLS).toBe(true);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: '0' })).ENABLE_INJECTION_TOOLS).toBe(false);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: 'false' })).ENABLE_INJECTION_TOOLS).toBe(false);
+        expect((await loadConstants({ ENABLE_INJECTION_TOOLS: 'maybe' })).ENABLE_INJECTION_TOOLS).toBe(true);
+    });
+    it('parses string env values with fallback semantics', async () => {
+        expect((await loadConstants({ GHIDRA_BRIDGE_URL: undefined })).GHIDRA_BRIDGE_ENDPOINT).toBe('http://127.0.0.1:18080');
+        expect((await loadConstants({ GHIDRA_BRIDGE_URL: '' })).GHIDRA_BRIDGE_ENDPOINT).toBe('http://127.0.0.1:18080');
+        expect((await loadConstants({ GHIDRA_BRIDGE_URL: 'https://vmoranv.github.io/jshookmcp/test' })).GHIDRA_BRIDGE_ENDPOINT).toBe('https://vmoranv.github.io/jshookmcp/test');
+    });
+    it('parses numeric lists and drops invalid entries without falling back', async () => {
+        expect((await loadConstants({ DEBUG_PORT_CANDIDATES: '' })).DEBUG_PORT_CANDIDATES).toEqual([
+            9222, 9229, 9333, 2039,
+        ]);
+        expect((await loadConstants({ DEBUG_PORT_CANDIDATES: '9333,foo,9444' })).DEBUG_PORT_CANDIDATES).toEqual([
+            9333, 9444,
+        ]);
+        expect((await loadConstants({ DEBUG_PORT_CANDIDATES: 'foo,bar' })).DEBUG_PORT_CANDIDATES).toEqual([]);
+    });
+    it('parses csv tiers with normalization and fallback semantics', async () => {
+        expect((await loadConstants({ SEARCH_WORKFLOW_BOOST_TIERS: undefined })).SEARCH_WORKFLOW_BOOST_TIERS).toEqual(new Set(['workflow', 'full']));
+        expect((await loadConstants({ SEARCH_WORKFLOW_BOOST_TIERS: ' Workflow , FULL ' })).SEARCH_WORKFLOW_BOOST_TIERS).toEqual(new Set(['workflow', 'full']));
+        expect((await loadConstants({ SEARCH_WORKFLOW_BOOST_TIERS: ' , , ' })).SEARCH_WORKFLOW_BOOST_TIERS).toEqual(new Set(['workflow', 'full']));
+    });
+    it('parses optional json overrides with fallback semantics', async () => {
+        expect((await loadConstants({ SEARCH_INTENT_TOOL_BOOST_RULES_JSON: undefined }))
+            .SEARCH_INTENT_TOOL_BOOST_RULES_OVERRIDE).toBeNull();
+        expect((await loadConstants({
+            SEARCH_INTENT_TOOL_BOOST_RULES_JSON: '[{"pattern":"captcha","flags":"i","boosts":[{"tool":"workflow","bonus":2}]}]',
+        })).SEARCH_INTENT_TOOL_BOOST_RULES_OVERRIDE).toEqual([
+            {
+                pattern: 'captcha',
+                flags: 'i',
+                boosts: [{ tool: 'workflow', bonus: 2 }],
+            },
+        ]);
+        expect((await loadConstants({ SEARCH_INTENT_TOOL_BOOST_RULES_JSON: '{not-json' }))
+            .SEARCH_INTENT_TOOL_BOOST_RULES_OVERRIDE).toBeNull();
+    });
+    it('prefers the primary captcha solver url and trims both env variants', async () => {
+        expect((await loadConstants({
+            CAPTCHA_SOLVER_BASE_URL: ' https://vmoranv.github.io/jshookmcp/captcha-a ',
+            CAPTCHA_2CAPTCHA_BASE_URL: 'https://vmoranv.github.io/jshookmcp/captcha-b',
+        })).CAPTCHA_SOLVER_BASE_URL).toBe('https://vmoranv.github.io/jshookmcp/captcha-a');
+        expect((await loadConstants({
+            CAPTCHA_SOLVER_BASE_URL: '   ',
+            CAPTCHA_2CAPTCHA_BASE_URL: ' https://vmoranv.github.io/jshookmcp/captcha-b ',
+        })).CAPTCHA_SOLVER_BASE_URL).toBe('https://vmoranv.github.io/jshookmcp/captcha-b');
+        expect((await loadConstants({
+            CAPTCHA_SOLVER_BASE_URL: undefined,
+            CAPTCHA_2CAPTCHA_BASE_URL: undefined,
+        })).CAPTCHA_SOLVER_BASE_URL).toBe('');
+    });
+    it('trims extension registry urls and collapses blank values', async () => {
+        expect((await loadConstants({ EXTENSION_REGISTRY_BASE_URL: ' https://vmoranv.github.io/jshookmcp/registry ' }))
+            .EXTENSION_REGISTRY_BASE_URL).toBe('https://vmoranv.github.io/jshookmcp/registry');
+        expect((await loadConstants({ EXTENSION_REGISTRY_BASE_URL: '   ' })).EXTENSION_REGISTRY_BASE_URL).toBe('');
+    });
+    it('preserves direct parseFloat behavior for CACHE_LOW_HIT_RATE_THRESHOLD', async () => {
+        expect((await loadConstants({ CACHE_LOW_HIT_RATE_THRESHOLD: undefined })).CACHE_LOW_HIT_RATE_THRESHOLD).toBe(0.3);
+        expect((await loadConstants({ CACHE_LOW_HIT_RATE_THRESHOLD: '0.75' })).CACHE_LOW_HIT_RATE_THRESHOLD).toBe(0.75);
+        expect(Number.isNaN((await loadConstants({ CACHE_LOW_HIT_RATE_THRESHOLD: 'abc' })).CACHE_LOW_HIT_RATE_THRESHOLD)).toBe(true);
+    });
+});

package/dist/tests/contracts/contracts.test.d.ts

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

package/dist/tests/contracts/contracts.test.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { createWorkflow, ToolNodeBuilder, SequenceNodeBuilder, ParallelNodeBuilder, BranchNodeBuilder, } from '../../src/server/workflows/WorkflowContract.js';
+import { NoopInstrumentation, SpanNames, MetricNames, } from '../../src/server/observability/InstrumentationContract.js';
+describe('WorkflowContract - builder helpers', () => {
+    it('ToolNodeBuilder creates a ToolNode with kind=tool', () => {
+        const node = new ToolNodeBuilder('step1', 'my_tool').build();
+        expect(node.kind).toBe('tool');
+        expect(node.id).toBe('step1');
+        expect(node.toolName).toBe('my_tool');
+        expect(node.input).toBeUndefined();
+    });
+    it('ToolNodeBuilder accepts options', () => {
+        const node = new ToolNodeBuilder('step2', 'tool2')
+            .input({ key: 'value' })
+            .retry({ maxAttempts: 3, backoffMs: 1000, multiplier: 2 })
+            .timeout(5000)
+            .build();
+        expect(node.input).toEqual({ key: 'value' });
+        expect(node.retry?.maxAttempts).toBe(3);
+        expect(node.timeoutMs).toBe(5000);
+    });
+    it('SequenceNodeBuilder creates a SequenceNode', () => {
+        const node = new SequenceNodeBuilder('seq1')
+            .tool('a', 'tool_a')
+            .build();
+        expect(node.kind).toBe('sequence');
+        expect(node.steps).toHaveLength(1);
+        expect(node.steps[0].id).toBe('a');
+        expect(node.steps[0].toolName).toBe('tool_a');
+    });
+    it('ParallelNodeBuilder creates a ParallelNode with defaults', () => {
+        const node = new ParallelNodeBuilder('par1')
+            .tool('a', 'tool_a')
+            .tool('b', 'tool_b')
+            .build();
+        expect(node.kind).toBe('parallel');
+        expect(node.maxConcurrency).toBe(4);
+        expect(node.failFast).toBe(false);
+    });
+    it('ParallelNodeBuilder accepts custom concurrency and failFast', () => {
+        const node = new ParallelNodeBuilder('par2')
+            .maxConcurrency(2)
+            .failFast(true)
+            .build();
+        expect(node.maxConcurrency).toBe(2);
+        expect(node.failFast).toBe(true);
+    });
+    it('BranchNodeBuilder creates a BranchNode with predicateId', () => {
+        const node = new BranchNodeBuilder('br1', 'my_predicate')
+            .whenTrue(new ToolNodeBuilder('t', 'tool_t'))
+            .whenFalse(new ToolNodeBuilder('f', 'tool_f'))
+            .build();
+        expect(node.kind).toBe('branch');
+        expect(node.predicateId).toBe('my_predicate');
+        expect(node.whenTrue.id).toBe('t');
+        expect(node.whenFalse?.id).toBe('f');
+        expect(node.predicateFn).toBeUndefined();
+    });
+    it('BranchNodeBuilder accepts optional predicateFn', () => {
+        const fn = () => true;
+        const node = new BranchNodeBuilder('br2', 'pred')
+            .whenTrue(new ToolNodeBuilder('t', 'tool_t'))
+            .predicateFn(fn)
+            .build();
+        expect(node.predicateFn).toBe(fn);
+        expect(node.whenFalse).toBeUndefined();
+    });
+});
+describe('WorkflowContract - node composition', () => {
+    it('nodes can be nested arbitrarily', () => {
+        const root = new SequenceNodeBuilder('root')
+            .parallel('par', (b) => b
+            .tool('leaf1', 'tool_leaf')
+            .branch('br', 'check', (b) => b
+            .whenTrue(new ToolNodeBuilder('leaf2', 'tool_leaf'))))
+            .tool('leaf3', 'tool_leaf')
+            .build();
+        expect(root.kind).toBe('sequence');
+        expect(root.steps[0].kind).toBe('parallel');
+        expect(root.steps[0].steps[1].kind).toBe('branch');
+    });
+    it('createWorkflow builds a valid contract', () => {
+        const contract = createWorkflow('wf1', 'Test Workflow')
+            .description('A test')
+            .timeoutMs(10000)
+            .buildGraph(() => new ToolNodeBuilder('root', 'my_tool'))
+            .build();
+        expect(contract.kind).toBe('workflow-contract');
+        expect(contract.id).toBe('wf1');
+        expect(contract.displayName).toBe('Test Workflow');
+        expect(contract.timeoutMs).toBe(10000);
+        expect(contract.build({}).kind).toBe('tool');
+    });
+});
+describe('InstrumentationContract - NoopInstrumentation', () => {
+    it('startSpan returns a SpanLike that does not throw', () => {
+        const noop = new NoopInstrumentation();
+        const span = noop.startSpan('test.span', { key: 'value' });
+        expect(span.name).toBe('test.span');
+        expect(span.startTime).toBeGreaterThan(0);
+        expect(() => span.addEvent('event')).not.toThrow();
+        expect(() => span.end()).not.toThrow();
+    });
+    it('emitMetric does not throw', () => {
+        const noop = new NoopInstrumentation();
+        expect(() => noop.emitMetric('test_metric', 1, 'counter')).not.toThrow();
+        expect(() => noop.emitMetric('test_metric', 42, 'gauge', { dim: 'a' })).not.toThrow();
+        expect(() => noop.emitMetric('test_metric', 1.5, 'histogram')).not.toThrow();
+    });
+});
+describe('InstrumentationContract - well-known names', () => {
+    it('SpanNames contains expected keys', () => {
+        expect(SpanNames.toolExecute).toBe('tool.execute');
+        expect(SpanNames.pluginLifecycle).toBe('plugin.lifecycle');
+        expect(SpanNames.workflowRun).toBe('workflow.run');
+        expect(SpanNames.bridgeRequest).toBe('bridge.request');
+        expect(SpanNames.captchaSolve).toBe('captcha.solve');
+    });
+    it('MetricNames contains expected keys', () => {
+        expect(MetricNames.toolCallsTotal).toBe('tool_calls_total');
+        expect(MetricNames.workflowRunsTotal).toBe('workflow_runs_total');
+        expect(MetricNames.bridgeRequestsTotal).toBe('bridge_requests_total');
+        expect(MetricNames.pluginActiveTotal).toBe('plugin_active_total');
+    });
+});

package/dist/tests/e2e/context-capture.d.ts

@@ -0,0 +1,2 @@
+import type { E2EContext } from '../e2e/helpers/types.js';
+export declare function applyContextCapture(toolName: string, parsed: unknown, ctx: E2EContext, overrides: Record<string, Record<string, unknown>>): void;

package/dist/tests/e2e/context-capture.js

@@ -0,0 +1,55 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function applyContextCapture(toolName, parsed, ctx, overrides) {
+    if (toolName === 'get_all_scripts' && isRecord(parsed) && Array.isArray(parsed.scripts) && parsed.scripts.length > 0) {
+        const firstScript = parsed.scripts[0];
+        if (firstScript.scriptId !== undefined) {
+            ctx.scriptId = String(firstScript.scriptId);
+        }
+    }
+    if (toolName === 'breakpoint_set' && isRecord(parsed)) {
+        const breakpoint = isRecord(parsed.breakpoint) ? parsed.breakpoint : undefined;
+        const breakpointId = parsed.breakpointId ?? breakpoint?.breakpointId;
+        if (breakpointId != null) {
+            ctx.breakpointId = String(breakpointId);
+            overrides.breakpoint_remove = { breakpointId: ctx.breakpointId };
+        }
+    }
+    if (toolName === 'network_get_requests' && isRecord(parsed) && Array.isArray(parsed.requests) && parsed.requests.length > 0) {
+        const first = parsed.requests[0];
+        if (first.requestId != null) {
+            ctx.requestId = String(first.requestId);
+            overrides.network_get_response_body = { requestId: ctx.requestId };
+            overrides.network_replay_request = { requestId: ctx.requestId };
+        }
+    }
+    if (toolName === 'ai_hook_generate' && isRecord(parsed)) {
+        const hookId = parsed.hookId ?? parsed.id;
+        if (hookId != null) {
+            ctx.hookId = String(hookId);
+            overrides.ai_hook_inject = { hookId: ctx.hookId };
+            overrides.ai_hook_toggle = { hookId: ctx.hookId, enabled: true };
+            overrides.ai_hook_get_data = { hookId: ctx.hookId };
+        }
+    }
+    if (toolName === 'get_scope_variables_enhanced' && isRecord(parsed) && Array.isArray(parsed.variables)) {
+        const objVar = parsed.variables.find((v) => v.objectId != null);
+        if (objVar) {
+            ctx.objectId = String(objVar.objectId);
+            overrides.get_object_properties = { objectId: ctx.objectId };
+        }
+    }
+    if (toolName === 'watch_add' && isRecord(parsed)) {
+        overrides.watch_remove = { id: String(parsed.id ?? parsed.watchId ?? '0') };
+    }
+    if (toolName === 'xhr_breakpoint_set' && isRecord(parsed)) {
+        overrides.xhr_breakpoint_remove = { id: String(parsed.id ?? parsed.breakpointId ?? '0') };
+    }
+    if (toolName === 'event_breakpoint_set' && isRecord(parsed)) {
+        overrides.event_breakpoint_remove = { id: String(parsed.id ?? parsed.breakpointId ?? '0') };
+    }
+    if (toolName === 'blackbox_add_common' && isRecord(parsed) && Array.isArray(parsed.added) && parsed.added.length > 0) {
+        overrides.blackbox_add = { pattern: parsed.added[0] };
+    }
+}

package/dist/tests/e2e/full-tool-e2e.test.d.ts

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

package/dist/tests/e2e/full-tool-e2e.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MCPTestClient } from '../e2e/helpers/mcp-client.js';
+import { buildArgs } from '../e2e/helpers/schema-builder.js';
+import { getOverrides } from '../e2e/overrides.js';
+import { buildSkipSet } from '../e2e/skip-list.js';
+import { ALL_PHASES } from '../e2e/phases/index.js';
+import { applyContextCapture } from '../e2e/context-capture.js';
+function flag(name, fallback) {
+    const argv = process.argv.slice(2);
+    const i = argv.indexOf(name);
+    return i === -1 ? fallback : (argv[i + 1] ?? fallback);
+}
+function extractDomain(url) {
+    try {
+        return '.' + new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return '.example.com';
+    }
+}
+const DEFAULT_TARGET_URL = '';
+const TARGET_URL = process.env.E2E_TARGET_URL || flag('--target-url', DEFAULT_TARGET_URL);
+const ARTIFACT_DIR = join(process.cwd(), '.tmp_mcp_artifacts');
+const config = {
+    targetUrl: TARGET_URL,
+    targetDomain: extractDomain(TARGET_URL),
+    electronPath: flag('--electron-path', ''),
+    miniappPath: flag('--miniapp-path', ''),
+    asarPath: flag('--asar-path', ''),
+    browserPath: flag('--browser-path', 'C:/Program Files/Browser/Application/browser.exe'),
+    perToolTimeout: Number(flag('--timeout', '30000')),
+    skipSet: new Set((flag('--skip', '') || '').split(',').filter(Boolean)),
+    artifactDir: ARTIFACT_DIR,
+};
+describe.skipIf(!TARGET_URL)('Full Tool E2E', { timeout: 300_000, sequential: true }, () => {
+    const client = new MCPTestClient();
+    const ctx = { scriptId: null, breakpointId: null, requestId: null, hookId: null, objectId: null };
+    const alwaysSkip = buildSkipSet({ electronPath: config.electronPath, miniappPath: config.miniappPath });
+    let overrides = {};
+    let toolMap = new Map();
+    beforeAll(async () => {
+        await mkdir(ARTIFACT_DIR, { recursive: true });
+        await client.connect();
+        toolMap = client.getToolMap();
+        overrides = getOverrides(ctx, config);
+    });
+    afterAll(async () => {
+        const results = client.results;
+        const pass = results.filter((r) => r.ok).length;
+        const isErrorCount = results.filter((r) => r.isError).length;
+        const report = {
+            timestamp: new Date().toISOString(),
+            targetUrl: TARGET_URL,
+            serverToolCount: toolMap?.size ?? 0,
+            tested: results.length,
+            pass,
+            fail: results.length - pass,
+            isErrorCount,
+            results,
+        };
+        const reportPath = join(ARTIFACT_DIR, 'e2e-full-report.json');
+        try {
+            await writeFile(reportPath, JSON.stringify(report, null, 2));
+        }
+        catch { }
+        await client.cleanup();
+    });
+    for (const phase of ALL_PHASES) {
+        describe(phase.name, { sequential: true, timeout: 120_000 }, () => {
+            beforeAll(async () => {
+                if (typeof phase.setup === 'function') {
+                    await phase.setup(async (name, args, timeout) => client.call(name, args, timeout ?? 45_000));
+                }
+                else if (Array.isArray(phase.setup)) {
+                    for (const setupTool of phase.setup) {
+                        if (config.skipSet.has(setupTool) || alwaysSkip.has(setupTool))
+                            continue;
+                        const args = overrides[setupTool] ?? buildArgs(toolMap.get(setupTool)?.inputSchema, config);
+                        await client.call(setupTool, args, 45_000);
+                        await new Promise((r) => setTimeout(r, 200));
+                    }
+                }
+                if (phase.name === 'Browser Launch & Navigation') {
+                    await new Promise((r) => setTimeout(r, 4_000));
+                }
+            });
+            for (const toolName of phase.tools) {
+                it(toolName, async () => {
+                    if (config.skipSet.has(toolName) || alwaysSkip.has(toolName))
+                        return;
+                    if (!toolMap.has(toolName))
+                        return;
+                    overrides = getOverrides(ctx, config);
+                    const args = overrides[toolName] ?? buildArgs(toolMap.get(toolName)?.inputSchema, config);
+                    const parsed = await client.call(toolName, args, config.perToolTimeout);
+                    applyContextCapture(toolName, parsed, ctx, overrides);
+                    if (toolName === 'debugger_pause') {
+                        await new Promise((r) => setTimeout(r, 500));
+                    }
+                    const lastResult = client.results[client.results.length - 1];
+                    expect(lastResult?.isError, `${toolName} returned isError`).toBe(false);
+                });
+            }
+        });
+    }
+});

package/dist/tests/e2e/helpers/mcp-client.d.ts

@@ -0,0 +1,18 @@
+import type { ToolResult } from '../../e2e/helpers/types.js';
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+export declare function parseContent(result: unknown): unknown;
+export declare class MCPTestClient {
+    private client;
+    private transport;
+    private toolMap;
+    readonly results: ToolResult[];
+    constructor();
+    private record;
+    connect(): Promise<void>;
+    getToolMap(): Map<string, {
+        name: string;
+        inputSchema?: Record<string, unknown>;
+    }>;
+    call(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    cleanup(): Promise<void>;
+}

package/dist/tests/e2e/helpers/mcp-client.js

@@ -0,0 +1,120 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Timeout after ${ms}ms (${label})`)), ms);
+        promise
+            .then((v) => { clearTimeout(timer); resolve(v); })
+            .catch((e) => { clearTimeout(timer); reject(e); });
+    });
+}
+export function parseContent(result) {
+    if (!isRecord(result) || !Array.isArray(result.content) || result.content.length === 0)
+        return result;
+    const first = result.content[0];
+    if (!isRecord(first) || typeof first.text !== 'string')
+        return result;
+    try {
+        return JSON.parse(first.text);
+    }
+    catch {
+        return first.text;
+    }
+}
+export class MCPTestClient {
+    client;
+    transport = null;
+    toolMap = new Map();
+    results = [];
+    constructor() {
+        this.client = new Client({ name: 'full-e2e-tool-test', version: '1.0.0' }, { capabilities: {} });
+    }
+    record(name, resp, error) {
+        const parsed = error ? null : parseContent(resp);
+        const isError = isRecord(resp) && resp.isError === true;
+        const softFail = !error && !isError && isRecord(parsed) && parsed.success === false;
+        const ok = !error && !isError;
+        let detail;
+        if (error) {
+            detail = error.message;
+        }
+        else if (isRecord(parsed)) {
+            if (parsed.success === false) {
+                detail = `GRACEFUL: ${String(parsed.message ?? parsed.error ?? 'success=false')}`;
+            }
+            else if (parsed.success === true) {
+                detail = 'success=true';
+            }
+            else {
+                detail = JSON.stringify(parsed).substring(0, 120);
+            }
+        }
+        else {
+            detail = String(parsed).substring(0, 120);
+        }
+        this.results.push({ name, ok, isError, detail: detail.substring(0, 200) });
+        const icon = isError || error ? '\u2717' : softFail ? '\u26A0' : '\u2713';
+        const status = softFail ? 'SOFT_FAIL' : ok ? 'OK' : 'FAIL';
+        console.info(`  ${icon} ${name.padEnd(42)} ${status} | ${detail.substring(0, 80)}`);
+        return parsed;
+    }
+    async connect() {
+        const env = {};
+        for (const [k, v] of Object.entries(process.env)) {
+            if (typeof v === 'string')
+                env[k] = v;
+        }
+        env.MCP_TRANSPORT = 'stdio';
+        env.MCP_TOOL_PROFILE = 'full';
+        env.LOG_LEVEL = 'error';
+        env.PUPPETEER_HEADLESS = 'false';
+        const transport = new StdioClientTransport({
+            command: 'node',
+            args: ['dist/src/index.js'],
+            cwd: process.cwd(),
+            env,
+            stderr: 'pipe',
+        });
+        this.transport = transport;
+        console.info('Connecting to MCP server...');
+        await withTimeout(this.client.connect(transport), 30000, 'connect');
+        console.info('Connected. Listing tools...');
+        const listed = await withTimeout(this.client.listTools(), 15000, 'listTools');
+        const tools = listed?.tools ?? [];
+        this.toolMap = new Map(tools.map((tool) => [tool.name, { name: tool.name, inputSchema: tool.inputSchema }]));
+        console.info(`Server has ${this.toolMap.size} tools registered.\n`);
+    }
+    getToolMap() {
+        return this.toolMap;
+    }
+    async call(name, args, timeoutMs = 30000) {
+        try {
+            const resp = await withTimeout(this.client.callTool({ name, arguments: args ?? {} }), timeoutMs, name);
+            return this.record(name, resp, null);
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            this.record(name, null, error);
+            return null;
+        }
+    }
+    async cleanup() {
+        try {
+            await this.call('browser_close', {}, 5000);
+        }
+        catch { }
+        try {
+            await this.transport?.close();
+        }
+        catch { }
+        try {
+            const proc = this.transport;
+            if (proc?._process?.pid)
+                process.kill(proc._process.pid, 'SIGKILL');
+        }
+        catch { }
+    }
+}

package/dist/tests/e2e/helpers/schema-builder.d.ts

@@ -0,0 +1,6 @@
+import type { E2EConfig } from '../../e2e/helpers/types.js';
+type SchemaBuilderConfig = Pick<E2EConfig, 'targetUrl' | 'artifactDir'>;
+export declare function scalarFromSchema(name: string, schema: Record<string, unknown> | undefined, config: SchemaBuilderConfig): unknown;
+export declare function valueFromSchema(name: string, schema: Record<string, unknown> | undefined, config: SchemaBuilderConfig, depth?: number): unknown;
+export declare function buildArgs(inputSchema: Record<string, unknown> | undefined, config: SchemaBuilderConfig): Record<string, unknown>;
+export {};

package/dist/tests/e2e/helpers/schema-builder.js

@@ -0,0 +1,108 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function scalarFromSchema(name, schema, config) {
+    if (schema?.const !== undefined)
+        return schema.const;
+    const enumValues = schema?.enum;
+    if (Array.isArray(enumValues) && enumValues.length > 0)
+        return enumValues[0];
+    const type = typeof schema?.type === 'string' ? schema.type : undefined;
+    const n = name.toLowerCase();
+    if (type === 'boolean')
+        return false;
+    if (type === 'number' || type === 'integer') {
+        if (typeof schema?.minimum === 'number')
+            return schema.minimum;
+        if (typeof schema?.exclusiveMinimum === 'number')
+            return schema.exclusiveMinimum + 1;
+        return type === 'integer' ? 1 : 1.0;
+    }
+    if (type === 'string' || !type) {
+        if (n.includes('url') || n.includes('endpoint') || n.includes('baseurl') || n.includes('registerurl'))
+            return config.targetUrl;
+        if (n.includes('selector'))
+            return 'body';
+        if (n.includes('path') || n.includes('file') || n.includes('artifactpath'))
+            return `${config.artifactDir}/${name}.txt`;
+        if (n.includes('query'))
+            return '{ __typename }';
+        if (n.includes('operationname'))
+            return 'TestOp';
+        if (n.includes('eventname'))
+            return 'click';
+        if (n === 'category')
+            return 'mouse';
+        if (n === 'state')
+            return 'none';
+        if (n === 'method')
+            return 'GET';
+        if (n === 'device')
+            return 'iPhone 14';
+        if (n === 'action')
+            return 'list';
+        if (n.includes('expression'))
+            return '1+1';
+        if (n.includes('code'))
+            return 'return 1;';
+        if (n.includes('pattern') || n.includes('keyword'))
+            return 'test';
+        if (n.includes('key') && !n.includes('apikey'))
+            return 'test_key';
+        if (n.includes('value'))
+            return 'test_value';
+        if (n.includes('hookid'))
+            return '__placeholder__';
+        if (n.includes('scriptid'))
+            return '__placeholder__';
+        if (n.includes('breakpointid'))
+            return '__placeholder__';
+        if (n.includes('requestid'))
+            return '__placeholder__';
+        if (n.includes('objectid'))
+            return '__placeholder__';
+        if (n.includes('callframeid'))
+            return '__placeholder__';
+        return 'test';
+    }
+    return null;
+}
+export function valueFromSchema(name, schema, config, depth = 0) {
+    if (!schema || depth > 4)
+        return scalarFromSchema(name, schema, config);
+    if (schema.const !== undefined || schema.enum !== undefined)
+        return scalarFromSchema(name, schema, config);
+    const oneOf = schema.oneOf;
+    if (Array.isArray(oneOf) && oneOf.length > 0 && isRecord(oneOf[0])) {
+        return valueFromSchema(name, oneOf[0], config, depth + 1);
+    }
+    const anyOf = schema.anyOf;
+    if (Array.isArray(anyOf) && anyOf.length > 0 && isRecord(anyOf[0])) {
+        return valueFromSchema(name, anyOf[0], config, depth + 1);
+    }
+    const type = typeof schema.type === 'string' ? schema.type : undefined;
+    if (type === 'object' || isRecord(schema.properties)) {
+        const props = isRecord(schema.properties) ? schema.properties : {};
+        const required = Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === 'string') : [];
+        const out = {};
+        for (const key of required) {
+            const propSchema = isRecord(props[key]) ? props[key] : undefined;
+            out[key] = valueFromSchema(key, propSchema, config, depth + 1);
+        }
+        return out;
+    }
+    if (type === 'array') {
+        const itemSchema = isRecord(schema.items) ? schema.items : undefined;
+        const minItems = typeof schema.minItems === 'number' ? schema.minItems : 0;
+        return Array.from({ length: Math.max(1, minItems) }, () => valueFromSchema(name, itemSchema, config, depth + 1));
+    }
+    return scalarFromSchema(name, schema, config);
+}
+export function buildArgs(inputSchema, config) {
+    const props = isRecord(inputSchema?.properties) ? inputSchema.properties : {};
+    const required = Array.isArray(inputSchema?.required) ? inputSchema.required.filter((key) => typeof key === 'string') : [];
+    const args = {};
+    for (const key of required)
+        args[key] = valueFromSchema(key, isRecord(props[key]) ? props[key] : undefined, config, 0);
+    return args;
+}