Skip to content

armgit / peel

Public Imported from GitHub
0

Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.

51.0 KB
Raw Blame
import ArgumentParser
import Foundation
import PeelCore

struct OrphansCommand: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "orphans",
        abstract: "List files left by apps that are no longer installed, and move a group to the Trash.",
        discussion: "Nothing here is selected for you, so --remove takes the identifier of one group. What Peel refuses to move, what it leaves for you to choose in the app, and what needs administrator access, stays. What only an administrator can move is listed apart, with how to remove it in Finder."
    )

    @Argument(help: "The group to move, as `peel orphans` names it in its first column.")
    var group: String?

    @Flag(help: "Move the named group to the Trash, leaving out what Peel holds back.")
    var remove = false

    @OptionGroup var removal: RemovalOptions

    @OptionGroup var output: OutputOptions

    /// What `--json` writes.
    struct Report: Encodable {
        let groups: [Group]
        let forAnAdministrator: [ForAnAdministrator]
        let unreadableLocations: [String]
        /// The places with more folders inside than Peel looks into, where an orphaned file may be that isn't listed.
        let cutShortLocations: [String]
        let needsFullDiskAccess: Bool

        struct ForAnAdministrator: Encodable {
            let path: String
            let size: MeasuredSize
            let apps: [String]
            /// How the uninstall that left it found it, in `peel leftovers --json`'s words, or `null` for what the
            /// scan found itself.
            let reason: String?
            let confidence: String?

            private enum CodingKeys: String, CodingKey {
                case path
                case size
                case apps
                case reason
                case confidence
            }

            /// Encodes a missing claim as `null`, for the reason `AppRecord` gives.
            func encode(to encoder: any Encoder) throws {
                var container = encoder.container(keyedBy: CodingKeys.self)
                try container.encode(path, forKey: .path)
                try container.encode(size, forKey: .size)
                try container.encode(apps, forKey: .apps)
                try container.encode(reason, forKey: .reason)
                try container.encode(confidence, forKey: .confidence)
            }
        }

        struct Group: Encodable {
            let identifier: String
            let size: MeasuredSize
            /// What `--remove` would move of the group: its size without the files Peel holds back.
            let movable: MeasuredSize
            let confidence: String
            let why: String
            let files: [File]
        }

        struct File: Encodable {
            let path: String
            let size: MeasuredSize
            /// Why `--remove` leaves the file where it is, or `null` when it would move it.
            let heldBack: String?

            private enum CodingKeys: String, CodingKey {
                case path
                case size
                case heldBack
            }

            /// Encodes a missing `heldBack` as `null`, for the reason `AppRecord` gives.
            func encode(to encoder: any Encoder) throws {
                var container = encoder.container(keyedBy: CodingKeys.self)
                try container.encode(path, forKey: .path)
                try container.encode(size, forKey: .size)
                try container.encode(heldBack, forKey: .heldBack)
            }
        }
    }

    func validate() throws {
        try removal.validate(removing: remove, with: output)
        guard remove == (group != nil) else {
            throw ValidationError(remove
                ? "Name the group to move. See `peel orphans`."
                : "A group on its own does nothing. Add --remove to move it.")
        }
    }

    func run() async throws {
        let catalog = await AppCatalog.scan()
        if let refusal = Self.refusal(for: catalog) { throw refusal }
        let apps = catalog.apps
        // The same signals the app uses (the apps Peel remembers, the apps running, and what uninstalls left for an
        // administrator), so both judge these files alike. What Peel remembers is only read here, never written.
        let remembered = await AppMemory().load()
        let running = await RunningCopies.current
        let exclusions = await UnreadableExclusions.load()
        let scanner = OrphanScanner(exclusions: exclusions)
        let owners = OrphanOwners().load()
        let tools = await InstalledTools.read()
        let scan = await ProgressLine.counting {
            await scanner.scan(
                installedApps: apps,
                remembered: remembered,
                running: running,
                owners: owners ?? [:],
                tools: tools,
                leftForAnAdministrator: await LeftForAnAdministrator().load()
            )
        }
        if let group {
            return try await clean(
                group,
                in: scan,
                apps: apps,
                remembered: remembered,
                scanner: scanner,
                using: TrashService(exclusions: exclusions)
            )
        }

        if output.json {
            try Output.json(Self.report(for: scan))
        } else if scan.groups.isEmpty, scan.forAnAdministrator.isEmpty {
            Output.line("No orphaned files found.")
        } else {
            for group in scan.groups {
                Output.line(Self.heading(for: group))
                Output.table(Self.rows(for: group), indent: "  ")
            }
            if !scan.forAnAdministrator.isEmpty {
                Output.line(Self.administratorHeading(for: scan))
                Output.table(Self.administratorRows(for: scan), indent: "  ")
            }
        }
        for note in Self.notes(for: scan, ownersUnreadable: owners == nil) {
            Output.note(note)
        }
    }

    /// What the list could not cover, the groups the person said belong to an app or a tool when that list can't be
    /// read, the folders Peel could not read and the places with more folders inside than Peel looks into, and how to
    /// remove what only an administrator can move, with what a kernel extension needs: a restart, and on Apple silicon
    /// the startup disk's security set back.
    static func notes(
        for scan: OrphanScan, ownersUnreadable: Bool, onAppleSilicon: Bool = HostArchitecture.isAppleSilicon
    ) -> [String] {
        var notes: [String] = []
        if ownersUnreadable {
            notes.append("Peel can't read the list of orphaned files you said belong to an app or a command-line tool, so it lists them too. Start the list over in Peel's Settings > Exclusions.")
        }
        if !scan.unreadableLocations.isEmpty {
            let folders = scan.unreadableLocations.map(\.url)
            notes.append(Output.unreadableNote(for: folders, needsFullDiskAccess: scan.needsFullDiskAccess))
        }
        notes += scan.cutShortLocations.map {
            "There are more folders in \(Output.plain(Output.path($0.url))) than Peel looks inside, so an orphaned file may be in a folder Peel didn't reach."
        }
        if !scan.forAnAdministrator.isEmpty {
            notes.append(byHand)
        }
        if scan.forAnAdministrator.contains(where: \.item.url.isKernelExtension) {
            notes.append(kernelExtensions)
            if onAppleSilicon { notes.append(reducedSecurity) }
        }
        return notes
    }

    /// Why nothing is listed when some apps could not be read: their files would look orphaned.
    static func refusal(for catalog: AppScan) -> CommandFailure? {
        guard !catalog.readEverything else { return nil }
        let list = catalog.listOfFoldersUnreadable ? ["its list of app folders"] : []
        let listed = Output.list(list + Output.named(catalog.unreadable))
        let why = Output.whyNotRead(catalog.unreadable).map { " " + $0 } ?? ""
        let access = catalog.needsFullDiskAccess ? " " + Output.fullDiskAccessAdvice : ""
        let startOver = list.isEmpty
            ? "" : " Start the list over in Settings > General > App Folders." + catalog.whyListOfFoldersUnreadable.sentence
        return CommandFailure("Peel couldn't read \(listed), so it can't tell which apps are installed. Nothing is listed, since the files of an app it can't see would look orphaned.\(why)\(access)\(startOver)")
    }

    static func report(for scan: OrphanScan) -> Report {
        Report(
            groups: scan.groups.map { group in
                Report.Group(
                    identifier: group.identifier,
                    size: MeasuredSize(group.total),
                    movable: MeasuredSize(SizeTotal(moving(group).map(\.size))),
                    confidence: group.confidence.levelName,
                    why: group.confidence.summary,
                    files: group.items.map { item in
                        let size = MeasuredSize(item.size)
                        return Report.File(path: Output.path(item.url), size: size, heldBack: item.heldBack?.rawValue)
                    }
                )
            },
            forAnAdministrator: scan.forAnAdministrator.map { entry in
                Report.ForAnAdministrator(
                    path: Output.path(entry.item.url),
                    size: MeasuredSize(entry.item.size),
                    apps: entry.apps,
                    reason: entry.claim?.reason.rawValue,
                    confidence: entry.claim?.confidence.summary
                )
            },
            unreadableLocations: scan.unreadableLocations.map { Output.path($0.url) },
            cutShortLocations: scan.cutShortLocations.map { Output.path($0.url) },
            needsFullDiskAccess: scan.needsFullDiskAccess
        )
    }

    static let kernelExtensions = "macOS changes the kernel extensions it loads only when the Mac restarts, so restart once a .kext you removed is in the Trash."

    static let reducedSecurity = "If you set the startup disk's security to Reduced Security to install a .kext, it stays that way until you choose Full Security again: in the Recovery app, choose Utilities > Startup Security Utility."

    /// How to remove what only an administrator can move, from a place Peel's helper may not move it from.
    static let byHand = "Only an administrator can move what Needs an administrator lists, and Peel's helper isn't allowed to move it from there. To remove one, reveal it in Finder with `open -R <path>`, drag it to the Trash, then enter an administrator name and password when macOS asks."

    static func administratorHeading(for scan: OrphanScan) -> String {
        "Needs an administrator  \(Output.size(SizeTotal(scan.forAnAdministrator.map(\.item.size))))"
    }

    static func administratorRows(for scan: OrphanScan) -> [[String]] {
        scan.forAnAdministrator.map { entry in
            var found = "found for \(Output.list(entry.apps.map(Output.plain)))"
            if let claim = entry.claim {
                found += ", \(claim.reason.summary)"
                if claim.confidence == .possible {
                    found += ", review: \(claim.confidence.summary) match"
                }
            }
            return [Output.size(entry.item.size), Output.path(entry.item.url), found]
        }
    }

    /// What `--remove` moves of `group`: every file but those Peel holds back, which the list says stay.
    static func moving(_ group: OrphanGroup) -> [OrphanItem] {
        group.items.filter { $0.heldBack == nil }
    }

    /// Why the app recommends nothing of an unsure group, said in the plan, since a script with -y reads no list first.
    static func unsureNote(for group: OrphanGroup) -> [String] {
        group.confidence.level == .unsure ? ["unsure: \(group.confidence.summary)"] : []
    }

    static func heading(for group: OrphanGroup) -> String {
        let moving = Output.size(SizeTotal(moving(group).map(\.size)))
        return "\(group.identifier)  \(moving)  \(group.confidence.levelName): \(group.confidence.summary)"
    }

    static func rows(for group: OrphanGroup) -> [[String]] {
        group.items.map { item in
            [Output.size(item.size), Output.path(item.url)] + (item.heldBack.map { ["stays: \($0.summary)"] } ?? [])
        }
    }

    func clean(
        _ identifier: String,
        in scan: OrphanScan,
        apps: [InstalledApp],
        remembered: [RememberedApp],
        scanner: OrphanScanner,
        using service: TrashService,
        recordingIn log: RemovalLog = RemovalLog(),
        refusals: RefusalLog = RefusalLog()
    ) async throws {
        let wanted = scan.groups.filter { $0.identifier.caseInsensitiveCompare(identifier) == .orderedSame }
        guard let group = wanted.first else {
            throw CommandFailure("Nothing orphaned is called \(Output.quoted(identifier)). See `peel orphans`.")
        }
        let items = Self.moving(group)
        // Nobody asked for a held back file on its own, so it is said here and never recorded as refused.
        let staying = group.items.compactMap { item in item.heldBack.map { "\(Output.plain(Output.path(item.url))) stays: \($0.summary)" } }
        guard !items.isEmpty else {
            Output.line("Every file of \(group.identifier) is one Peel leaves alone. See `peel orphans`.")
            staying.forEach(Output.note)
            return
        }
        let cleanup = Cleanup.of(
            items.map { (url: $0.url, size: $0.size) },
            source: group.title,
            tool: "orphans",
            needingAdministrator: Set(items.filter(\.requiresPrivileges).map(\.url)),
            service: service
        )
        try await cleanup.run(
            question: "Move \(Output.count(cleanup.moving.count, "item", "items")) of \(group.title) to the Trash?",
            notes: Self.unsureNote(for: group) + staying,
            dryRun: removal.dryRun,
            yes: removal.yes,
            using: service,
            recordingIn: log,
            refusals: refusals
        ) { service, urls in
            let wanted = Set(urls)
            return await OrphanRemoval.trash(
                items.filter { wanted.contains($0.url) },
                installedApps: apps,
                remembered: remembered,
                scanner: scanner,
                using: service,
                mayUseHelper: false
            )
        }
    }
}

