#!/usr/bin/env node
/**
 * Healix MCP Server
 *
 * Model Context Protocol server that exposes all HealixApiServer REST endpoints
 * as MCP tools over stdio transport. An AI agent (Claude, etc.) can call these
 * tools to observe and control live Healix test sessions.
 *
 * Tool categories
 * ───────────────
 * SESSION-INDEPENDENT — work any time, no running Healix session needed:
 *   healix_sessions          List live sessions from the registry
 *   healix_list_specs         Scan disk for all spec files in the project
 *   healix_list_capabilities  Read healix.agent.json — available platforms, app config, suites
 *   healix_scaffold           Generate .locators.json stubs from @Find-decorated POM source files
 *   healix_start_session      Spawn a new WDIO session (reads config, spawns detached process)
 *
 * SESSION-REQUIRED — require api.enabled:true and an active WebDriver session:
 *   healix_status        Session health and test counts
 *   healix_list_tests    Tests in the loaded suite with results         [--interactive]
 *   healix_list_pages    Registered page objects and their methods
 *   healix_run_test      Queue one test by name                         [--interactive]
 *   healix_run_all       Queue all tests                                [--interactive]
 *   healix_reload_specs  Hot-reload spec files                          [--interactive]
 *   healix_device_info   Live WebDriver capabilities / device descriptor
 *   healix_get_dom       Current screen/page source (XML or HTML)
 *   healix_get_contexts  List WebDriver contexts (for hybrid apps)
 *   healix_switch_context Switch WebDriver context
 *   healix_validate_locator Test a locator against the live screen
 *   healix_replace_locator  Write a new locator to the JSON file
 *   healix_screenshot    Take a debug screenshot
 *   healix_stop          Gracefully close the session
 *
 * Session discovery:
 *   Reads ~/.healix/sessions.json written by HealixApiServer at bind time.
 *   Stale entries are detected by HTTP probe at list time.
 *   All tools that target a specific session accept an optional `port` arg;
 *   when omitted, the first live session is used (single-session convenience).
 *
 * Usage:
 *   npx healix-mcp              # auto-discovers session on default port 3000
 *   HEALIX_PORT=3001 npx healix-mcp  # override target port
 *
 * MCP config (.mcp.json):
 *   { "mcpServers": { "healix": { "command": "npx", "args": ["healix-mcp"] } } }
 */
export interface ToolResponse {
    structured?: Record<string, unknown>;
    isError?: boolean;
    text?: string;
    data?: unknown;
    warnings?: string[];
    images?: {
        data: string;
        mimeType: string;
    }[];
}
export interface ToolEnvelopeSuccess {
    ok: true;
    data?: unknown;
    warnings: string[];
    sessionAlive: boolean | null;
}
export interface ToolEnvelopeError {
    ok: false;
    error: {
        tool: string;
        message: string;
    };
    warnings: string[];
    sessionAlive: boolean | null;
}
export type ToolEnvelope = ToolEnvelopeSuccess | ToolEnvelopeError;
/**
 * Filter a stack trace to frames pointing at user-owned files (Stack B —
 * test spec failures, page objects). Drops node_modules / framework
 * internals so the agent sees only frames it can actually edit.
 *
 * Usage (future): when a tool surfaces test-execution failures (e.g.
 * healix_run_test result carries a stack), pass the stack through this
 * helper before putting it in `data`. MCP tool-runtime errors (Stack A)
 * should still strip stack entirely — those live server-side in logs.
 */
export declare function filterUserFrames(stack: string | undefined, projectRoot?: string): string | undefined;