export declare function expandTilde(filePath: string, home?: string): string;
export declare function expandPath(filePath: string): string;
export declare function splitPathAndSel(rawPath: string): {
    path: string;
    sel?: string;
};
/**
 * Variant of {@link splitPathAndSel} for internal URLs (`scheme://...`).
 *
 * The filesystem-path splitter is intentionally conservative: it refuses to
 * peel a trailing `:<chunk>` unless that chunk matches the strict selector
 * grammar. That rule is right for filesystem paths (a file named `a:1-50` is
 * legal) but wrong for internal URLs, where any trailing `:<chunk>` after the
 * scheme is unambiguously a read-tool selector — even if malformed (e.g.
 * `artifact://3:raw:-100`).
 *
 * This function iteratively peels selector-shaped chunks (well-formed plus
 * common malformed shapes like `:-N`) so the rest of the read tool can pass a
 * clean URL to the protocol handler and surface selector errors via parseSel
 * instead of as misleading "host invalid" errors from the handler. Schemes
 * whose resource URIs may legitimately contain colons (`mcp://`) are skipped.
 *
 * Falls back to the input unchanged when nothing matches.
 */
export declare function splitInternalUrlSel(rawPath: string): {
    path: string;
    sel?: string;
};
export declare function normalizeLocalScheme(filePath: string): string;
export declare function isInternalUrlPath(filePath: string): boolean;
/**
 * Resolve a path relative to the given cwd.
 * Handles ~ expansion and absolute paths.
 *
 * A bare root slash is treated as a workspace-root alias for tool inputs. Users
 * often pass `/` to mean “search from here”, and letting tools escape to the
 * filesystem root is almost never what they intended.
 */
export declare function resolveToCwd(filePath: string, cwd: string): string;
export declare function formatPathRelativeToCwd(filePath: string, cwd: string, options?: {
    trailingSlash?: boolean;
}): string;
/**
 * Strip matching surrounding double quotes from a path string.
 * Common when users paste quoted paths from Windows Explorer or shell copy-paste.
 * Only double quotes — single quotes are valid POSIX filename characters.
 * Tradeoff: a POSIX path literally starting AND ending with " would also be unquoted.
 * Accepted because such names are virtually nonexistent in practice.
 */
export declare function stripOuterDoubleQuotes(input: string): string;
export declare function normalizePathLikeInput(input: string): string;
export declare function hasGlobPathChars(filePath: string): boolean;
export interface ParsedSearchPath {
    basePath: string;
    glob?: string;
}
export interface ParsedFindPattern {
    basePath: string;
    globPattern: string;
    hasGlob: boolean;
}
export interface ResolvedSearchTarget {
    basePath: string;
    glob?: string;
}
export interface ResolvedMultiSearchPath {
    basePath: string;
    glob?: string;
    scopePath: string;
    exactFilePaths?: string[];
    targets?: ResolvedSearchTarget[];
}
export interface ResolvedMultiFindPattern {
    basePath: string;
    globPattern: string;
    scopePath: string;
}
/**
 * Split a user path into a base path + glob pattern for tools that delegate to
 * APIs accepting separate `path` and `glob` arguments.
 */
export declare function parseSearchPath(filePath: string): ParsedSearchPath;
export declare function parseFindPattern(pattern: string): ParsedFindPattern;
export declare function combineSearchGlobs(prefixGlob?: string, suffixGlob?: string): string | undefined;
export declare function resolveExplicitSearchPaths(pathItems: string[], cwd: string, suffixGlob?: string): Promise<ResolvedMultiSearchPath | undefined>;
export declare function resolveExplicitFindPatterns(patternItems: string[], cwd: string): Promise<ResolvedMultiFindPattern | undefined>;
/**
 * Result of partitioning a list of user-supplied paths/globs into entries whose
 * base directory currently exists on disk versus those that do not.
 *
 * Used by multi-path tools (search, find, ast_grep, ast_edit) to tolerate one
 * or more missing entries in a multi-path call: the surviving entries should
 * still be searched, with the missing entries surfaced as a non-fatal warning.
 */
export interface PartitionedPaths {
    /** Raw input strings whose resolved base path exists. */
    valid: string[];
    /** Raw input strings whose resolved base path is missing (ENOENT). */
    missing: string[];
}
/**
 * Stat each input's base path concurrently; return entries split by existence.
 *
 * `splitter` is expected to be {@link parseFindPattern} or
 * {@link parseSearchPath}: both return a `basePath` field that this helper
 * resolves against `cwd` and stats. ENOENT is the only swallowed error — every
 * other stat failure (permission, IO, etc.) propagates so callers do not silently
 * skip paths that exist but are unreadable.
 *
 * Order of `valid` and `missing` follows the input order, so callers can rely
 * on `valid[0]` matching the first surviving user-supplied entry.
 */
export declare function partitionExistingPaths(items: string[], cwd: string, splitter: (item: string) => {
    basePath: string;
}): Promise<PartitionedPaths>;
export declare function resolveReadPath(filePath: string, cwd: string): string;
export interface ToolScopeOptions {
    rawPaths: string[];
    cwd: string;
    /** Verb used in the "Cannot {action} internal URL without a backing file: …" message. */
    internalUrlAction: string;
    /** Collect absolute paths flagged immutable by their internal-URL handler. */
    trackImmutableSources?: boolean;
    /** Honor `exactFilePaths` from {@link resolveExplicitSearchPaths} (search-only). */
    surfaceExactFilePaths?: boolean;
    /** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
    multipathStatHint?: string;
}
export interface ToolScopeResolution {
    searchPath: string;
    scopePath: string;
    globFilter: string | undefined;
    isDirectory: boolean;
    multiTargets?: ResolvedSearchTarget[];
    exactFilePaths?: string[];
    missingPaths: string[];
    immutableSourcePaths: Set<string>;
}
/**
 * Shared path-input pipeline for `search`, `ast_grep`, and `ast_edit`:
 *  1. normalize + reject empty paths,
 *  2. resolve internal URLs through {@link InternalUrlRouter} to backing files,
 *  3. partition existing vs missing when multiple paths are supplied,
 *  4. derive a single search base path / glob, or a multi-target list,
 *  5. stat the resolved base path so callers can branch on directory vs file scope.
 */
export declare function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution>;