import type { FetchableRef } from '../generators/pdf-registry.js';
/** Outcome of attempting to cache a single reference. */
export type RefOutcome = {
    kind: 'downloaded' | 'cached' | 'failed';
    filename: string;
};
export declare const REFERENCE_MANIFEST_FILENAME = "setup-agents-reference-manifest.json";
export declare const REFERENCE_PARSER_VERSION = "2";
export type ReferenceManifestEntry = {
    filename: string;
    sourceUrl: string;
    profileIds: string[];
    scope: string;
    resolvedVersion?: string;
    fetchedAt: string;
    etag?: string;
    lastModified?: string;
    contentDigest?: string;
    parserVersion: string;
    contamination: 'clean' | 'contaminated' | 'unknown';
    status: 'success' | 'failure' | 'partial';
    error?: string;
};
export type ReferenceManifest = {
    schemaVersion: 1;
    entries: ReferenceManifestEntry[];
};
export type ReferenceHealthIssue = {
    filename: string;
    kind: 'missing' | 'stale' | 'contaminated' | 'foreign' | 'mis-scoped' | 'source-missing';
    action: string;
};
export type ReferenceHealth = {
    status: 'healthy' | 'unhealthy' | 'not-configured';
    complete: boolean;
    configuredProfiles: string[];
    issues: ReferenceHealthIssue[];
    manifestPath: string;
};
export type FetchReferencesResult = {
    downloaded: string[];
    cached: string[];
    failed: string[];
    /** PDF references that were converted to `<name>.md` during this run. */
    extracted: string[];
    refsDir: string;
    cwd: string;
    aborted: boolean;
};
type ReferenceFetchResponse = {
    ok: boolean;
    status: number;
    headers?: {
        get(name: string): string | null;
    };
    arrayBuffer(): Promise<ArrayBuffer>;
};
export type FetchReferencesHooks = {
    /**
     * Re-fetch and re-convert even when a cached file already exists. Off by default
     * (the cache is idempotent), but needed to re-generate references written by an
     * older extractor — e.g. pre-GH-522 `.md` that still carry stripped SPA bootstrap
     * scripts. `update --fetch-refs --force` sets this (GH-522 follow-up).
     */
    force?: boolean;
    /** Informational log line (e.g. "Downloaded: foo.pdf"). */
    log?: (message: string) => void;
    /** Warning line for a single ref failure — never throws, never fails the run. */
    warn?: (filename: string, reason: string) => void;
    /**
     * PDF→Markdown extractor. Injectable for testing. Defaults to the shared
     * {@link extractPdfToMarkdown} (pdf-parse based). Returns markdown text, or
     * an empty string on parse failure.
     */
    extractPdf?: (data: Buffer, signal?: AbortSignal) => Promise<string>;
    /**
     * Resolver for the authoritative, version-current PDF URL from a deliverable
     * key. Injectable for testing. Defaults to {@link resolvePdfUrl}. Returns the
     * resolved URL, or `null` when no PDF exists / resolution fails (the fetcher
     * then falls back to the ref's constructed candidate URL).
     */
    resolvePdf?: (deliverable: string, signal?: AbortSignal) => Promise<string | null>;
    /**
     * Resolver for server-rendered Atlas HTML content from a deliverable key.
     * Injectable for testing. Defaults to {@link resolveAtlasContent}. Returns the
     * server-rendered HTML, or `null` when the deliverable exposes no content via
     * the metadata API (the fetcher then falls back to fetching the raw `.htm`).
     */
    resolveContent?: (deliverable: string, signal?: AbortSignal) => Promise<string | null>;
    /**
     * Resolver for `help.salesforce.com` article content from a help-article
     * id. Injectable for testing. Defaults to {@link resolveHelpArticleContent}.
     * Returns the article body, or `null` when the id doesn't resolve /
     * resolution fails (the fetcher then falls back to fetching the raw
     * `.htm`, which the shell-detection guard below rejects).
     */
    resolveHelpArticle?: (articleId: string, signal?: AbortSignal) => Promise<string | null>;
    /**
     * Download implementation. Injectable for testing. Defaults to {@link docFetch},
     * which applies the bundled Salesforce-docs intermediate CA only for Salesforce
     * documentation CDN hosts (completing their incomplete TLS chain) and delegates
     * every other host to the global `fetch` with default verification. The second
     * argument is the timeout in milliseconds.
     */
    fetchImpl?: (url: string, timeoutMs: number, signal?: AbortSignal) => Promise<ReferenceFetchResponse>;
    now?: () => Date;
    signal?: AbortSignal;
    concurrency?: number;
    operationTimeoutMs?: number;
    overallTimeoutMs?: number;
};
/**
 * Shared download + cache + PDF→Markdown routine used by both
 * `update --fetch-refs` and `init` onboarding.
 *
 * For each ref:
 * - If the cached file already exists, it is classified `cached` and not re-fetched.
 * - Otherwise it is downloaded to `.setup-agents/references/<filename>` with a timeout.
 * - A non-OK status or network throw is classified `failed` (warned, never thrown).
 *
 * After a successful PDF download (`.pdf`), the buffer is also converted to
 * `.setup-agents/references/<name>.md` via {@link extractPdfToMarkdown} so agents
 * read Markdown instead of the raw PDF. MD extraction is best-effort: a parse
 * failure warns and is skipped. Extraction is idempotent — if the `.md` already
 * exists it is not regenerated.
 *
 * HTML references (`.htm`/`.html`) for Atlas docs are client-rendered SPAs whose
 * raw URL yields only a ~21-char JS shell. When such a ref carries a deliverable
 * key, the server-rendered content is resolved via {@link resolveAtlasContent}
 * and persisted (plus a `.md` sibling) instead of the shell. As a
 * belt-and-suspenders guard, any HTML fetch whose visible text falls below
 * {@link MIN_HTML_VISIBLE_CHARS} is classified `failed` rather than cached, so a
 * future SPA URL can never silently cache a useless shell.
 *
 * This function never rejects on a per-ref network/parse failure; callers can
 * treat it as best-effort and rely on the returned classification.
 */
export declare function fetchReferences(cwd: string, refs: FetchableRef[], hooks?: FetchReferencesHooks): Promise<FetchReferencesResult>;
export declare function readReferenceManifest(cwd: string): ReferenceManifest;
export declare function assessReferenceHealth(cwd: string, expectedRefs: FetchableRef[], configuredProfiles: string[], now?: Date): ReferenceHealth;
/** True when a reference `.md`'s text carries leftover SPA bootstrap scripts. */
export declare function isContaminatedReferenceMarkdown(markdown: string): boolean;
/**
 * Scan the workspace's cached reference `.md` files and return the filenames whose
 * content still carries leftover SPA bootstrap scripts (pre-GH-522 stale cache).
 * Returns [] when the references dir is absent or everything is clean. Never throws.
 *
 * The fix for any hit is `update --fetch-refs --force`, which re-derives the `.md`
 * from the cached HTML bytes with the current (script-stripping) extractor.
 */
export declare function findContaminatedReferences(cwd: string): string[];
export {};