struct CachesCommand: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "caches",
        abstract: "List caches of developer tools, and move them to the Trash.",
        discussion: "With --remove, only what Peel would suggest goes: never a toolchain, an account, a token, or something it couldn't measure. Name tools to narrow it down."
    )

    @Argument(help: "Tools to look at, as `peel caches` names them. All of them when none is given.")
    var tools: [String] = []

    @Flag(help: RemovalOptions.movesWhatPeelSuggests)
    var remove = false

    @OptionGroup var removal: RemovalOptions

    @OptionGroup var output: OutputOptions

    struct Record: Encodable {
        let tool: String
        let id: String
        let size: MeasuredSize
        let locations: [Location]

        struct Location: Encodable {
            let path: String
            let size: MeasuredSize
            let kind: String
            let source: String
            /// Whether `--remove` would move it.
            let suggested: Bool
            /// What holds it back, as `HoldBack` names it, or `null`.
            let heldBack: String?
            /// Why it stays, as the list says it, or `null` when it is suggested.
            let reason: String?

            private enum CodingKeys: String, CodingKey {
                case path, size, kind, source, suggested, heldBack, reason
            }

            /// Encodes a missing `heldBack` and `reason` as `null`, for the reason `AppRecord` gives.
            func encode(to encoder: any Encoder) throws {
                var container = encoder.container(keyedBy: CodingKeys.self)
                try container.encode(path, forKey: .path)
                try container.encode(size, forKey: .size)
                try container.encode(kind, forKey: .kind)
                try container.encode(source, forKey: .source)
                try container.encode(suggested, forKey: .suggested)
                try container.encode(heldBack, forKey: .heldBack)
                try container.encode(reason, forKey: .reason)
            }
        }
    }

    func validate() throws {
        try removal.validate(removing: remove, with: output)
    }

    func run() async throws {
        let exclusions = await UnreadableExclusions.load()
        let all = await ProgressLine.counting { await DeveloperCaches.scan(exclusions: exclusions) }
        let environments = try Self.chosen(from: all, named: tools)
        guard !remove else {
            return try await clean(environments, using: TrashService(exclusions: exclusions))
        }

        if output.json {
            try Output.json(Self.records(for: environments))
        } else if environments.isEmpty {
            Output.line("No developer caches found.")
        } else {
            for environment in environments {
                Output.line("\(Self.title(of: environment, among: environments))  \(Output.size(environment.total))")
                Output.table(Self.rows(for: environment), indent: "  ")
            }
        }
        Self.notes(for: environments).forEach(Output.note)
    }

    /// A tool's name, as `peel caches <tool>` takes it. Electron apps are named for the app, so two can share a name,
    /// and then each gets its identifier beside it.
    static func title(of environment: DeveloperEnvironment, among environments: [DeveloperEnvironment]) -> String {
        let isShared = environments.contains { $0.name == environment.name && $0.id != environment.id }
        return isShared ? "\(environment.name) (\(environment.id))" : environment.name
    }

    static func rows(for environment: DeveloperEnvironment) -> [[String]] {
        environment.locations.map { [Output.size($0.size), Output.path($0.url), $0.kind.summary, note(for: $0)] }
    }

    /// Why `location` stays, in the words the list says it, or nil when `--remove` takes it.
    static func reason(for location: DeveloperEnvironment.Location) -> String? {
        location.keptBecause.map { kept in
            switch kept {
            case .keptByDefault: "kept by default"
            case .heldBack(let heldBack): heldBack.summary
            case .notTheTools: "nothing shows the tool made it"
            case .workspaceMayBeInUse(let lastUsed):
                lastUsed == nil ? "Xcode wrote no date for its workspace" : "its workspace was opened in the last 7 days"
            }
        }
    }

    private static func heldBack(of location: DeveloperEnvironment.Location) -> String? {
        if case .heldBack(let heldBack) = location.keptBecause { heldBack.rawValue } else { nil }
    }

    /// The list's last column: "suggested", or why the folder stays.
    static func note(for location: DeveloperEnvironment.Location) -> String {
        guard let reason = reason(for: location) else { return "suggested" }
        return location.keptBecause == .keptByDefault ? reason : "\(reason), kept"
    }

    /// What `--remove` leaves of the tools it moves from, each folder with why.
    static func staying(in environments: [DeveloperEnvironment]) -> [String] {
        environments.flatMap { environment in
            environment.locations.compactMap { location in
                reason(for: location).map { "\(Output.plain(Output.path(location.url))) stays: \($0)" }
            }
        }
    }

    /// The folders macOS kept Peel out of, said on standard error whatever the output, so that an unknown size is not
    /// read as an empty folder.
    static func notes(for environments: [DeveloperEnvironment]) -> [String] {
        let unread = environments.flatMap(\.locations).filter(\.couldNotBeRead)
        guard !unread.isEmpty else { return [] }
        let isPrivacy = unread.contains { !$0.closedByPermissions }
        return [Output.unreadableNote(for: unread.map(\.url), needsFullDiskAccess: isPrivacy)]
    }

    static func records(for environments: [DeveloperEnvironment]) -> [Record] {
        environments.map { environment in
            Record(
                tool: environment.name, id: environment.id, size: MeasuredSize(environment.total),
                locations: environment.locations.map {
                    Record.Location(
                        path: Output.path($0.url),
                        size: MeasuredSize($0.size),
                        kind: $0.kind.rawValue,
                        source: $0.source,
                        suggested: $0.isRecommended,
                        heldBack: heldBack(of: $0),
                        reason: reason(for: $0)
                    )
                }
            )
        }
    }

    /// Returns the environments named in `tools`, by the name the listing shows or by its identifier, ignoring
    /// case. All of them when `tools` is empty. A name that matches none fails the command, even beside one that
    /// matches: shown the rest, a typo would read as a tool with nothing to show.
    static func chosen(
        from environments: [DeveloperEnvironment],
        named tools: [String]
    ) throws -> [DeveloperEnvironment] {
        guard !tools.isEmpty else { return environments }
        func isNamed(_ environment: DeveloperEnvironment, _ tool: String) -> Bool {
            [environment.name, environment.id].contains { tool.caseInsensitiveCompare($0) == .orderedSame }
        }
        let unmatched = tools.filter { tool in !environments.contains { isNamed($0, tool) } }
        guard unmatched.isEmpty else {
            let names = unmatched.map(Output.quoted).joined(separator: ", ")
            throw CommandFailure("No developer caches of \(names) were found. See `peel caches`.")
        }
        return environments.filter { environment in tools.contains { isNamed(environment, $0) } }
    }

    func clean(
        _ environments: [DeveloperEnvironment],
        using service: TrashService,
        recordingIn log: RemovalLog = RemovalLog(),
        refusals: RefusalLog = RefusalLog()
    ) async throws {
        // Nothing of a tool moves while its app runs, since the app writes in those folders. A tool nothing would move
        // from holds nothing up, whether its app runs or not.
        let moving = environments.filter { $0.locations.contains(where: \.isRecommended) }
        let open = moving.filter { $0.runningApp != nil }
        let closed = environments.filter { environment in !open.contains { $0.id == environment.id } }
        let closedMoving = moving.filter { environment in !open.contains { $0.id == environment.id } }
        let locations = closedMoving.flatMap { environment in environment.locations.filter(\.isRecommended) }
        // With nothing else to move, the first of them is the error below.
        for environment in open.dropFirst(locations.isEmpty ? 1 : 0) {
            Output.note(Self.quitFirst(environment))
        }
        Self.notes(for: environments).forEach(Output.note)
        // Nobody asked for a folder Peel doesn't suggest on its own, so it is said here and never recorded as refused.
        let staying = Self.staying(in: closed)
        guard !locations.isEmpty else {
            if let first = open.first {
                throw CommandFailure(Self.quitFirst(first))
            }
            Output.line("Nothing here is safe to suggest. See `peel caches`.")
            staying.forEach(Output.note)
            return
        }
        let cleanup = Cleanup.of(
            locations.map { (url: $0.url, size: $0.size) },
            source: closedMoving.count == 1 ? closedMoving[0].name : "Developer caches",
            sourceKey: closedMoving.count == 1 ? nil : "tool",
            tool: "developer",
            service: service
        )
        try await cleanup.run(
            question: "Move \(Output.count(cleanup.moving.count, "item", "items")) to the Trash?",
            notes: staying,
            dryRun: removal.dryRun,
            yes: removal.yes,
            using: service,
            recordingIn: log,
            refusals: refusals,
            checkingAgain: {
                // The question takes time, and an app may have been opened meanwhile.
                if let reopened = closedMoving.first(where: { $0.runningApp != nil }) {
                    throw CommandFailure(Self.quitFirst(reopened))
                }
            }
        )
    }

    private static func quitFirst(_ environment: DeveloperEnvironment) -> String {
        "Quit \(Output.plain(environment.runningApp ?? environment.name)) first: \(environment.name)'s caches stay while it runs."
    }
}

