import { type GlobOptionsWithFileTypesUnset } from "glob";
import type { DraftInterface } from "../../draft-interface.js";
import type { IOperationQueue } from "../../util/operation-queue.js";
import type { TemplateRenderer } from "../template-renderer.js";
import { type FileArtifact } from "../types.js";
import { type DraftChanges, type FileMetadata, type PathValidator } from "./filesystem/index.js";
import type { VirtualFileSystem } from "./filesystem/index.js";
/**
 * Options for listing files with optional metadata.
 */
export interface ListFilesOptions extends GlobOptionsWithFileTypesUnset {
    /** Include file metadata (size, mtime, type). Default: false */
    includeMetadata?: boolean;
    /** Include directories in listing. Default: false (files only) */
    includeDirs?: boolean;
}
/**
 * AppShell provides the primary interface for the AI agent to interact
 * with the application environment.
 *
 * It encapsulates:
 * - File system operations (read, write, delete, list, rename)
 * - Virtual file abstraction (APIs appear as single .ts files)
 * - Draft management for undo/redo capability
 * - Code quality tools (linting, type checking)
 * - Package management
 */
export declare class AppShell {
    readonly appRootDirPath: string;
    private readonly fsOperationQueue;
    private readonly linter;
    private messageSender?;
    private readonly draftManager?;
    private readonly templateRenderer?;
    private readonly virtualFs;
    private readonly pathValidator;
    private readonly enableDeletingLockfiles;
    /**
     * Tracks files that must be read before they can be written.
     * Used to enforce read-before-write pattern for AI safety.
     */
    private readonly requiredReads;
    constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, }: {
        appRootDirPath: string;
        fsOperationQueue: IOperationQueue;
        messageSender?: (message: any) => Promise<void>;
        draftInterface?: DraftInterface;
        templateRenderer?: TemplateRenderer;
        virtualFileSystem: VirtualFileSystem;
        /** Path validator for template-specific path restrictions */
        pathValidator: PathValidator;
        /** Feature flag to allow deleting package-manager lock files */
        enableDeletingLockfiles?: boolean;
    });
    /**
     * Toggle the API virtual-file projection. When disabled, reads to `apis/*`
     * bypass the YAML→TS transformer and fall through to raw disk, which is what
     * v2→v3 migration needs so Clark sees the original YAML sources.
     */
    setApiHandlerEnabled(enabled: boolean): void;
    /**
     * Enqueue a filesystem operation and annotate queue timing in llmobs.
     * This helps separate queue contention from operation execution time.
     */
    private enqueueFsOperation;
    readFiles(patterns: string[], globOptions?: GlobOptionsWithFileTypesUnset, enableAppBlacklist?: boolean): Promise<FileArtifact[]>;
    runTypecheck(abortSignal?: AbortSignal): Promise<Record<string, string[]> | null>;
    runTypecheckRawOutput(abortSignal?: AbortSignal): Promise<string | null>;
    runLinter(filePaths: string[], abortSignal?: AbortSignal): Promise<Record<string, string[]> | null>;
    warmLinterCache(): void;
    runNpmInstall(abortSignal?: AbortSignal): Promise<void>;
    runPackageManagerInstall(abortSignal?: AbortSignal): Promise<string>;
    installSpecificPackages(packages: Array<{
        name: string;
        version?: string;
        dev?: boolean;
    }>, abortSignal?: AbortSignal): Promise<string>;
    uninstallPackages(packages: string[], options?: {
        abortSignal?: AbortSignal;
    }): Promise<{
        stdout: string;
        stderr: string;
    }>;
    private static readonly MAX_GENERATION_RUNS;
    saveGeneratedArtifact(artifact: FileArtifact, stepId: string, runTimestamp: string): Promise<void>;
    pruneGenerations(keepLast?: number): Promise<void>;
    sendMessage(message: {
        type: string;
        payload?: any;
    }): Promise<void>;
    /** Check if a given path exists in the app dir. */
    pathExists(relativePath: string): Promise<boolean>;
    /**
     * Clears the scratch directory used for temporary API source files.
     * This is typically called when a draft is rejected to clean up temporary artifacts.
     */
    clearScratchDirectory(): Promise<void>;
    /**
     * Reads a single file's content from the application.
     *
     * Handles virtual path translation for files managed by the VirtualFileSystem:
     * - Virtual paths are read via the appropriate handler
     * - Regular files are read directly from disk
     *
     * @param relativePath - The virtual path relative to app root
     * @param options - Optional read options
     * @param options.offset - Line number to start reading from (1-indexed)
     * @param options.limit - Number of lines to read
     * @returns The file content as a string
     * @throws Error if file does not exist or cannot be read
     */
    readFile(relativePath: string, options?: {
        offset?: number;
        limit?: number;
    }): Promise<string>;
    /**
     * Internal read implementation (no queue).
     * Use this from other methods that are already enqueued to avoid deadlock.
     */
    private readFileInternal;
    /**
     * Writes content to a file as a draft.
     *
     * Handles virtual path translation for files managed by the VirtualFileSystem:
     * - Virtual paths are written via the appropriate handler
     * - Regular files are written via the draft interface
     *
     * @param relativePath - Virtual path relative to app root
     * @param content - File content to write
     * @param options - Optional write options
     * @param options.bypassRequireRead - Skip the read-before-write check (use for new files)
     * @throws Error if path is blacklisted, restricted, or draft manager not configured
     * @throws Error if file requires reading first (unless bypassed)
     */
    writeFile(relativePath: string, content: string, options?: {
        bypassRequireRead?: boolean;
    }): Promise<void>;
    /**
     * Internal write implementation.
     * Called directly by writeFile (no queue wrapper needed since draftInterface queues).
     */
    private writeFileInternal;
    /**
     * Deletes a file or directory as a draft operation.
     *
     * Handles virtual path translation for files managed by the VirtualFileSystem:
     * - Virtual paths delete via the appropriate handler
     * - Regular files/directories are deleted via the draft interface
     *
     * @param relativePath - Virtual path relative to app root
     * @throws Error if path is protected or draft manager not configured
     */
    deleteFile(relativePath: string): Promise<void>;
    /**
     * Internal delete implementation.
     * Called directly by deleteFile (no queue wrapper needed since draftInterface queues).
     */
    private deleteFileInternal;
    /**
     * Lists files matching patterns, returning virtual paths.
     *
     * Physical files managed by the VirtualFileSystem are converted to
     * their virtual representations (e.g., apis/MyAPI/api.yaml -> apis/MyAPI.ts).
     *
     * @param patterns - Glob patterns to match (defaults to application files)
     * @param options - Glob options
     * @returns Array of matching virtual file paths
     */
    listFiles(patterns?: string[], options?: GlobOptionsWithFileTypesUnset): Promise<string[]>;
    /**
     * Lists files matching patterns with metadata.
     *
     * @param patterns - Glob patterns to match (defaults to application files)
     * @param options - Options including includeMetadata: true
     * @returns Array of FileMetadata objects
     */
    listFiles(patterns?: string[], options?: ListFilesOptions & {
        includeMetadata: true;
    }): Promise<FileMetadata[]>;
    /**
     * Internal list implementation (no queue).
     * Use this from other methods that are already enqueued to avoid deadlock.
     *
     * @param patterns - Glob patterns to match
     * @param options - Glob options
     * @returns Array of virtualized file paths (physical API paths converted to virtual)
     */
    private listFilesInternal;
    /**
     * Gets metadata for a list of file paths.
     *
     * @param paths - Array of virtual paths to get metadata for
     * @returns Array of FileMetadata objects (excludes paths that don't exist)
     */
    private getFileMetadataList;
    /**
     * Gets metadata for a single file path.
     *
     * @param virtualPath - The virtual path to get metadata for
     * @returns FileMetadata or undefined if file doesn't exist
     */
    private getFileMetadata;
    /**
     * Gets metadata for a virtual API file.
     * Checks scratch file first (for pending changes), then falls back to YAML.
     *
     * @param virtualPath - The virtual API path (e.g., "apis/MyAPI.ts")
     * @returns FileMetadata or undefined if not found
     */
    private getApiFileMetadata;
    /**
     * Renames or moves a file.
     *
     * Implemented as read + write + delete to work with the draft system.
     *
     * @param oldPath - Current virtual path
     * @param newPath - New virtual path
     * @throws Error if old file doesn't exist or new path is invalid
     * @throws Error if old file requires reading first
     */
    renameFile(oldPath: string, newPath: string): Promise<void>;
    /**
     * Checks if there are any pending draft changes.
     *
     * @returns true if there are uncommitted draft changes
     */
    hasDraftChanges(): Promise<boolean>;
    /**
     * Gets a unified diff of pending draft changes.
     *
     * @param paths - Optional specific paths to diff. If empty, diffs all changes.
     * @returns Unified diff string
     */
    getDraftDiff(paths?: string[]): Promise<string>;
    /**
     * Gets categorized draft changes.
     *
     * @returns Object containing arrays of edited, added, and deleted paths
     */
    getDraftChanges(): Promise<DraftChanges>;
    /**
     * Gets the underlying draft interface for direct access.
     *
     * This should only be used for advanced operations that require
     * direct access to the draft interface. Prefer using the AppShell
     * methods when possible.
     *
     * @internal
     */
    getDraftInterface(): DraftInterface | undefined;
    /**
     * Check if a file must be read before it can be written.
     *
     * @param relativePath - The path to check
     * @returns true if the file must be read before writing
     */
    isReadRequired(relativePath: string): boolean;
    /**
     * Mark a file as requiring a read before write.
     *
     * Call this when a file has been modified externally (e.g., by lint/format)
     * to ensure the AI reads the updated content before making further changes.
     *
     * @param relativePath - The path to mark as requiring read
     */
    requireRead(relativePath: string): void;
    /**
     * Mark a file as having been read, allowing subsequent writes.
     * Called internally after successful read operations.
     */
    private markRead;
    private getFileOperationBlacklistOptions;
    /**
     * Recursively deletes directory contents by creating draft deletes.
     */
    private deleteDirectoryRecursive;
}
//# sourceMappingURL=shell.d.ts.map