/**
 * lib.ts — pure, side-effect-free helpers extracted from index.ts.
 * Imported by both the MCP server and the unit test suite.
 */
export interface PlatformConfig {
    appEnvVar?: string;
    defaultApp?: string;
    wdioConf?: string;
    /** Optional URL the service navigates to before the first test (C1 start-url feature). */
    startUrl?: string;
}
export interface AgentConfig {
    platforms: Record<string, PlatformConfig>;
    wdioConf?: string;
}
export interface SessionEntry {
    id: string;
    /**
     * Globally-unique per-launch handle minted by the worker at registration
     * (crypto.randomUUID()). This is the value the MCP requires callers to pass back as
     * `sessionId` on every session-scoped tool call — it is what `resolveSession()`
     * looks up, replacing the old cwd/first-live-session fallback that silently
     * collapsed concurrent agents onto the same session. Optional only for legacy
     * entries written by a pre-upgrade worker.
     */
    launchId?: string;
    launchRequestId?: string;
    specPath?: string;
    /** W3C / WDIO browser.sessionId — authoritative driver-session handle. May be null until the browser exists. */
    sessionId?: string | null;
    pid: number;
    port: number;
    host: string;
    startedAt: string;
    /** The owning project's root (the worker's process.cwd()) — the ownership anchor. May be absent on legacy entries. */
    projectRoot?: string;
    /** 'own' = healix-launched; 'attached' = connected to a pre-existing/remote driver (never kill). */
    ownership?: 'own' | 'attached';
    suite: string | null;
    platform: string | null;
    device: string | null;
}
/** Normalize a string for fuzzy comparison: lowercase, strip separators. */
export declare function normalize(s: string): string;
/** Walk root for spec/test files (mirrors HealixApiServer.globSpecs). */
export declare function globSpecs(root: string): string[];
/** Walk root for page-object files (*.page.ts). Mirrors globSpecs' exclusions. */
export declare function globPoms(root: string): string[];
/**
 * Classify a POM source as a "plain-getter" page object: it looks like a page
 * object (declares a class) but uses neither @ScaffoldPage nor @Find — so Healix
 * cannot track it and its locators never self-heal. Returns the basename list of
 * such files under `root`.
 */
export declare function findPlainGetterPoms(root: string): string[];
/** Extract suite-name → spec-path map from wdio.conf.ts via text scan. */
export declare function extractSuites(projectRoot: string, wdioConf: string): Record<string, string>;
/**
 * Resolve a user-supplied spec identifier to an actual path.
 * Accepts: suite name, description (fuzzy), file path, or basename fragment.
 * Handles glob patterns in suite definitions by expanding to the first matching file.
 */
export declare function resolveSpec(spec: string, suites: Record<string, string>, projectRoot: string): {
    resolved: string;
    via: string;
} | null;
export type AgentConfigResult = {
    config: AgentConfig;
    error?: never;
} | {
    config: null;
    error: string;
};
export declare function readAgentConfig(projectRoot: string): AgentConfigResult;
/** Legacy single-file registry — read-only fallback for older workers. */
export declare const REGISTRY_PATH: string;
/** Per-session files: ~/.healix/sessions/<port>.json (one file per session, written by the worker). */
export declare const SESSIONS_DIR: string;
export declare const PIDS_PATH: string;
/**
 * Read all session entries. Prefers the per-session files under SESSIONS_DIR;
 * falls back to the legacy monolithic file only when the dir holds none (so a
 * not-yet-upgraded worker is still discoverable). `legacyPath` is the fallback
 * file (kept as a param for test injection / backward-compat call sites).
 */
export declare function readSessions(legacyPath?: string): SessionEntry[];
/** Delete a session's per-file entry (used to prune dead sessions). Best-effort. */
export declare function removeSessionFile(port: number, dir?: string): void;
/**
 * Normalize a project root for cross-process comparison: absolutize, forward
 * slashes, drop trailing slash, lowercase (Windows paths are case-insensitive).
 */
export declare function normalizeRoot(p: string | undefined | null): string;
/**
 * Find the session a given project+platform owns. The owner anchor is the
 * project root (the worker's cwd), which survives MCP and worker restarts.
 * Returns null if no entry matches — the MCP must never manage another
 * project's session.
 */
export declare function findOwnedSession(sessions: SessionEntry[], projectRoot: string, platform: string): SessionEntry | null;
/**
 * Resolve a session by its unique launchId — the explicit handle healix_start_session
 * returns and every session-scoped tool call requires back. Unlike findOwnedSession
 * (projectRoot+platform), this is exact-match only and deliberately has NO fallback (no
 * "first session", no cwd-based guess): two sessions can share the same projectRoot AND
 * platform (e.g. two agents' concurrent runs against the same app) and still resolve to
 * the correct one independently, as long as each caller holds and passes its own launchId.
 */
export declare function findSessionByLaunchId(sessions: SessionEntry[], launchId: string): SessionEntry | null;