struct ProjectsCommand: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "projects",
        abstract: "List what builds left behind in your projects, and move it to the Trash.",
        discussion: "A folder only counts when the file that makes it sits beside it, its tool tagged it as a cache, or what it holds could only be its tool's, as with Python's __pycache__. Projects changed in the last 7 days or whose last change Peel couldn't tell, folders under a name that could mean anything, environments and installed packages, and folders Peel holds back, such as one Git tracks or one with a repository or a key inside, are listed but never suggested, and --remove moves only what is suggested."
    )

    @Argument(help: "Folders your projects live in.", completion: .directory)
    var folders: [String]

    @Flag(help: RemovalOptions.movesWhatPeelSuggests)
    var remove = false

    @OptionGroup var removal: RemovalOptions

    @OptionGroup var output: OutputOptions

    struct Record: Encodable {
        let path: String
        let project: String
        /// `null` for a folder known only by the cache directory tag its tool wrote.
        let tool: String?
        let size: MeasuredSize
        let suggested: Bool
        let recentlyActive: Bool
        /// Why measuring the folder left it to be chosen by hand, or `null` when nothing did.
        let heldBack: String?
        /// Why the folder isn't suggested, in the words of the list's last column, or `null` when it is.
        let reason: String?

        private enum CodingKeys: String, CodingKey {
            case path
            case project
            case tool
            case size
            case suggested
            case recentlyActive
            case heldBack
            case reason
        }

        /// Encodes a missing `heldBack` or `reason` as `null`, for the reason `AppRecord` gives.
        func encode(to encoder: any Encoder) throws {
            var container = encoder.container(keyedBy: CodingKeys.self)
            try container.encode(path, forKey: .path)
            try container.encode(project, forKey: .project)
            try container.encode(tool, forKey: .tool)
            try container.encode(size, forKey: .size)
            try container.encode(suggested, forKey: .suggested)
            try container.encode(recentlyActive, forKey: .recentlyActive)
            try container.encode(heldBack, forKey: .heldBack)
            try container.encode(reason, forKey: .reason)
        }
    }

    /// Fails when none of the folders can be searched, giving the reason for each, rather than report that
    /// nothing built was found.
    func validate() throws {
        try removal.validate(removing: remove, with: output)
        let refused = folders.map(URL.init(argument:)).compactMap { root in
            ProjectArtifacts.refusal(for: root).map { "\(Output.plain(Output.path(root))): \($0.summary)" }
        }
        guard refused.count < folders.count else {
            throw ValidationError(refused.joined(separator: "\n"))
        }
    }

    func run() async throws {
        let roots = folders.map(URL.init(argument:))
        let exclusions = await UnreadableExclusions.load()
        let scan = await ProgressLine.counting { await ProjectArtifacts.scan(roots: roots, exclusions: exclusions) }
        let artifacts = scan.artifacts
        if remove {
            Self.notes(for: scan).forEach(Output.note)
            return try await clean(artifacts, using: TrashService(exclusions: exclusions))
        }

        if output.json {
            try Output.json(Self.report(for: scan))
        } else if artifacts.isEmpty {
            Output.line("Nothing built was found in those folders.")
        } else {
            Output.table(Self.rows(for: artifacts))
        }
        Self.notes(for: scan).forEach(Output.note)
    }

    /// What `--json` writes.
    struct Report: Encodable {
        let artifacts: [Record]
        let unreadableLocations: [String]
        /// Folders the scan didn't search: chosen ones, and ones inside them that another app keeps in step.
        let skippedLocations: [String]
        /// True when there were more folders than Peel looks at in one go, so the list isn't all of them.
        let cutShort: Bool
    }

    /// What the scan couldn't look at, said on standard error whatever the output, so that an empty answer is not
    /// read as nothing being there.
    static func notes(for scan: ProjectArtifacts.Scan) -> [String] {
        var notes = scan.refusedRoots.map { "\(Output.path($0.url)): \($0.reason.summary)" }
        if !scan.unreadableLocations.isEmpty {
            notes.append(
                Output.unreadableNote(for: scan.unreadableLocations, needsFullDiskAccess: scan.needsFullDiskAccess)
            )
        }
        if scan.wasCutShort {
            notes.append("There were more folders than Peel looks at in one go, so this list isn't all of them.")
        }
        return notes
    }

    static func report(for scan: ProjectArtifacts.Scan) -> Report {
        Report(
            artifacts: scan.artifacts.map {
                Record(
                    path: Output.path($0.url),
                    project: Output.path($0.project),
                    tool: $0.tool,
                    size: MeasuredSize($0.size),
                    suggested: $0.isRecommended,
                    recentlyActive: $0.isRecentlyActive,
                    heldBack: $0.heldBack?.rawValue,
                    reason: reason(for: $0)
                )
            },
            unreadableLocations: scan.unreadableLocations.map(Output.path),
            skippedLocations: scan.refusedRoots.map { Output.path($0.url) },
            cutShort: scan.wasCutShort
        )
    }

    func clean(
        _ artifacts: [ProjectArtifact],
        using service: TrashService,
        recordingIn log: RemovalLog = RemovalLog(),
        refusals: RefusalLog = RefusalLog()
    ) async throws {
        let suggested = artifacts.filter(\.isRecommended)
        let staying = artifacts.compactMap { artifact in
            Self.reason(for: artifact).map { "\(Output.plain(Output.path(artifact.url))) stays: \($0)" }
        }
        guard !suggested.isEmpty else {
            Output.line("Nothing here is safe to suggest. See `peel projects`.")
            staying.forEach(Output.note)
            return
        }
        let (source, sourceKey) = Self.source(of: suggested)
        let cleanup = Cleanup.of(
            suggested.map { (url: $0.url, size: $0.size) },
            source: source,
            sourceKey: sourceKey,
            tool: "projects",
            service: service
        )
        try await cleanup.run(
            question: "Move \(Output.count(cleanup.moving.count, "folder", "folders")) to the Trash?",
            notes: staying,
            dryRun: removal.dryRun,
            yes: removal.yes,
            using: service,
            recordingIn: log,
            refusals: refusals,
            move: { service, urls in
                // The question takes time, and work may have started in a project meanwhile.
                let changed = await ProjectArtifacts.changedSinceScan(suggested, among: artifacts)
                return await service.trash(urls, refusing: { changed[$0] })
            }
        )
    }

    /// How History names a removal: by its project when it moves from one, otherwise as build artifacts.
    static func source(of artifacts: [ProjectArtifact]) -> (source: String, sourceKey: String?) {
        let projects = Set(artifacts.map { PathPattern.comparablePath(of: $0.project) })
        guard projects.count == 1, let project = artifacts.first?.project else { return ("Build artifacts", "tool") }
        return (project.lastPathComponent, nil)
    }

    static func rows(for artifacts: [ProjectArtifact]) -> [[String]] {
        artifacts.map { [Output.size($0.size), Output.path($0.url), $0.tool ?? "tagged as a cache", note(for: $0)] }
    }

    /// Says in words why `artifact` is kept, or "suggested".
    static func note(for artifact: ProjectArtifact) -> String {
        reason(for: artifact).map { "\($0), kept" } ?? "suggested"
    }

    /// Why `artifact` isn't suggested, or nil when it is.
    static func reason(for artifact: ProjectArtifact) -> String? {
        switch artifact.keptBecause {
        case .heldBack(let heldBack): heldBack.summary
        case .installedPackages: "installed packages"
        case .genericName: "a common folder name"
        case .changedRecently: "changed in the last 7 days"
        case .lastChangeNotKnown: "too large to tell when it last changed"
        case .lastChangeNotReadInTime: "couldn't read in time when it last changed"
        case nil: nil
        }
    }
}

