/**
 * Manager for handling uploaded session recording snapshots.
 *
 * This manager handles receiving archives (zip or tar.gz, same format as
 * sb-download), extracting them to a temporary directory, and tracking the
 * current upload state.
 *
 * Directory structure:
 * /tmp/superblocks-replay/{userId}/{uploadId}/
 *   ├── main/                     <- main archive extraction
 *   │   ├── .superblocks/
 *   │   │   ├── superblocks.json
 *   │   │   └── recordings/
 *   │   │       ├── sessions.json
 *   │   │       └── {sessionId}/
 *   │   │           ├── recording.jsonl
 *   │   │           └── snapshot.zip (or snapshot.tar.gz for older snapshots)
 *   │   ├── apis/
 *   │   ├── pages/
 *   │   └── ... (rest of app structure)
 *   └── {sessionId}/             <- session snapshot extraction
 *       ├── apis/
 *       ├── pages/
 *       └── ...
 */
import type { AppSnapshotMeta, SnapshotDetails, SnapshotState } from "@superblocksteam/library-shared/types";
/** Contents of `.superblocks/snapshot-restore.json`. */
export interface SnapshotRestoreTracking {
    uploadId: string;
    sourceDir: string;
    restoredAt: string | null;
}
/** Report produced by {@link SnapshotManager.sanitizeSourceIntegrations}. */
export interface SanitizationReport {
    /** Integration IDs that were sanitized (not recognized in the current environment). */
    sanitizedIntegrationIds: string[];
}
/**
 * Manager for uploaded session recording snapshots.
 *
 * Tracks the current upload state and handles extraction of uploaded archives
 * to a deterministic temporary directory structure.
 */
