import { type ChildProcess, type SpawnOptions } from "node:child_process";
import { type CacheDirContext } from "./cacheDir.js";
export type LogLevel = "info" | "warn" | "error" | "debug";
export type Logger = (msg: string, level?: LogLevel) => void;
export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
export interface LoaderDeps {
    spawn?: SpawnFn;
    logger?: Logger;
}
export interface LoadOptions {
    autoInstall?: boolean;
    ctx?: CacheDirContext;
    deps?: LoaderDeps;
}
/**
 * Resolve a heavy dep's entry path without importing it. Used by call
 * sites that need to spawn a binary directly (e.g. Appium via
 * `node <entry>.js`) rather than `await import()` the module — which
 * lets them bypass `.cmd` shim execution and the Windows shell:true
 * requirement entirely. Mirrors `loadHeavyDep`'s shim → cache fallback.
 * Returns `null` if neither location resolves the name.
 */
export declare function resolveHeavyDepPath(name: string, ctx?: CacheDirContext): string | null;
/**
 * Resolve a heavy dep's entry path from the runtime cache ONLY (no shim
 * fallback). Callers that must co-locate packages in one APPIUM_HOME (e.g.
 * a lazily-installed native Appium driver plus the Appium copy that loads
 * it) use this to confirm the cache-side copy specifically — the
 * shim-preferring resolveHeavyDepPath would mask a missing cache install.
 */
export declare function resolveHeavyDepPathInCache(name: string, ctx?: CacheDirContext): string | null;
/**
 * Where a heavy dep resolves from, or `null` if it doesn't resolve.
 * "shim" = the doc-detective package's own node_modules (a pre-installed
 * optionalDependency or dev checkout); "cache" = <cacheDir>/runtime. The
 * distinction matters for freshness: `ensureRuntimeInstalled` never
 * overrides a shim-resolved version but DOES reinstall a stale cache, so
 * callers reporting "outdated" must only apply the declared-range check to
 * cache resolutions.
 */
export declare function resolveHeavyDepSource(name: string, ctx?: CacheDirContext): "shim" | "cache" | null;
/**
 * Read the installed version of a heavy dep that's resolvable (shim
 * node_modules OR runtime cache) but may not be recorded in
 * <cacheDir>/installed.json — e.g. a pre-installed optionalDependency or a
 * dev checkout. Walks up from the resolved entry to the package's own
 * package.json (the first one whose `name` matches, so a nested
 * `dist/package.json` with only `{"type":"module"}` is skipped). Returns
 * `null` when the dep isn't resolvable or the version can't be read.
 */
export declare function resolveHeavyDepVersion(name: string, ctx?: CacheDirContext): string | null;
/**
 * Resolve and import a heavy dep, lazy-installing into <cacheDir>/runtime
 * if neither the shim's node_modules nor the cache currently has it. The
 * shim's own node_modules wins so a user who kept the optionalDependency
 * pre-installed never pays the lazy-install cost.
 */
export declare function loadHeavyDep<T = unknown>(name: string, options?: LoadOptions): Promise<T>;
export interface EnsureRuntimeInstalledOptions {
    ctx?: CacheDirContext;
    deps?: LoaderDeps;
    /** Reinstall even when the package already resolves from the cache. */
    force?: boolean;
    /**
     * Wall-clock cap on the spawned `npm install` child. Stalls (hanging
     * proxy, rate-limit, large dep tree on a flaky link) get terminated
     * instead of freezing the first `doc-detective` run forever. Defaults
     * to 5 minutes; pass `0` to disable the timeout entirely.
     */
    installTimeoutMs?: number;
}
/**
 * Install one or more heavy npm packages into <cacheDir>/runtime. Uses
 * `npm install --prefix <runtimeDir> --no-save --no-audit --no-fund <pkg>@<v>`
 * — `--prefix` confines npm to the cache dir, and the resolved version comes
 * from `package.json#optionalDependencies` via getDeclaredVersion().
 *
 * On success, refreshes <cacheDir>/installed.json with the actually-installed
 * versions for each package. Skips packages already present unless `force`.
 */
export declare function ensureRuntimeInstalled(packages: string[], options?: EnsureRuntimeInstalledOptions): Promise<void>;
//# sourceMappingURL=loader.d.ts.map