struct DuplicatesCommand: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "duplicates",
        abstract: "Find folders and files with identical contents.",
        discussion: "Without folders, Peel scans Desktop, Documents, Downloads, Pictures, Movies, and Music. The first copy of each group is the one Peel suggests keeping. A copy in a folder that syncs to your other devices, such as iCloud Drive, is listed as one that stays and is never moved, and so is a copy with Finder tags, a Finder comment, or a resource fork the others lack, which keeps the bytes for them, so the others can all go. A folder is a copy of another only when every file under it matches, so what a folder already speaks for isn't listed again on its own."
    )

    @Argument(help: "Folders to scan.", completion: .directory)
    var folders: [String] = []

    @Option(help: "Only files of this kind.")
    var kind: KindArgument?

    @Option(name: .customLong("min-size"), help: "Only files at least this large, and folders holding at least this much, like 500KB or 1.5GB, or 0 for every size. Without it, \(DuplicateScanOptions.defaultMinimumSize / 1_000)KB, as in the Peel app.")
    var minimumSize: ByteSize?

    @Flag(help: RemovalOptions.movesWhatPeelSuggests)
    var remove = false

    @OptionGroup var removal: RemovalOptions

    @OptionGroup var output: OutputOptions

    struct Record: Encodable {
        let size: Int64
        let reclaimableSize: Int64
        /// The copies that may move, the kept one first unless a copy in `stays` keeps the bytes.
        let files: [String]
        /// The copies that sync to other devices, listed and never moved.
        let synced: [String]
        /// The apps that sync those copies, each with its marker.
        let syncedBy: [SyncRecord]
        /// The copies with Finder tags, a Finder comment, or a resource fork the others lack, never moved.
        let stays: [String]
    }

    struct FolderRecord: Encodable {
        let size: Int64
        let reclaimableSize: Int64
        let fileCount: Int
        let folders: [String]
    }

    struct Found: Encodable {
        let folders: [FolderRecord]
        let files: [Record]
        let unreadableLocations: [String]
        /// Chosen folders the scan didn't look in.
        let skippedLocations: [String]
        /// The same folders, each with why it wasn't looked in.
        let setAside: [SetAside]
    }

    struct SetAside: Encodable {
        let path: String
        let reason: String
    }

    /// Checks the folders here rather than in `run()`: only while it parses does ArgumentParser know which
    /// subcommand's usage to print. The finder needs no exclusions, since they don't decide what can be scanned.
    func validate() throws {
        try removal.validate(removing: remove, with: output)
        // One finder for every folder: each new finder resolves the home folder's links again.
        let finder = DuplicateFinder()
        let urls = folders.map(URL.init(argument:))
        let missing = urls.filter { !isAFolder($0) }
        guard missing.isEmpty else {
            throw ValidationError("\(missing.map(Output.path).joined(separator: ", ")): no such folder.")
        }
        let rejected = urls.compactMap { url in finder.refusal(of: url).map { "\(Output.path(url)): \($0.summary)" } }
        guard rejected.isEmpty else {
            throw ValidationError(rejected.joined(separator: "\n"))
        }
    }

    /// Comparing reads files, so nothing is compared while the exclusions can't be read.
    static func refusal(for exclusions: Exclusions, savedAt url: URL) -> CommandFailure? {
        guard exclusions.isUnreadable else { return nil }
        return CommandFailure("Peel couldn't read your exclusions at \(Output.plain(url.path(percentEncoded: false))), so it compares nothing, since it would read what you asked it to leave alone. Open Peel and click Start Over in Settings > Exclusions." + exclusions.whyUnreadable.sentence)
    }

    func run() async throws {
        let store = ExclusionStore()
        let exclusions = await store.load()
        if let refusal = Self.refusal(for: exclusions, savedAt: store.url) { throw refusal }
        let finder = DuplicateFinder(exclusions: exclusions, digestMemory: DigestMemory())
        let urls = folders.isEmpty ? finder.defaultFolders : folders.map(URL.init(argument:))
        let scan = try await ProgressLine.reporting { show in
            try await finder.scan(options(for: urls)) { show(Self.progress($0)) }
        }
        if remove {
            Self.notes(for: scan).forEach(Output.note)
            return try await clean(scan, using: TrashService(exclusions: exclusions))
        }

        if output.json {
            try Output.json(Self.found(in: scan))
        } else if scan.groups.isEmpty, scan.folderGroups.isEmpty {
            Output.line("No duplicates found.")
        } else {
            for group in scan.folderGroups {
                Output.line(Self.heading(for: group))
                Output.table(Self.rows(for: group.folders.map(\.url)), indent: "  ")
            }
            for group in scan.groups {
                Output.line(Self.heading(for: group))
                Output.table(Self.rows(for: group), indent: "  ")
            }
            let total =
                scan.groups.reduce(0) { $0 + $1.reclaimableSize }
                + scan.folderGroups.reduce(0) { $0 + $1.reclaimableSize }
            Output.line("Total to free: \(Output.size(total))")
        }
        Self.notes(for: scan).forEach(Output.note)
    }

    func options(for folders: [URL]) -> DuplicateScanOptions {
        var options = DuplicateScanOptions(folders: folders)
        if let kind { options.kind = kind.fileKind }
        if let minimumSize { options.minimumSize = minimumSize.bytes }
        return options
    }

    /// What the scan didn't look at, said on standard error whatever the output, so that an empty answer is not
    /// read as nothing being there.
    static func notes(for scan: DuplicateScan) -> [String] {
        var notes: [String] = []
        if !scan.unreadableLocations.isEmpty {
            notes.append(
                Output.unreadableNote(for: scan.unreadableLocations, needsFullDiskAccess: scan.needsFullDiskAccess)
            )
        }
        notes += scan.skippedLocations.map { "Peel didn't look in \(Output.path($0.url)): \($0.reason.summary)." }
        let synced = scan.groups.reduce(0) { total, group in total + group.files.count { $0.heldBack == .inTheCloud } }
        if synced > 0 {
            notes.append("\(Output.count(synced, "copy syncs", "copies sync")) to your other devices, so Peel lists \(asCopies(synced)).")
            notes += keepers(of: scan.groups.flatMap(\.files)).compactMap(\.note)
        }
        let staying = scan.groups.reduce(0) { total, group in
            total + group.files.count { $0.heldBack == .keepsWhatTheOthersLack }
        }
        if staying > 0 {
            notes.append("\(Output.count(staying, "copy has", "copies have")) Finder tags, a Finder comment, or a resource fork the others lack, so Peel lists \(asCopies(staying)).")
        }
        return notes
    }

    private static func asCopies(_ count: Int) -> String {
        count == 1 ? "it as a copy that stays and never moves it" : "them as copies that stay and never moves them"
    }

    /// The apps that sync the copies held back for syncing through one, each marker once, in the order found.
    static func keepers(of files: [DuplicateFile]) -> [SyncKeeper] {
        files.filter { $0.heldBack == .inTheCloud }.compactMap(\.syncedBy).reduce(into: []) { keepers, keeper in
            if !keepers.contains(keeper) { keepers.append(keeper) }
        }
    }

    static func found(in scan: DuplicateScan) -> Found {
        Found(
            folders: scan.folderGroups.map { group in
                FolderRecord(
                    size: group.size,
                    reclaimableSize: group.reclaimableSize,
                    fileCount: group.fileCount,
                    folders: group.folders.map { Output.path($0.url) }
                )
            },
            files: scan.groups.map { group in
                Record(
                    size: group.size,
                    reclaimableSize: group.reclaimableSize,
                    files: group.movableFiles.map { Output.path($0.url) },
                    synced: group.files.filter { $0.heldBack == .inTheCloud }.map { Output.path($0.url) },
                    syncedBy: keepers(of: group.files).compactMap(\.record),
                    stays: group.files.filter { $0.heldBack == .keepsWhatTheOthersLack }.map { Output.path($0.url) }
                )
            },
            unreadableLocations: scan.unreadableLocations.map(Output.path),
            skippedLocations: scan.skippedLocations.map { Output.path($0.url) },
            setAside: scan.skippedLocations.map { SetAside(path: Output.path($0.url), reason: $0.reason.summary) }
        )
    }

    /// The progress line for each step of the scan. The folders are compared by the files inside them, so both
    /// steps compare and read files.
    static func progress(_ report: DuplicateScanProgress) -> String {
        switch report {
        case .listing(let found): "Looking through folders: \(Output.number(found)) found"
        case .collecting(let found): "Looking for files: \(Output.number(found)) found"
        case .comparing(let compared, let total): "Comparing files: \(Output.number(compared)) of \(Output.number(total))"
        case .verifying(let read, let total): "Reading contents: \(Output.size(read)) of \(Output.size(total))"
        }
    }

    static func heading(for group: DuplicateFolderGroup) -> String {
        "\(Output.count(group.folders.count, "copy", "copies")) of a folder of \(Output.count(group.fileCount, "file", "files")), \(Output.size(group.size)), \(Output.size(group.reclaimableSize)) to free"
    }

    static func heading(for group: DuplicateGroup) -> String {
        "\(Output.count(group.files.count, "copy", "copies")) of \(Output.size(group.size)), \(Output.size(group.reclaimableSize)) to free"
    }

    /// One row per copy. Only the first, the copy Peel suggests keeping, is marked "keep".
    static func rows(for copies: [URL]) -> [[String]] {
        copies.enumerated().map { index, url in [index == 0 ? "keep" : "", Output.path(url)] }
    }

    /// One row per copy of a file: one Peel never moves is marked "stays", and the first that may move "keep",
    /// unless a copy that stays keeps the bytes and every other may go.
    static func rows(for group: DuplicateGroup) -> [[String]] {
        let kept = group.holdsACopyWithWhatOthersLack ? nil : group.movableFiles.first?.url
        return group.files.map { file in
            [file.heldBack != nil ? "stays" : file.url == kept ? "keep" : "", Output.path(file.url)]
        }
    }

    func clean(
        _ scan: DuplicateScan,
        using service: TrashService,
        recordingIn log: RemovalLog = RemovalLog(),
        refusals: RefusalLog = RefusalLog()
    ) async throws {
        let folders = scan.folderGroups.flatMap { $0.folders.dropFirst() }
        let files = scan.groups.flatMap(\.suggestedFiles)
        guard !folders.isEmpty || !files.isEmpty else {
            Output.line(
                scan.groups.isEmpty && scan.folderGroups.isEmpty
                    ? "No duplicates found." : "Nothing to move: every other copy syncs to your other devices."
            )
            return
        }
        // Where each group's kept copy is comes first, and the copies that sync, which stay: it is what the
        // decision rests on.
        let kept = scan.folderGroups.compactMap { $0.folders.first?.url }.map { ["keep", Output.path($0)] }
            + scan.groups.flatMap { group in
                Self.rows(for: group).filter { $0[0] != "" }
            }
        Output.table(kept)
        let cleanup = Cleanup.of(
            folders.map { (url: $0.url, size: $0.reclaimableSize) }
                + files.map { (url: $0.url, size: $0.reclaimableSize) },
            source: "Duplicates",
            sourceKey: "tool",
            tool: "duplicates",
            service: service
        )
        try await cleanup.run(
            question: "Move \(Output.count(cleanup.moving.count, "copy", "copies")) to the Trash? One of each is always kept.",
            dryRun: removal.dryRun,
            yes: removal.yes,
            using: service,
            recordingIn: log,
            refusals: refusals
        ) { service, urls in
            let wanted = Set(urls)
            return await DuplicateRemoval.trash(
                Set(files.map(\.url)).intersection(wanted),
                folders: Set(folders.map(\.url)).intersection(wanted),
                from: scan,
                using: service
            )
        }
    }
}

