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.

52.7 KB
Raw Blame
import ArgumentParser
import Foundation

// MARK: - Documentation Types

/// One example invocation of a command, with an optional one-line description.
struct ExampleDoc: Codable {
    let command: String
    let description: String?

    init(_ command: String, _ description: String? = nil) {
        self.command = command
        self.description = description
    }
}

/// Represents documentation for a single CLI command
struct CommandDoc: Codable {
    let name: String
    let abstract: String
    let discussion: String?
    let arguments: [ArgumentDoc]
    let options: [OptionDoc]
    let flags: [FlagDoc]
    let subcommands: [CommandDoc]
    /// Example invocations. `CommandDocExtractorTests` parses every one with
    /// ArgumentParser, so an example cannot use a flag that does not exist.
    var examples: [ExampleDoc] = []
}

/// Represents documentation for a command argument
struct ArgumentDoc: Codable {
    let name: String
    let help: String
    let type: String
    let isOptional: Bool
    /// The accepted values, for arguments backed by an enum.
    var possibleValues: [String]? = nil
}

/// Represents documentation for a command option
struct OptionDoc: Codable {
    let name: String
    let shortName: String?
    let help: String
    let type: String
    let defaultValue: String?
    let isOptional: Bool
    /// The accepted values, for options backed by an enum.
    var possibleValues: [String]? = nil
    /// Takes every value up to the next option (`parsing: .upToNextOption`).
    var multipleValues: Bool? = nil
}

/// Represents documentation for a command flag
struct FlagDoc: Codable {
    let name: String
    let shortName: String?
    let help: String
    let defaultValue: Bool
}

/// One process exit status and what it means.
struct ExitCodeDoc: Codable {
    let code: Int32
    let meaning: String
}

/// Root documentation structure
struct CLIDocumentation: Codable {
    let name: String
    let version: String
    let abstract: String
    let exitCodes: [ExitCodeDoc]
    let commands: [CommandDoc]
}

// MARK: - Command Documentation Extractor

/// Extracts CLI documentation from command definitions.
///
/// The command tree below is hand-maintained (it carries value types, defaults
/// and examples that ArgumentParser does not expose). `CommandDocExtractorTests`
/// compares it with ArgumentParser's own metadata (`--experimental-dump-help`),
/// so a renamed, added or removed argument, option or flag fails the tests.
enum CommandDocExtractor {
    /// Extract documentation from all registered commands
    static func extractAll() -> CLIDocumentation {
        let coverage = documentationCoverage
        precondition(
            coverage.missing.isEmpty && coverage.extra.isEmpty,
            "CLI documentation coverage mismatch. Missing: \(coverage.missing); extra: \(coverage.extra)"
        )
        return CLIDocumentation(
            name: "lume",
            version: Lume.Version.current,
            abstract: "A lightweight CLI and local API server to build, run and manage macOS VMs.",
            exitCodes: exitCodes,
            commands: allCommandDocs
        )
    }

    /// Exit statuses: ArgumentParser maps `ValidationError` and parse errors
    /// to `EX_USAGE` (64), any other thrown error to `EXIT_FAILURE` (1).
    static let exitCodes: [ExitCodeDoc] = [
        ExitCodeDoc(code: 0, meaning: "Success"),
        ExitCodeDoc(code: 1, meaning: "The command failed (for example the VM does not exist or the operation errored)"),
        ExitCodeDoc(code: 64, meaning: "Usage error: an unknown command or option, a missing argument, or an invalid value"),
    ]

    // MARK: - Command Documentation Definitions

    /// All command documentation, kept in sync with source code.
    static var allCommandDocs: [CommandDoc] {
        return [
            createDoc,
            pullDoc,
            pushDoc,
            convertDoc,
            imagesDoc,
            cloneDoc,
            getDoc,
            setDoc,
            listDoc,
            runDoc,
            attachDoc,
            stopDoc,
            shutdownDoc,
            restartDoc,
            sshDoc,
            cpDoc,
            sipDoc,
            ipswDoc,
            serveDoc,
            deleteDoc,
            pruneDoc,
            configDoc,
            logsDoc,
            checkUpdateDoc,
            updateDoc,
            channelDoc,
            setupDoc,
            dumpDocsDoc,
        ]
    }

    static var documentationCoverage: (missing: [String], extra: [String]) {
        let registered = Swift.Set(CommandRegistry.allCommands.map(commandName))
        let documented = Swift.Set(allCommandDocs.map(\.name))
        return (
            missing: registered.subtracting(documented).sorted(),
            extra: documented.subtracting(registered).sorted()
        )
    }

    private static func commandName(_ command: ParsableCommand.Type) -> String {
        command.configuration.commandName ?? String(describing: command).lowercased()
    }

    private static func values<T: CaseIterable & RawRepresentable>(_: T.Type) -> [String]
    where T.RawValue == String {
        T.allCases.map(\.rawValue)
    }

