/**
 * Resolving `exampleProjectSource` to a directory on disk.
 *
 * The field takes either a filesystem path (resolved against the config
 * file's directory) or a GitHub URL pointing at a stack's example inside
 * a repository. The URL form is what a real project uses: the stacks live
 * in farketari's REPOSITORY and not in its npm package, so a project that
 * installed farketari from npm has no example anywhere on disk.
 *
 * A remote source is fetched into a cache keyed by repository and ref, and
 * reused. The fetch is a shallow, blobless, sparse `git clone`, so only the
 * named subdirectory is materialised and private repositories work through
 * whatever credentials git already has — no token handling here.
 *
 * ONE checkout serves every subdirectory of a repo+ref: asking for a second
 * one (the skeleton, then the example; or two different stacks) ADDS it to
 * the sparse set rather than re-cloning. The cache key deliberately omits
 * the subdir — a second clone of the same commit would be pure waste.
 *
 * Freshness follows what the ref MEANS, which is the whole point:
 * - a commit SHA is immutable, so a checkout of one is never stale;
 * - a TAG is a promise not to move, so it is pinned once fetched;
 * - a BRANCH is a moving target, so the cached copy is checked against the
 *   remote on every use and fast-forwarded when it has moved.
 *
 * Pinning a branch at first fetch — the previous behaviour — bought
 * reproducibility nobody asked for and cost hours: a project bootstrapped
 * from a stale `main` keeps re-delivering the same broken skeleton, and
 * nothing on screen says the copy is old. Name a tag or a SHA when you
 * want a pin; that is what they are for.
 *
 * Being offline is not an error: when the remote cannot be reached the
 * cached copy is used and the fallback is announced.
 * FARKETARI_REFRESH_EXAMPLE=1 still forces a clean re-clone.
 */
/** A GitHub URL broken into the parts a sparse checkout needs. */
export interface RemoteExampleSource {
    owner: string;
    repo: string;
    /** Branch, tag or commit SHA. */
    ref: string;
    /** Repo-relative directory the example lives in; "" for the repo root. */
    subdir: string;
}
/** True when a source is a URL rather than a filesystem path. */
export declare function isRemoteSource(source: string): boolean;
/**
 * Parse a GitHub "tree" URL — the address you get from the browser when
 * looking at a directory. Returns null for anything else, so the caller
 * can report the shape it wanted.
 */
export declare function parseGitHubTreeUrl(url: string): RemoteExampleSource | null;
/** Where fetched examples are kept. Overridable for tests and CI. */
export declare function exampleCacheRoot(): string;
/**
 * The checkout directory for one repo-and-ref pair.
 *
 * Deliberately NOT keyed by subdirectory: one checkout serves every
 * subdirectory of the same commit, and asking for another one adds it to
 * the sparse set (see ensureSubdirectory).
 */
export declare function checkoutDirFor(source: RemoteExampleSource, cacheRoot: string): string;
/**
 * True for an object id. A checkout of one can never be stale, so it is
 * never re-checked against the remote.
 */
export declare function isCommitSha(ref: string): boolean;
/**
 * Ensure a remote directory is on disk, and answer where. Clones on first
 * use; afterwards reuses the checkout, refreshing it when the ref is a
 * branch and adding the subdirectory when it is not materialised yet.
 */
export declare function fetchRemoteDirectory(url: string, options?: {
    cacheRoot?: string;
    refresh?: boolean;
    log?: (message: string) => void;
}): Promise<string>;