struct SearchCommand: AsyncParsableCommand {
    static let configuration = CommandConfiguration(
        commandName: "search",
        abstract: "Search the Spotlight index for files.",
        discussion: "Peel asks Spotlight, so it finds only what Spotlight indexes, and network volumes aren't searched. It lists files alone, yours first, then those an app keeps in a Library folder, each largest first, at most \(Output.number(FileSearch.maximumResults)), and it says how many it left out and why."
    )

    @Option(help: "Part of the file name.")
    var name: String?

    @Option(help: "The kind of file.")
    var kind: KindArgument?

    @Option(name: .customLong("min-size"), help: "Only files at least this large, like 500KB or 1.5GB.")
    var minimumSize: ByteSize?

    // Unconditional, or `-1` reads as an option and `validate` never says what is wrong with it.
    @Option(name: .customLong("older-than"), parsing: .unconditional, help: "Only files not modified in this many days.")
    var olderThan: Int?

    @Flag(help: "Search every disk on this Mac, not only your home folder. Network volumes aren't searched.")
    var everywhere = false

    @OptionGroup var output: OutputOptions

    private struct Record: Encodable {
        let path: String
        /// What moving the file would free.
        let size: Int64
        /// Its length, which `--min-size` reads.
        let length: Int64
        let modificationDate: Date
    }

