Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

15.8 KB
Raw Blame
import Darwin
import Foundation

/// Manages the application's home directory and virtual machine directories.
/// Responsible for creating, accessing, and validating the application's directory structure.
final class Home {
    // MARK: - Constants

    private enum Constants {
        static let defaultDirectoryName = ".lume"
        static let homeDirPath = "~/\(defaultDirectoryName)"
    }

    // MARK: - Properties

    private var _homeDir: Path
    private let settingsManager: SettingsManager
    private let fileManager: FileManager
    private var locations: [String: VMLocation] = [:]

    // Current home directory based on default location
    var homeDir: Path {
        return _homeDir
    }

    // MARK: - Initialization

    init(
        settingsManager: SettingsManager = SettingsManager.shared,
        fileManager: FileManager = .default
    ) {
        self.settingsManager = settingsManager
        self.fileManager = fileManager

        // Get home directory path from settings or use default
        let settings = settingsManager.getSettings()
        guard let defaultLocation = settings.defaultLocation else {
            fatalError("No default VM location found")
        }

        self._homeDir = Path(defaultLocation.path)

        // Cache all locations
        for location in settings.vmLocations {
            locations[location.name] = location
        }
    }

    // MARK: - VM Directory Management

    /// Creates a temporary VM directory with a unique identifier
    /// - Returns: A VMDirectory instance representing the created directory
    /// - Throws: HomeError if directory creation fails
    func createTempVMDirectory() throws -> VMDirectory {
        let uuid = UUID().uuidString
        let tempDir = homeDir.directory(uuid)

        Logger.info("Creating temporary directory", metadata: ["path": tempDir.path])

        do {
            try createDirectory(at: tempDir.url)
            return VMDirectory(tempDir)
        } catch {
            throw HomeError.directoryCreationFailed(path: tempDir.path)
        }
    }

    /// Gets a VM directory for a specific VM name and optional location
    ///
    /// - Parameters:
    ///   - name: Name of the VM directory
    ///   - storage: Optional name of the VM location (default: default location)
    /// - Returns: A VMDirectory instance
    /// - Throws: HomeError if location not found
    func getVMDirectory(_ name: String, storage: String? = nil) throws -> VMDirectory {
        // Special case for ephemeral storage using macOS temporary directory
        if let storage = storage, storage == "ephemeral" {
            // Get the current temporary directory
            let tmpDir = ProcessInfo.processInfo.environment["TMPDIR"] ?? "/tmp"
            // Remove trailing slash if present
            let cleanPath = tmpDir.hasSuffix("/") ? String(tmpDir.dropLast()) : tmpDir
            
            // Create the directory if it doesn't exist
            if !fileExists(at: cleanPath) {
                try createVMLocation(at: cleanPath)
            }
            
            let baseDir = Path(cleanPath)
            return VMDirectory(baseDir.directory(name))
        }

        // Check if storage is a direct path
        if let storage = storage, (storage.contains("/") || storage.contains("\\")) {
            let cleanPath = storage.hasSuffix("/") ? String(storage.dropLast()) : storage
            let baseDir = Path(cleanPath)
            return VMDirectory(baseDir.directory(name))
        }

        let location: VMLocation

        if let storage = storage {
            // Get a specific location
            guard let loc = locations[storage] else {
                throw VMLocationError.locationNotFound(name: storage)
            }
            location = loc
        } else {
            // Use default location
            let settings = settingsManager.getSettings()
            guard let defaultLocation = settings.defaultLocation else {
                throw HomeError.invalidHomeDirectory
            }
            location = defaultLocation
        }

        let baseDir = Path(location.expandedPath)
        return VMDirectory(baseDir.directory(name))
    }
    
    /// Gets a VM directory from a direct file path
    ///
    /// - Parameters:
    ///   - name: Name of the VM directory
    ///   - storagePath: Direct file system path where the VM is located
    /// - Returns: A VMDirectory instance
    /// - Throws: HomeError if path is invalid
    func getVMDirectoryFromPath(_ name: String, storagePath: String) throws -> VMDirectory {
        let baseDir = Path(storagePath)
        
        // Create the directory if it doesn't exist
        if !fileExists(at: storagePath) {
            Logger.info("Creating storage directory", metadata: ["path": storagePath])
            try createVMLocation(at: storagePath)
        } else if !isValidDirectory(at: storagePath) {
            // Path exists but isn't a valid directory
            throw HomeError.invalidHomeDirectory
        }
        
        return VMDirectory(baseDir.directory(name))
    }