    // MARK: - Create

    private static var createDoc: CommandDoc {
        CommandDoc(
            name: "create",
            abstract: "Create a new virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name for the virtual machine", type: "String", isOptional: false)
            ],
            options: [
                OptionDoc(name: "os", shortName: nil, help: "Operating system to install: macOS or linux", type: "String", defaultValue: "macOS", isOptional: true),
                OptionDoc(name: "cpu", shortName: nil, help: "Number of CPU cores", type: "Int", defaultValue: "4", isOptional: true),
                OptionDoc(name: "memory", shortName: nil, help: "Memory size (8, 8GB or 8192MB; a bare number is GB)", type: "String", defaultValue: "8GB", isOptional: true),
                OptionDoc(name: "disk-size", shortName: nil, help: "Disk size (100, 100GB or 102400MB; a bare number is GB). Defaults to 100GB for macOS and 50GB for Linux", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "display", shortName: nil, help: "Display resolution as WIDTHxHEIGHT", type: "String", defaultValue: "1024x768", isOptional: true),
                OptionDoc(name: "ipsw", shortName: nil, help: "Path to a macOS restore image (IPSW), or 'latest' to download the latest supported version. Required for macOS VMs", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "unattended", shortName: nil, help: "Prepare macOS unattended setup offline after install. Built-in presets: sequoia, tahoe; a YAML path is accepted for compatibility. macOS VMs only", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "debug-dir", shortName: nil, help: "Compatibility option; ignored by offline setup", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "vnc-port", shortName: nil, help: "Port for the temporary verification VNC server (0 picks a free port)", type: "Int", defaultValue: "0", isOptional: true),
                OptionDoc(name: "network", shortName: nil, help: "Network mode: nat, bridged (picks an interface), or bridged:<interface> (for example bridged:en0)", type: "String", defaultValue: "nat", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "debug", shortName: nil, help: "Compatibility flag; ignored by offline setup", defaultValue: false),
                FlagDoc(name: "no-display", shortName: nil, help: "Compatibility flag; offline setup verifies headlessly", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume create macos-tahoe --ipsw latest --unattended tahoe", "A macOS VM from the latest IPSW, set up unattended (SSH user lume/lume)"),
                ExampleDoc("lume create dev --os linux --cpu 4 --memory 8GB --disk-size 50GB", "A Linux VM"),
                ExampleDoc("lume create macos-tahoe --ipsw latest --network bridged:en0", "Bridge the VM onto the host's en0 network"),
            ]
        )
    }

    // MARK: - Pull

    private static var pullDoc: CommandDoc {
        CommandDoc(
            name: "pull",
            abstract: "Pull a prebuilt or custom macOS image from an OCI-compatible registry",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "image", help: "Image to pull (format: name:tag)", type: "String", isOptional: false),
                ArgumentDoc(name: "name", help: "Name for the resulting VM (defaults to the image name without its tag)", type: "String", isOptional: true),
            ],
            options: [
                OptionDoc(name: "registry", shortName: nil, help: "Container registry to pull from", type: "String", defaultValue: "ghcr.io", isOptional: true),
                OptionDoc(name: "organization", shortName: nil, help: "Organization to pull from", type: "String", defaultValue: "trycua", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "username", shortName: nil, help: "Registry username for authentication", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "password", shortName: nil, help: "Registry password for authentication", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "force", shortName: nil, help: "Download again even if the image is cached", defaultValue: false),
                FlagDoc(name: "verbose", shortName: nil, help: "Enable verbose logging", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume pull macos-tahoe-vanilla:latest", "Pull an image from ghcr.io/trycua as a VM named macos-tahoe-vanilla"),
                ExampleDoc("lume pull macos-tahoe-vanilla:latest my-vm --storage external", "Pull it as my-vm into another storage location"),
            ]
        )
    }

    // MARK: - Push

    private static var pushDoc: CommandDoc {
        CommandDoc(
            name: "push",
            abstract: "Push a macOS VM to an OCI-compatible registry",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM to push", type: "String", isOptional: false),
                ArgumentDoc(name: "image", help: "Image tag to push (format: name:tag)", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "additional-tags", shortName: nil, help: "Additional tags to push the same image to", type: "[String]", defaultValue: nil, isOptional: true, multipleValues: true),
                OptionDoc(name: "registry", shortName: nil, help: "Container registry to push to", type: "String", defaultValue: "ghcr.io", isOptional: true),
                OptionDoc(name: "organization", shortName: nil, help: "Organization to push to", type: "String", defaultValue: "trycua", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "chunk-size-mb", shortName: nil, help: "Chunk size for large files, in MB", type: "Int", defaultValue: "512", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "verbose", shortName: nil, help: "Enable verbose logging", defaultValue: false),
                FlagDoc(name: "dry-run", shortName: nil, help: "Prepare files without uploading to the registry", defaultValue: false),
                FlagDoc(name: "reassemble", shortName: nil, help: "With --dry-run, also reassemble the chunks to verify integrity", defaultValue: false),
                FlagDoc(name: "single-layer", shortName: nil, help: "Push the disk as a single layer (kubelet-compatible, no chunking)", defaultValue: false),
                FlagDoc(name: "legacy", shortName: nil, help: "Use the legacy Lume LZ4-chunked format instead of the OCI-compliant format", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume push my-vm my-image:latest --organization my-org", "Push my-vm as ghcr.io/my-org/my-image:latest"),
                ExampleDoc("lume push my-vm my-image:1.0 --additional-tags latest stable", "Push one image under several tags"),
                ExampleDoc("lume push my-vm my-image:latest --dry-run --reassemble", "Prepare and verify the chunks without uploading"),
            ]
        )
    }

    // MARK: - Convert

    private static var convertDoc: CommandDoc {
        CommandDoc(
            name: "convert",
            abstract: "Convert a legacy Lume image to OCI-compliant format",
            discussion: "Pulls a legacy Lume image from the registry, pushes it again in OCI-compliant format under a new name and tag, then removes the temporary local VM.",
            arguments: [
                ArgumentDoc(name: "source-image", help: "Source image to convert (legacy format, for example macos-tahoe:latest)", type: "String", isOptional: false),
                ArgumentDoc(name: "target-image", help: "Target image to push in OCI format (format: name:tag)", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "additional-tags", shortName: nil, help: "Additional tags to push the OCI image to", type: "[String]", defaultValue: nil, isOptional: true, multipleValues: true),
                OptionDoc(name: "registry", shortName: nil, help: "Registry to pull from and push to", type: "String", defaultValue: "ghcr.io", isOptional: true),
                OptionDoc(name: "organization", shortName: nil, help: "Registry organization", type: "String", defaultValue: "trycua", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "verbose", shortName: nil, help: "Enable verbose logging", defaultValue: false),
                FlagDoc(name: "dry-run", shortName: nil, help: "Prepare files without uploading to the registry", defaultValue: false),
                FlagDoc(name: "single-layer", shortName: nil, help: "Push the disk as a single layer (kubelet-compatible, no chunking)", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume convert macos-tahoe:latest macos-tahoe:latest-oci"),
            ]
        )
    }

    // MARK: - Images

    private static var imagesDoc: CommandDoc {
        CommandDoc(
            name: "images",
            abstract: "List available macOS images from local cache",
            discussion: nil,
            arguments: [],
            options: [
                OptionDoc(name: "organization", shortName: nil, help: "Organization to list images for", type: "String", defaultValue: "trycua", isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume images"),
            ]
        )
    }

    // MARK: - Clone

    private static var cloneDoc: CommandDoc {
        CommandDoc(
            name: "clone",
            abstract: "Clone an existing virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the source VM", type: "String", isOptional: false),
                ArgumentDoc(name: "new-name", help: "Name for the cloned VM", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "source-storage", shortName: nil, help: "Source VM storage location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "dest-storage", shortName: nil, help: "Destination VM storage location", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume clone macos-tahoe macos-tahoe-backup", "Keep a golden copy before changing a VM"),
                ExampleDoc("lume clone macos-tahoe macos-tahoe --source-storage default --dest-storage external", "Copy a VM to another storage location"),
            ]
        )
    }

    // MARK: - Get

    private static var getDoc: CommandDoc {
        CommandDoc(
            name: "get",
            abstract: "Get detailed information about a virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "format", shortName: "f", help: "Output format", type: "String", defaultValue: "text", isOptional: true, possibleValues: values(FormatOption.self)),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume get my-vm"),
                ExampleDoc("lume get my-vm --format json", "Machine-readable, including the IP address and VNC URL"),
            ]
        )
    }

    // MARK: - Set

    private static var setDoc: CommandDoc {
        CommandDoc(
            name: "set",
            abstract: "Set new values for CPU, memory, and disk size of a virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "cpu", shortName: nil, help: "New number of CPU cores", type: "Int", defaultValue: nil, isOptional: true),
                OptionDoc(name: "memory", shortName: nil, help: "New memory size (8, 8GB or 8192MB; a bare number is GB)", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "disk-size", shortName: nil, help: "New total disk size, increase only. For macOS VMs this relocates the recovery partition and grows the main APFS container; the VM must be stopped and it may take several minutes", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "display", shortName: nil, help: "New display resolution as WIDTHxHEIGHT", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "machine-identifier", shortName: nil, help: "New machine identifier: 'random', or a base64 identifier from `lume get --format json` to give this VM an existing machine identity (per-machine licenses then see one machine). macOS VMs only; the VM must be stopped", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "mac-address", shortName: nil, help: "New MAC address: 'random' (locally administered) or aa:bb:cc:dd:ee:ff. The VM must be stopped. The DHCP lease follows the MAC, so two running VMs with one MAC claim the same IP", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "no-backup", shortName: nil, help: "Skip the pre-resize disk backup (macOS resize only). Faster, but a failure cannot be rolled back", defaultValue: false),
                FlagDoc(name: "keep-backup", shortName: nil, help: "Keep the pre-resize backup after a successful macOS resize", defaultValue: false),
                FlagDoc(name: "dry-run", shortName: nil, help: "Validate the disk-resize plan and print it without changing anything (macOS resize only)", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume set my-vm --cpu 8 --memory 16GB"),
                ExampleDoc("lume set my-vm --disk-size 120GB --dry-run", "Check a disk resize plan, then run it without --dry-run"),
                ExampleDoc("lume set my-vm --mac-address random"),
            ]
        )
    }

    // MARK: - List

    private static var listDoc: CommandDoc {
        CommandDoc(
            name: "ls",
            abstract: "List virtual machines",
            discussion: nil,
            arguments: [],
            options: [
                OptionDoc(name: "format", shortName: "f", help: "Output format", type: "String", defaultValue: "text", isOptional: true, possibleValues: values(FormatOption.self)),
                OptionDoc(name: "storage", shortName: nil, help: "Show only VMs in this storage location", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume ls"),
                ExampleDoc("lume ls --format json"),
            ]
        )
    }

    // MARK: - Run

    private static var runDoc: CommandDoc {
        CommandDoc(
            name: "run",
            abstract: "Run a virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM, or an image to pull and run (format: name or name:tag)", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "display", shortName: nil, help: "Local viewer to open. The VNC server stays available in every mode", type: "DisplayMode", defaultValue: "native", isOptional: true, possibleValues: values(DisplayMode.self)),
                OptionDoc(name: "log-file", shortName: nil, help: "Log path for --detach (default: ~/Library/Logs/lume/{vm}.log)", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "shared-dir", shortName: nil, help: "Directory to share with the VM: a path (read-write) or path:ro / path:rw. Repeatable", type: "[String]", defaultValue: nil, isOptional: true),
                OptionDoc(name: "mount", shortName: nil, help: "For Linux VMs only, a read-only disk image to attach", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "usb-storage", shortName: nil, help: "Disk image to attach as a USB mass storage device. Repeatable", type: "[String]", defaultValue: nil, isOptional: true),
                OptionDoc(name: "disk", shortName: nil, help: "Disk image to attach as a read-write virtio-blk device. Repeatable", type: "[String]", defaultValue: nil, isOptional: true),
                OptionDoc(name: "registry", shortName: nil, help: "Container registry to pull images from", type: "String", defaultValue: "ghcr.io", isOptional: true),
                OptionDoc(name: "organization", shortName: nil, help: "Organization to pull images from", type: "String", defaultValue: "trycua", isOptional: true),
                OptionDoc(name: "vnc", shortName: nil, help: "VNC server policy. disabled starts the VM with no VNC listener and reports a null vncUrl", type: "VNCPolicy", defaultValue: "enabled", isOptional: true, possibleValues: values(VNCPolicy.self)),
                OptionDoc(name: "vnc-port", shortName: nil, help: "Port for the VNC server (0 picks a free port)", type: "Int", defaultValue: "0", isOptional: true),
                OptionDoc(name: "vnc-password", shortName: nil, help: "Password for the VNC server (default: a random passphrase)", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "recovery-mode", shortName: nil, help: "For macOS VMs only, boot into recovery mode", type: "Bool", defaultValue: "false", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "disk-path", shortName: nil, help: "Use this disk image instead of disk.img in the VM directory", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "nvram-path", shortName: nil, help: "Use this NVRAM file instead of nvram.bin in the VM directory", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "network", shortName: nil, help: "Network override for this run: nat, bridged, or bridged:<interface> (default: the VM's configured mode)", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "no-display", shortName: "d", help: "Compatibility alias for --display none", defaultValue: false),
                FlagDoc(name: "detach", shortName: nil, help: "Run the VM in the background and return immediately", defaultValue: false),
                FlagDoc(name: "clipboard", shortName: nil, help: "Sync the clipboard both ways over SSH. Automatic with the native macOS display", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume run my-vm"),
                ExampleDoc("lume run my-vm --shared-dir ~/src:ro --display none", "Headless, with a read-only shared folder"),
                ExampleDoc("lume run my-vm --detach --display none --vnc disabled", "In the background with no VNC listener"),
            ]
        )
    }

    // MARK: - Attach

    private static var attachDoc: CommandDoc {
        CommandDoc(
            name: "attach",
            abstract: "Open a viewer for a running virtual machine",
            discussion: "The native display is used when the `lume run` process that owns the VM supports live attachment; VNC is the fallback.",
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "display", shortName: nil, help: "Viewer to open (default: native, falling back to VNC)", type: "AttachDisplayMode", defaultValue: nil, isOptional: true, possibleValues: values(AttachDisplayMode.self)),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume attach my-vm"),
                ExampleDoc("lume attach my-vm --display vnc", "Open Screen Sharing over VNC"),
            ]
        )
    }

    // MARK: - Stop

    private static var stopDoc: CommandDoc {
        CommandDoc(
            name: "stop",
            abstract: "Stop a virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM to stop", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "timeout", shortName: nil, help: "Seconds to wait for a graceful shutdown before forcing power off", type: "Int", defaultValue: "10", isOptional: false),
            ],
            flags: [
                FlagDoc(name: "force", shortName: nil, help: "Power off the VM immediately instead of attempting a graceful shutdown first", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume stop my-vm"),
                ExampleDoc("lume stop my-vm --force"),
            ]
        )
    }

    // MARK: - Guest power

    private static var shutdownDoc: CommandDoc {
        guestPowerDoc(
            name: "shutdown",
            abstract: "Gracefully shut down a virtual machine"
        )
    }

    private static var restartDoc: CommandDoc {
        guestPowerDoc(
            name: "restart",
            abstract: "Gracefully restart a virtual machine"
        )
    }

    private static func guestPowerDoc(name: String, abstract: String) -> CommandDoc {
        CommandDoc(
            name: name,
            abstract: abstract,
            discussion: "Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.",
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "user", shortName: "u", help: "SSH username", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "password", shortName: "p", help: "SSH and sudo password", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "timeout", shortName: "t", help: "SSH command timeout in seconds", type: "Int", defaultValue: "30", isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume \(name) my-vm"),
                ExampleDoc("lume \(name) my-vm --user admin --timeout 60", "With another SSH user and a longer timeout"),
            ]
        )
    }

    // MARK: - SSH

    private static var sshDoc: CommandDoc {
        CommandDoc(
            name: "ssh",
            abstract: "Connect to a VM via SSH or execute commands remotely",
            discussion: "Opens an interactive shell, or runs one command and exits with its status. Password authentication is handled for you (no sshpass needed). Requires Remote Login in the guest; VMs created with --unattended have it enabled with credentials lume/lume.",
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
                ArgumentDoc(name: "command", help: "Command to execute (omit for an interactive shell)", type: "[String]", isOptional: true),
            ],
            options: [
                OptionDoc(name: "user", shortName: "u", help: "SSH username", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "password", shortName: "p", help: "SSH password", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "Storage location name or path", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "timeout", shortName: "t", help: "Command timeout in seconds (0 for no timeout)", type: "Int", defaultValue: "60", isOptional: true),
            ],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume ssh my-vm", "Interactive shell"),
                ExampleDoc("lume ssh my-vm \"ls -la\"", "Run one command"),
                ExampleDoc("lume ssh my-vm --timeout 0 \"cd /app && npm test\"", "A long-running command with no timeout"),
            ]
        )
    }

    // MARK: - CP

    private static var cpDoc: CommandDoc {
        CommandDoc(
            name: "cp",
            abstract: "Copy files between the host and a VM",
            discussion: "Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.",
            arguments: [
                ArgumentDoc(name: "source", help: "Source path. Use VM:PATH for a path inside a VM", type: "String", isOptional: false),
                ArgumentDoc(name: "destination", help: "Destination path. Use VM:PATH for a path inside a VM", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "user", shortName: "u", help: "SSH username", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "password", shortName: "p", help: "SSH password", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "Storage location name or path", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "timeout", shortName: "t", help: "Transfer timeout in seconds (0 for no timeout)", type: "Int", defaultValue: "600", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "recursive", shortName: "r", help: "Copy directories recursively", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume cp ./build.zip my-vm:/tmp/build.zip", "Copy a host file into the VM"),
                ExampleDoc("lume cp my-vm:/tmp/out.log ./out.log", "Copy a file out of the VM"),
                ExampleDoc("lume cp -r ./assets my-vm:/tmp/assets", "Copy a directory into the VM"),
            ]
        )
    }

    // MARK: - SIP

    private static var sipDoc: CommandDoc {
        CommandDoc(
            name: "sip",
            abstract: "Enable or disable System Integrity Protection on a macOS VM",
            discussion: "Boots the stopped VM normally to validate the admin credentials, runs `csrutil disable` (or `enable`) in paired recoveryOS over VNC, then boots normally once more to verify the result. The VM needs an admin account and Remote Login; VMs from unattended setup use lume/lume. Prefer --admin-password-stdin: --admin-password is visible to other processes. Requires vncdotool (pip3 install vncdotool).",
            arguments: [
                ArgumentDoc(name: "state", help: "Desired SIP state", type: "String", isOptional: false, possibleValues: values(Sip.State.self)),
                ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "admin-user", shortName: nil, help: "Administrator username in the guest", type: "String", defaultValue: "lume", isOptional: true),
                OptionDoc(name: "admin-password", shortName: nil, help: "Administrator password in the guest (default: lume); prefer --admin-password-stdin", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "screenshot-dir", shortName: nil, help: "Save step-by-step framebuffer PNGs here for debugging", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "vnc-port", shortName: nil, help: "TCP port for the temporary recovery VNC server", type: "Int", defaultValue: "5999", isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "timeout", shortName: nil, help: "Overall timeout in seconds", type: "Int", defaultValue: "900", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "yes", shortName: "y", help: "Skip the interactive confirmation prompt", defaultValue: false),
                FlagDoc(name: "admin-password-stdin", shortName: nil, help: "Read one administrator-password line from standard input without echo", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume sip off my-vm --yes"),
                ExampleDoc("lume sip on my-vm --yes --admin-user alice --admin-password-stdin", "With another admin account, password read from stdin"),
            ]
        )
    }

    // MARK: - IPSW

    private static var ipswDoc: CommandDoc {
        CommandDoc(
            name: "ipsw",
            abstract: "Get macOS restore image IPSW URL",
            discussion: "Prints the URL of the latest supported restore image. Download it, then pass the file to `lume create --ipsw`.",
            arguments: [],
            options: [],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume ipsw"),
            ]
        )
    }

    // MARK: - Serve

    private static var serveDoc: CommandDoc {
        CommandDoc(
            name: "serve",
            abstract: "Start the VM management server",
            discussion: "Serves the HTTP API on localhost, or with --mcp an MCP server over stdio for AI agents.",
            arguments: [],
            options: [
                OptionDoc(name: "port", shortName: nil, help: "Port to listen on (HTTP mode only)", type: "Int", defaultValue: "7777", isOptional: true),
            ],
            flags: [
                FlagDoc(name: "mcp", shortName: nil, help: "Run as an MCP server (stdio transport) for AI agents", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume serve", "HTTP API on http://localhost:7777"),
                ExampleDoc("lume serve --port 7778"),
                ExampleDoc("lume serve --mcp", "MCP server over stdio (what MCP clients launch)"),
            ]
        )
    }

    // MARK: - Delete

    private static var deleteDoc: CommandDoc {
        CommandDoc(
            name: "delete",
            abstract: "Delete a virtual machine",
            discussion: nil,
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the VM to delete", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "force", shortName: nil, help: "Delete without asking for confirmation", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume delete my-vm"),
                ExampleDoc("lume delete my-vm --force", "Without the confirmation prompt"),
            ]
        )
    }

    // MARK: - Prune

    private static var pruneDoc: CommandDoc {
        CommandDoc(
            name: "prune",
            abstract: "Remove cached images",
            discussion: nil,
            arguments: [],
            options: [],
            flags: [],
            subcommands: [],
            examples: [
                ExampleDoc("lume prune"),
            ]
        )
    }

    // MARK: - Config

    private static func leaf(
        _ name: String, _ abstract: String, arguments: [ArgumentDoc] = [], options: [OptionDoc] = [],
        examples: [ExampleDoc]
    ) -> CommandDoc {
        CommandDoc(
            name: name, abstract: abstract, discussion: nil, arguments: arguments, options: options,
            flags: [], subcommands: [], examples: examples)
    }

    private static var configDoc: CommandDoc {
        CommandDoc(
            name: "config",
            abstract: "Get or set lume configuration",
            discussion: "Without a subcommand, prints the current configuration (`lume config get`).",
            arguments: [],
            options: [],
            flags: [],
            subcommands: [
                leaf("get", "Get current configuration", examples: [ExampleDoc("lume config get")]),
                CommandDoc(
                    name: "storage",
                    abstract: "Manage VM storage locations",
                    discussion: nil,
                    arguments: [],
                    options: [],
                    flags: [],
                    subcommands: [
                        leaf("add", "Add a new VM storage location", arguments: [
                            ArgumentDoc(name: "name", help: "Storage name (letters, digits, dashes and underscores)", type: "String", isOptional: false),
                            ArgumentDoc(name: "path", help: "Path to the VM storage directory", type: "String", isOptional: false),
                        ], examples: [ExampleDoc("lume config storage add external /Volumes/External/lume")]),
                        leaf("remove", "Remove a VM storage location", arguments: [
                            ArgumentDoc(name: "name", help: "Storage name to remove", type: "String", isOptional: false),
                        ], examples: [ExampleDoc("lume config storage remove external")]),
                        leaf("list", "List all VM storage locations", examples: [ExampleDoc("lume config storage list")]),
                        leaf("default", "Set the default VM storage location", arguments: [
                            ArgumentDoc(name: "name", help: "Storage name to set as default", type: "String", isOptional: false),
                        ], examples: [ExampleDoc("lume config storage default external")]),
                    ]
                ),
                CommandDoc(
                    name: "cache",
                    abstract: "Manage image cache settings",
                    discussion: nil,
                    arguments: [],
                    options: [],
                    flags: [],
                    subcommands: [
                        leaf("dir", "Get or set cache directory", arguments: [
                            ArgumentDoc(name: "path", help: "Path to the cache directory (omit to show the current one)", type: "String", isOptional: true),
                        ], examples: [ExampleDoc("lume config cache dir"), ExampleDoc("lume config cache dir /Volumes/External/lume-cache")]),
                        leaf("enable", "Enable image caching", examples: [ExampleDoc("lume config cache enable")]),
                        leaf("disable", "Disable image caching", examples: [ExampleDoc("lume config cache disable")]),
                        leaf("status", "Show cache status and directory", examples: [ExampleDoc("lume config cache status")]),
                    ]
                ),
                CommandDoc(
                    name: "telemetry",
                    abstract: "Manage pseudonymous telemetry settings",
                    discussion: nil,
                    arguments: [],
                    options: [],
                    flags: [],
                    subcommands: [
                        leaf("status", "Show current telemetry status", examples: [ExampleDoc("lume config telemetry status")]),
                        leaf("enable", "Enable pseudonymous telemetry", examples: [ExampleDoc("lume config telemetry enable")]),
                        leaf("disable", "Disable pseudonymous telemetry", examples: [ExampleDoc("lume config telemetry disable")]),
                        leaf("reset-id", "Delete the pseudonymous installation ID and registration markers", examples: [ExampleDoc("lume config telemetry reset-id")]),
                    ]
                ),
                CommandDoc(
                    name: "registry",
                    abstract: "Manage container registry settings",
                    discussion: nil,
                    arguments: [],
                    options: [],
                    flags: [],
                    subcommands: [
                        leaf("status", "Show current registry configuration", examples: [ExampleDoc("lume config registry status")]),
                        leaf("type", "Get or set registry type", arguments: [
                            ArgumentDoc(name: "type", help: "Registry type to use: ghcr or gcs (omit to show the current one)", type: "String", isOptional: true),
                        ], examples: [ExampleDoc("lume config registry type"), ExampleDoc("lume config registry type ghcr")]),
                        leaf("ghcr", "Configure GitHub Container Registry settings", options: [
                            OptionDoc(name: "registry", shortName: nil, help: "Registry URL (default: ghcr.io)", type: "String", defaultValue: nil, isOptional: true),
                            OptionDoc(name: "organization", shortName: nil, help: "Organization or namespace (default: trycua)", type: "String", defaultValue: nil, isOptional: true),
                        ], examples: [ExampleDoc("lume config registry ghcr --organization my-org")]),
                        leaf("gcs", "Configure GCS registry settings", options: [
                            OptionDoc(name: "api-url", shortName: nil, help: "API URL for signed URL generation", type: "String", defaultValue: nil, isOptional: true),
                            OptionDoc(name: "api-key", shortName: nil, help: "API key for authentication", type: "String", defaultValue: nil, isOptional: true),
                        ], examples: [ExampleDoc("lume config registry gcs --api-url https://images.example.com --api-key <key>")]),
                    ]
                ),
                CommandDoc(
                    name: "network",
                    abstract: "Manage network settings",
                    discussion: nil,
                    arguments: [],
                    options: [],
                    flags: [],
                    subcommands: [
                        leaf("interfaces", "List available network interfaces for bridged networking", examples: [ExampleDoc("lume config network interfaces")]),
                    ]
                ),
            ]
        )
    }

    // MARK: - Logs

    private static func logsLeaf(_ name: String, _ abstract: String, files: String) -> CommandDoc {
        CommandDoc(
            name: name,
            abstract: abstract,
            discussion: nil,
            arguments: [],
            options: [
                OptionDoc(name: "lines", shortName: "l", help: "Number of lines to display from the end of \(files)", type: "Int", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "follow", shortName: "f", help: "Follow the log continuously (like tail -f)", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume logs \(name) --lines 100"),
                ExampleDoc("lume logs \(name) --follow"),
            ]
        )
    }

    private static var logsDoc: CommandDoc {
        CommandDoc(
            name: "logs",
            abstract: "View lume serve logs",
            discussion: nil,
            arguments: [],
            options: [],
            flags: [],
            subcommands: [
                logsLeaf("info", "View info logs from the daemon", files: "the file"),
                logsLeaf("error", "View error logs from the daemon", files: "the file"),
                logsLeaf("all", "View both info and error logs from the daemon", files: "each file"),
            ]
        )
    }

    // MARK: - Update

    private static var checkUpdateDoc: CommandDoc {
        CommandDoc(
            name: "check-update",
            abstract: "Check whether a newer Lume release is available",
            discussion: "Read-only update check. Uses GitHub Releases, caches the result briefly, and never installs anything.",
            arguments: [],
            options: [],
            flags: [
                FlagDoc(name: "json", shortName: nil, help: "Emit the structured update-state payload as JSON", defaultValue: false),
                FlagDoc(name: "no-cache", shortName: nil, help: "Bypass the local update-check cache", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume check-update"),
                ExampleDoc("lume check-update --json --no-cache"),
            ]
        )
    }

    private static var updateDoc: CommandDoc {
        CommandDoc(
            name: "update",
            abstract: "Check for a Lume update and optionally apply it",
            discussion: "Without --apply, this command only checks for a newer release and prints the command to install it. With --apply, it runs the official Lume installer pinned to the discovered version and exits with the installer's status.",
            arguments: [],
            options: [],
            flags: [
                FlagDoc(name: "apply", shortName: nil, help: "Apply the update while preserving the current background-service choice", defaultValue: false),
                FlagDoc(name: "json", shortName: nil, help: "Emit the structured update-state payload as JSON", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume update"),
                ExampleDoc("lume update --apply"),
            ]
        )
    }

    private static var channelDoc: CommandDoc {
        CommandDoc(
            name: "channel",
            abstract: "Inspect or change the stable/nightly update channel; selection does not install",
            discussion: "The selection persists but never installs by itself; run `lume update --apply` after changing it. Without a subcommand, prints the status.",
            arguments: [],
            options: [],
            flags: [],
            subcommands: [
                CommandDoc(
                    name: "status",
                    abstract: "Show selected and current release channels",
                    discussion: nil,
                    arguments: [], options: [],
                    flags: [FlagDoc(name: "json", shortName: nil, help: "Emit machine-readable channel state as JSON", defaultValue: false)],
                    subcommands: [],
                    examples: [ExampleDoc("lume channel status --json")]
                ),
                CommandDoc(
                    name: "set",
                    abstract: "Save stable or nightly as the update channel",
                    discussion: nil,
                    arguments: [ArgumentDoc(name: "channel", help: "Release channel: stable or nightly", type: "String", isOptional: false)],
                    options: [],
                    flags: [FlagDoc(name: "json", shortName: nil, help: "Emit machine-readable channel state as JSON", defaultValue: false)],
                    subcommands: [],
                    examples: [ExampleDoc("lume channel set nightly"), ExampleDoc("lume channel set stable")]
                ),
            ]
        )
    }

    // MARK: - Setup

    private static var setupDoc: CommandDoc {
        CommandDoc(
            name: "setup",
            abstract: "Prepare unattended macOS setup",
            discussion: "Lume prepares the macOS disk offline, skips Setup Assistant, enables autologin and SSH, disables screensaver lock, verifies SSH, then stops the VM.",
            arguments: [
                ArgumentDoc(name: "name", help: "Name of the virtual machine", type: "String", isOptional: false),
            ],
            options: [
                OptionDoc(name: "unattended", shortName: nil, help: "Built-in preset (sequoia, tahoe) or a YAML path, kept for compatibility and optional post-SSH commands (default: tahoe)", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "storage", shortName: nil, help: "VM storage location name, or a direct path to the VM location", type: "String", defaultValue: nil, isOptional: true),
                OptionDoc(name: "vnc-port", shortName: nil, help: "Port for the temporary verification VNC server (0 picks a free port)", type: "Int", defaultValue: "0", isOptional: true),
                OptionDoc(name: "debug-dir", shortName: nil, help: "Compatibility option; ignored by offline setup", type: "String", defaultValue: nil, isOptional: true),
            ],
            flags: [
                FlagDoc(name: "no-display", shortName: nil, help: "Compatibility flag; offline setup verifies headlessly", defaultValue: false),
                FlagDoc(name: "debug", shortName: nil, help: "Compatibility flag; ignored by offline setup", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume setup my-vm"),
                ExampleDoc("lume setup my-vm --unattended sequoia"),
            ]
        )
    }

    // MARK: - Dump Docs

    private static var dumpDocsDoc: CommandDoc {
        CommandDoc(
            name: "dump-docs",
            abstract: "Output CLI and API documentation as JSON for tooling and integrations",
            discussion: "Emits the CLI, HTTP API or MCP tool metadata (arguments, options, flags, endpoints, tool schemas, help text, defaults and types) that the generated reference is built from.",
            arguments: [],
            options: [
                OptionDoc(name: "type", shortName: nil, help: "Documentation type to output", type: "String", defaultValue: "cli", isOptional: true, possibleValues: values(DocType.self)),
            ],
            flags: [
                FlagDoc(name: "pretty", shortName: nil, help: "Pretty-print the JSON output with sorted keys", defaultValue: false),
            ],
            subcommands: [],
            examples: [
                ExampleDoc("lume dump-docs --type cli --pretty"),
                ExampleDoc("lume dump-docs --type mcp", "The MCP server's tool list"),
            ]
        )
    }
}