    var criteria: FileSearchCriteria {
        var criteria = FileSearchCriteria()
        criteria.name = name ?? ""
        criteria.kind = kind?.fileKind ?? .any
        criteria.minimumSize = minimumSize?.bytes ?? 0
        criteria.unmodifiedDays = olderThan ?? 0
        criteria.scope = everywhere ? .computer : .home
        return criteria
    }

    func validate() throws {
        guard criteria.isSearchable else {
            throw ValidationError("Add --name, --kind, or --min-size to narrow the search.")
        }
        if let olderThan, olderThan < 0 {
            throw ValidationError("--older-than can't be negative.")
        }
    }

    func run() async throws {
        let results = await FileSearch.run(criteria, exclusions: UnreadableExclusions.load(listsEverything: false))
        guard results.didRun else {
            throw CommandFailure("Spotlight didn't answer, so Peel can't say what is on this Mac. Try the search again.")
        }
        guard !results.isNothingIndexed else {
            let unindexed = results.unindexedDisks.map(Output.plain).joined(separator: ", ")
            throw CommandFailure("Spotlight isn't indexing \(unindexed), so Peel can't find anything there. To search a disk, remove it from System Settings > Spotlight > Search Privacy if it is listed there, or turn its indexing on with `sudo mdutil -i on` and its path.")
        }
        try report(results)
    }

