/**
 * Represents a discovered cartridge in the local filesystem.
 */
export interface CartridgeMapping {
    /** Cartridge name (directory name containing .project) */
    name: string;
    /** Absolute path to the cartridge directory */
    src: string;
    /** Destination name (same as name, used for WebDAV path) */
    dest: string;
}
/**
 * Options for finding cartridges.
 */
export interface FindCartridgesOptions {
    /** Cartridge names to include (if empty, all are included) */
    include?: string[];
    /** Cartridge names to exclude */
    exclude?: string[];
    /**
     * Maximum directory depth to recurse when searching for `.project` files,
     * counted in path segments relative to the search directory (so a cartridge
     * at `cartridges/<name>/.project` is depth 3). When omitted the search is
     * unbounded (default), preserving behavior for callers that expect a full
     * recursive walk. Bound this for untrusted/broad roots (e.g. an MCP server
     * that may be launched from a home directory) to avoid scanning the whole
     * filesystem tree.
     */
    maxDepth?: number;
    /**
     * When true, stop at the first matching cartridge and return only that one.
     * Useful for existence checks (e.g. workspace-type detection) where the full
     * list is not needed — it lets the underlying scan short-circuit instead of
     * enumerating every `.project` file. Filters from `include`/`exclude` are
     * applied while scanning, so the returned cartridge always satisfies them.
     */
    firstMatchOnly?: boolean;
}
/**
 * Find cartridges recursively in a directory.
 *
 * Cartridges are identified by the presence of a `.project` file
 * (Eclipse project marker commonly used in SFCC development).
 *
 * @param directory - Directory to search for cartridges (defaults to cwd)
 * @param options - Filter options for including/excluding cartridges
 * @returns Array of discovered cartridge mappings
 *
 * @example
 * ```typescript
 * // Find all cartridges in current directory
 * const cartridges = findCartridges();
 *
 * // Find cartridges in specific directory
 * const cartridges = findCartridges('./my-project');
 *
 * // Find specific cartridges only
 * const cartridges = findCartridges('.', { include: ['app_storefront_base'] });
 *
 * // Find all except certain cartridges
 * const cartridges = findCartridges('.', { exclude: ['test_cartridge'] });
 * ```
 */
export declare function findCartridges(directory?: string, options?: FindCartridgesOptions): CartridgeMapping[];