    /// Returns all initialized VM directories across all locations
    /// - Returns: An array of VMDirectory instances with location info
    /// - Throws: HomeError if directory access is denied
    func getAllVMDirectories() throws -> [VMDirectoryWithLocation] {
        var results: [VMDirectoryWithLocation] = []

        // Loop through all locations
        let settings = settingsManager.getSettings()

        // Note: We intentionally do NOT scan TMPDIR for ephemeral VMs.
        // Ephemeral VMs are short-lived and should be explicitly managed by the code
        // that creates them, not automatically discovered. Scanning TMPDIR would pick up
        // test leftovers and other temporary directories that happen to look like VMs.

        for location in settings.vmLocations {
            let locationPath = Path(location.expandedPath)

            // Skip non-existent locations
            if !locationPath.exists() {
                continue
            }

            do {
                let allFolders = try fileManager.contentsOfDirectory(
                    at: locationPath.url,
                    includingPropertiesForKeys: nil
                )

                let folders =
                    allFolders
                    .compactMap { url in
                        let sanitizedName = sanitizeFileName(url.lastPathComponent)
                        let dir = VMDirectory(locationPath.directory(sanitizedName))
                        let dirWithLoc =
                            dir.initialized()
                            ? VMDirectoryWithLocation(directory: dir, locationName: location.name)
                            : nil
                        return dirWithLoc
                    }

                results.append(contentsOf: folders)
            } catch {
                Logger.error(
                    "Failed to access VM location",
                    metadata: [
                        "location": location.name,
                        "error": error.localizedDescription,
                    ])
                // Continue to next location rather than failing completely
            }
        }

        return results
    }

    /// Copies a VM directory to a new location with a new name
    /// - Parameters:
    ///   - sourceName: Name of the source VM
    ///   - destName: Name for the destination VM
    ///   - sourceLocation: Optional name of the source location
    ///   - destLocation: Optional name of the destination location
    /// - Throws: HomeError if the copy operation fails
    func copyVMDirectory(
        from sourceName: String,
        to destName: String,
        sourceLocation: String? = nil,
        destLocation: String? = nil
    ) throws {
        let sourceDir = try getVMDirectory(sourceName, storage: sourceLocation)
        let destDir = try getVMDirectory(destName, storage: destLocation)

        // Check if destination directory exists at all
        if destDir.exists() {
            throw HomeError.directoryAlreadyExists(path: destDir.dir.path)
        }

        do {
            try fileManager.copyItem(atPath: sourceDir.dir.path, toPath: destDir.dir.path)
        } catch {
            throw HomeError.directoryCreationFailed(path: destDir.dir.path)
        }
    }

    /// Clones a complete VM state using APFS clonefile for disk.img (and a saved machine
    /// state, when `includeSavedState`) and regular copies for auxiliary files. macOS disk
    /// and auxiliary storage must remain paired because boot policy state spans both files.
    /// - Parameters:
    ///   - sourceName: Name of the source VM
    ///   - destName: Name for the destination VM
    ///   - sourceLocation: Optional name of the source location
    ///   - destLocation: Optional name of the destination location
    /// - Throws: HomeError if the clone operation fails
    func cloneVMDirectory(
        from sourceName: String,
        to destName: String,
        sourceLocation: String? = nil,
        destLocation: String? = nil,
        includeSavedState: Bool = false
    ) throws {
        let sourceDir = try getVMDirectory(sourceName, storage: sourceLocation)
        let destDir = try getVMDirectory(destName, storage: destLocation)

        // Check if destination directory exists at all
        if destDir.exists() {
            throw HomeError.directoryAlreadyExists(path: destDir.dir.path)
        }

        // Create the destination directory
        do {
            try fileManager.createDirectory(
                atPath: destDir.dir.path,
                withIntermediateDirectories: true
            )
        } catch {
            throw HomeError.directoryCreationFailed(path: destDir.dir.path)
        }

        // Enumerate files in the source directory and copy/clone each one
        let sourceURL = sourceDir.dir.url
        let destURL = destDir.dir.url
        let contents: [URL]
        do {
            contents = try fileManager.contentsOfDirectory(
                at: sourceURL,
                includingPropertiesForKeys: nil
            )
        } catch {
            throw HomeError.directoryCreationFailed(path: sourceDir.dir.path)
        }

        for fileURL in contents {
            let fileName = fileURL.lastPathComponent
            let destFileURL = destURL.appendingPathComponent(fileName)

            // A saved machine state is cloned only when asked for (the clone
            // then keeps the source's MAC address and machine identifier,
            // which the state is bound to); a half-written one never.
            if fileName.hasPrefix(sourceDir.statePath.name) {
                guard includeSavedState, fileName == sourceDir.statePath.name else { continue }
            }
            // The state's device marker goes with the state; a running VM's
            // forwards never go to a clone.
            if fileName == sourceDir.stateVsockPath.name && !includeSavedState { continue }
            if fileName == sourceDir.vsockSessionPath.name { continue }

            if fileName == "disk.img" || fileName == sourceDir.statePath.name {
                // Use clonefile(2) for disk.img (instant APFS copy-on-write)
                let result = Darwin.clonefile(
                    fileURL.path,
                    destFileURL.path,
                    0
                )
                if result != 0 {
                    // Fallback to regular copy if clonefile fails (e.g., cross-volume)
                    Logger.info(
                        "clonefile failed for disk.img, falling back to regular copy",
                        metadata: ["errno": "\(errno)"]
                    )
                    do {
                        try fileManager.copyItem(at: fileURL, to: destFileURL)
                    } catch {
                        throw HomeError.directoryCreationFailed(path: destDir.dir.path)
                    }
                }
            } else {
                // Regular copy for small files (config.json, nvram.bin, etc.)
                do {
                    try fileManager.copyItem(at: fileURL, to: destFileURL)
                } catch {
                    throw HomeError.directoryCreationFailed(path: destDir.dir.path)
                }
            }
        }
    }