    func report(_ results: FileSearchResults) throws {
        if output.json {
            try Output.json(
                results.files.map {
                    Record(
                        path: Output.path($0.url), size: $0.size, length: $0.length,
                        modificationDate: $0.modificationDate
                    )
                }
            )
        } else if results.files.isEmpty {
            Output.line(results.leftOut.isEmpty ? "No files found." : "No files listed.")
        } else {
            Output.table(
                results.files.map { [Output.size($0.size), Output.day($0.modificationDate), Output.path($0.url)] }
            )
        }
        if results.isTruncated {
            Output.note("Only the first \(Output.number(FileSearch.maximumResults)) files are shown, yours before those an app keeps in a Library folder, each largest first. Narrow the search to see the rest.")
        }
        for reason in FileSearch.LeftOut.allCases {
            guard let count = results.leftOut[reason] else { continue }
            Output.note(Self.note(for: reason, count: count))
            if reason == .syncs { results.syncedBy.compactMap(\.note).forEach(Output.note) }
        }
        if !results.unindexedDisks.isEmpty {
            let unindexed = results.unindexedDisks.map(Output.plain).joined(separator: ", ")
            Output.note("Spotlight isn't indexing \(unindexed), so nothing there was searched.")
        }
    }

    private static func note(for reason: FileSearch.LeftOut, count: Int) -> String {
        let files = Output.count(count, "file", "files")
        return switch reason {
        case .syncs:
            "Left out: \(files) in iCloud or another place that syncs to your other devices. Peel never moves what syncs."
        case .excluded: "Left out: \(files) among what you excluded."
        case .exclusionsNotKnown:
            "Left out: \(files), since Peel can't check what it finds against your exclusions until it can read them."
        case .protected:
            "Left out: \(files) in places Peel never moves anything from, such as macOS itself, Mail, Messages, or a photo library."
        case .couldNotBeRead: "Left out: \(files) macOS didn't let Peel look at."
        }
    }
}