export declare class SnapshotManager {
    private readonly userId;
    private currentUpload;
    private readonly baseDir;
    /**
     * Create a new SnapshotManager.
     *
     * @param userId - Current user ID, used to namespace the temp directory
     */
    constructor(userId: string);
    /**
     * Get the main extraction subdirectory within an upload directory.
     * The main tar is extracted here; session extractions are siblings.
     */
    private mainDir;
    /**
     * Scan the base directory for recent uploads.
     * Returns the most recent upload within MAX_UPLOAD_AGE_MS, or null if none found.
     */
    private findRecentUpload;
    /**
     * Check if there's a currently uploaded snapshot.
     * Checks disk for recent uploads if no in-memory state exists.
     */
    hasUpload(): Promise<boolean>;
    /**
     * Get the current upload state.
     * If no in-memory state exists, checks disk for recent uploads (within 1 hour).
     *
     * @returns The current upload state, or null if no upload exists
     */
    getUpload(): Promise<SnapshotState | null>;
    /**
     * Get detailed information about the uploaded snapshot.
     * Reads superblocks.json for app ID and sessions.json for recording sessions.
     *
     * @returns Snapshot details, or null if no upload exists
     */
    getDetails(): Promise<SnapshotDetails | null>;
    /**
     * Upload and extract an archive (zip or tar.gz).
     *
     * This will clear any previous upload before extracting the new one.
     * The archive should be in the same format as sb-download.
     *
     * @param archiveBuffer - The archive buffer to extract (zip or tar.gz)
     * @returns The new upload state
     */
    upload(archiveBuffer: Buffer): Promise<SnapshotState>;
    /**
     * Clear the current upload and delete extracted files.
     */
    clear(): Promise<void>;
    /**
     * Prepare the source directory for a restore operation.
     *
     * - If no `sessionId` is provided, returns the main upload's extractedDir.
     * - If a `sessionId` is provided, extracts the session's snapshot
     *   to a temporary directory and returns that.
     * - Writes the current app's `.superblocks/superblocks.json` from `appRootDir`
     *   into the source dir so the restored tree keeps the app's identity/config.
     * - When `sanitizeIntegrations` is true and `availableIntegrationIds` is
     *   provided, replaces unrecognised integration steps with javascript stubs.
     *
     * The returned `dispose` function cleans up any temporary directory created
     * for session-based restores. It is a no-op when no temp dir was needed.
     *
     * @param uploadId - The upload ID to restore from (must match current upload)
     * @param sessionId - Optional session ID whose snapshot to extract
     * @param appRootDir - Current app root; its .superblocks/superblocks.json is copied into the source dir
     * @param availableIntegrationIds - Integration IDs available in the current environment
     * @param sanitizeIntegrations - When true, unknown integration steps are replaced with JS stubs
     * @returns The source directory and a dispose callback
     */
    prepareRestoreSource(uploadId: string, sessionId: string | undefined, appRootDir: string, availableIntegrationIds?: Set<string>, sanitizeIntegrations?: boolean): Promise<{
        sourceDir: string;
        dispose: () => Promise<void>;
    }>;
    /**
     * List immediate subdirectory names under `apis/` and `pages/` within a directory.
     */
    private computeSnapshotMeta;
    /**
     * Detect archive format from magic bytes and extract into `destDir`.
     *
     * Accepts either a Buffer (for uploaded archives) or a file path string
     * (for session snapshots on disk). Supports both zip and tar.gz formats.
     */
    private extractArchive;
    /**
     * Get the deterministic extraction directory and snapshot path for a session.
     *
     * The snapshot lives inside the main extraction; the session extraction dir
     * is a sibling of `main/` under the upload root. Prefers `snapshot.zip`,
     * falling back to `snapshot.tar.gz` for older snapshots.
     */
    private getSessionExtractionDir;
    /**
     * Extract a session snapshot to its deterministic directory if not already extracted.
     */
    private ensureSessionExtracted;
    /**
     * Analyze a snapshot (or session snapshot) and return metadata about its contents.
     *
     * - If no `sessionId` is provided, scans the main upload's extracted directory.
     * - If a `sessionId` is provided, extracts the session's snapshot to a
     *   deterministic directory (reused by prepareRestoreSource) and scans it.
     *
     * @param uploadId - The upload ID to analyze (must match current upload)
     * @param sessionId - Optional session ID whose snapshot to analyze
     * @returns Metadata about the snapshot contents
     */
    analyze(uploadId: string, sessionId?: string): Promise<AppSnapshotMeta>;
    /**
     * Scan the `apis/` directory within a snapshot source, compare the
     * integration IDs found in each API's blocks against a set of IDs
     * available in the current environment, and replace any unrecognised
     * integration steps with a javascript stub.
     *
     * @param sourceDir - Root of the extracted snapshot (contains `apis/`)
     * @param availableIntegrationIds - IDs present in the current environment
     * @returns A report listing the integration IDs that were sanitized
     */
    sanitizeSourceIntegrations(sourceDir: string, availableIntegrationIds: Set<string>): Promise<SanitizationReport>;
    /**
     * Restore snapshot files into `appRootDir`.
     *
     * Clears everything in `appRootDir` except node_modules, .git, build, then
     * copies the prepared source directory (which already has the correct
     * .superblocks/superblocks.json from prepareRestoreSource) into app root.
     */
    copySnapshotToAppRoot(sourceDir: string, appRootDir: string): Promise<void>;
    /**
     * Write a tracking file that records a pending snapshot restore.
     * On the next dev-server startup, `executePendingRestore` will read it
     * and perform the actual restore.
     */
    createPendingRestore(appRootDir: string, uploadId: string, sourceDir: string): Promise<void>;
    /**
     * Check for a pending snapshot restore and execute it if found.
     *
     * Note: `copySnapshotToAppRoot` clears the app root, so the tracking data
     * is read into memory first and re-written with a `restoredAt` timestamp
     * after the copy.
     *
     * @returns `true` if a restore was performed, `false` otherwise
     */
    executePendingRestore(appRootDir: string): Promise<boolean>;
}
/**
 * Error thrown when a restore operation fails due to a user-facing issue
 * (e.g. upload not found, session snapshot missing).
 */
export declare class SnapshotRestoreError extends Error {
    constructor(message: string);
}
//# sourceMappingURL=snapshot-manager.d.ts.map