    // MARK: - Location Management

    /// Adds a new VM location
    /// - Parameters:
    ///   - name: Location name
    ///   - path: Location path
    /// - Throws: Error if location cannot be added
    func addLocation(name: String, path: String) throws {
        let location = VMLocation(name: name, path: path)
        try settingsManager.addLocation(location)

        // Update cache
        locations[name] = location
    }

    /// Removes a VM location
    /// - Parameter name: Location name
    /// - Throws: Error if location cannot be removed
    func removeLocation(name: String) throws {
        try settingsManager.removeLocation(name: name)

        // Update cache
        locations.removeValue(forKey: name)
    }

    /// Sets the default VM location
    /// - Parameter name: Location name
    /// - Throws: Error if location cannot be set as default
    func setDefaultLocation(name: String) throws {
        try settingsManager.setDefaultLocation(name: name)

        // Update home directory
        guard let location = locations[name] else {
            throw VMLocationError.locationNotFound(name: name)
        }

        // Update homeDir to reflect the new default
        self._homeDir = Path(location.path)
    }

    /// Gets all available VM locations
    /// - Returns: Array of VM locations
    func getLocations() -> [VMLocation] {
        return settingsManager.getSettings().sortedLocations
    }

    /// Gets the default VM location
    /// - Returns: Default VM location
    /// - Throws: HomeError if no default location
    func getDefaultLocation() throws -> VMLocation {
        guard let location = settingsManager.getSettings().defaultLocation else {
            throw HomeError.invalidHomeDirectory
        }
        return location
    }

    // MARK: - Directory Validation

    /// Validates and ensures the existence of all VM locations
    /// - Throws: HomeError if validation fails or directory creation fails
    func validateHomeDirectory() throws {
        let settings = settingsManager.getSettings()

        for location in settings.vmLocations {
            let path = location.expandedPath
            if !fileExists(at: path) {
                try createVMLocation(at: path)
            } else if !isValidDirectory(at: path) {
                throw HomeError.invalidHomeDirectory
            }
        }
    }

    // MARK: - Private Helpers

    private func createVMLocation(at path: String) throws {
        do {
            try fileManager.createDirectory(
                atPath: path,
                withIntermediateDirectories: true
            )
        } catch {
            throw HomeError.directoryCreationFailed(path: path)
        }
    }

    private func createDirectory(at url: URL) throws {
        try fileManager.createDirectory(
            at: url,
            withIntermediateDirectories: true
        )
    }

    private func isValidDirectory(at path: String) -> Bool {
        var isDirectory: ObjCBool = false
        return fileManager.fileExists(atPath: path, isDirectory: &isDirectory)
            && isDirectory.boolValue
            && Path(path).writable()
    }

    private func fileExists(at path: String) -> Bool {
        return fileManager.fileExists(atPath: path)
    }

    private func sanitizeFileName(_ name: String) -> String {
        // Only decode percent encoding (e.g., %20 for spaces)
        return name.removingPercentEncoding ?? name
    }
}

// MARK: - VM Directory with Location

/// Represents a VM directory with its location information
struct VMDirectoryWithLocation {
    let directory: VMDirectory
    let locationName: String
}

// MARK: - Home + CustomStringConvertible

extension Home: CustomStringConvertible {
    var description: String {
        "Home(path: \(homeDir.path))"
    }
}