Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.
Swift cache-cleanercleanerclideveloper-toolsdisk-cleanupdisk-spaceduplicate-finderhomebrewliquid-glassmac-cleanermacosmacos-appmacos-golden-gatemacos-tahoemacos-tweaksswiftswiftuiterminal-themesuninstalluninstaller
Bring ARCHITECTURE.md up to date
Țugui Dragoș13f3bfb808cc
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 80600160..29047ea7 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -13,15 +13,16 @@ Peel is four programs built from one Xcode project, and a Swift package that hol|---|---|---|---|| Peel.app | `Peel/` | You | The SwiftUI app: every page, and a model for each. || The helper | `PeelHelper/` | root | A launch daemon for the few things only an administrator can do: move items to the Trash and back, and start or stop another vendor's launch daemon. |-| The Finder extension | `PeelFinder/` | You, sandboxed | Adds Uninstall with Peel to Finder's menu for an app, and opens Peel with `peel://open?path=`. |-| The `peel` tool | `PeelCLI/` | You | The command line tool, shipped inside `Peel.app/Contents/Helpers`. |+| The Finder extension | `PeelFinder/` | You, sandboxed | Adds Uninstall with Peel… to the menu Finder shows when you Control-click an app, and opens Peel with `peel://open?path=`. |+| The `peel` tool | `PeelCLI/` | You | The command-line tool, shipped inside `Peel.app/Contents/Helpers`. |```mermaidflowchart LRFinder["Finder extension<br>sandboxed"] -- "peel://open" --> App["Peel.app<br>runs as you"]Finder --> Link["PeelLink<br>what a link says"]App --> Link- CLI["peel command<br>runs as you"] --> Core["PeelCore<br>scans, matches, moves"]+ CLI["peel command<br>runs as you"] --> Commands["PeelCommandLine<br>the peel commands"]+ Commands --> Core["PeelCore<br>scans, matches, moves"]App --> CoreApp -- "XPC, administrators only" --> Helper["Helper<br>runs as root"]Core --> Privileged["PeelPrivileged<br>what may be touched"]@@ -31,9 +32,9 @@ flowchart LRThe package, `Packages/PeelCore`, has four libraries:- **PeelCore** decides and acts: it finds apps and their leftovers, measures folders, matches files to apps,- and moves things to the Trash. It has no pages or windows, only three AppKit pieces the app's lists and- sheets use (`RowCheckboxButton`, `SheetInFront`, `TextEditing`), and it speaks plain English; the app- words everything a person reads.+ and moves things to the Trash. It has no pages or windows, only three pieces of interface the app's lists and+ sheets use (`RowCheckboxButton`, `SheetInFront`, `TextEditing`), and it speaks plain English: the app words+ everything a person reads in Peel, and `PeelCommandLine` what `peel` prints.- **PeelPrivileged** is the part the helper shares: which paths may be touched, what is protected, how a toolis run, and how a path is split into names. The helper links nothing else, so it stays small.- **PeelCommandLine** holds the `peel` commands. `PeelCLI` is only their entry point.@@ -41,11 +42,13 @@ The package, `Packages/PeelCore`, has four libraries:notifications that send it too, and the app that reads it. The extension links nothing else.Keeping the logic in the package is what makes it testable: `swift test --package-path Packages/PeelCore` runs-more than 1,800 tests without building the app.+more than 2,200 tests without building the app.## Where to start reading-- `Peel/PeelApp.swift`: the app's entry point, its windows, its menu commands, and the menu bar panel.+- `Peel/PeelApp.swift`: the app's entry point, its windows, and the menu bar panel.+- `Peel/Navigation/`: the sidebar and the tools it lists (`ToolSidebar`, `Tool`), the menu commands+ (`PeelCommands`), and the App Shortcuts (`PeelShortcuts`).- `Peel/Views/ContentView.swift`: the main window, its sidebar, and how a page is chosen.- `Packages/PeelCore/Sources/PeelCore/Removal/Uninstallation.swift`: what an uninstall offers, and what it selectsfor you.@@ -57,20 +60,25 @@ more than 1,800 tests without building the app.remove, and what the helper may touch.- `PeelHelper/HelperService.swift`: the helper's operations.- `Packages/PeelCore/Sources/PeelCommandLine/PeelCommand.swift`, which registers the `peel` commands kept in- `Commands/`, and `Support/Cleanup.swift`, the path the commands that remove what a scan found take.+ `Commands/`, and `Support/Cleanup.swift`, the one path every command that removes what a scan found goes through.## How a removal travels-Take the most common case, uninstalling an app. Every other page follows the same path with its own scanner.+Take the most common case, uninstalling an app. Every other page that moves something to the Trash follows the same+path with its own scanner; iCloud Drive's Remove Downloads only asks iCloud to drop this Mac's copy of a file, and+the Homebrew page's uninstall and cleanups are Homebrew's own.1. **Scan.** `Uninstallation.prepare` asks `LeftoverScanner` to look through every place an app keeps files(`SearchLocation`): Application Support, Caches, Containers, Preferences, launch agents, plug-in folders, the- top of the home folder, and more, and adds what a Homebrew cask or an installer's receipt names for the app,- and the cask's own folder in Homebrew's Caskroom when Homebrew installed it (`HomebrewPackage.caskroomFolder`).- A page's scan runs through its `ScanRun`, so a newer scan or the Stop button ends an older one, and it counts- what it reads so the page can show progress.+ top of the home folder, and more. It adds the paths the app's Homebrew cask names in its `uninstall` and `zap`+ stanzas, whether or not Homebrew installed the app (`CaskEvidence`); the installer receipt that proves the app,+ its two files in `/private/var/db/receipts`, while what the package installed stays with the Package Receipts+ page; the cask's own folder in Homebrew's Caskroom when Homebrew installed it (`HomebrewPackage.caskroomFolder`);+ and what an area the app manages keeps in the home folder, such as Xcode's simulators. A page's scan runs+ through its `ScanRun`, so a newer scan or the Stop button ends an older one, and it counts what it reads so the+ page can show progress.2. **Match.** For each file, `LeftoverMatcher` weighs the evidence that it belongs to the app: its bundle- identifier, the identifiers of what the app embeds, its application groups, its signing team, its name. A+ identifier, the identifiers of what the app embeds, its application groups, its signing team, and its name. Aplug-in and a container named by a UUID are also weighed by the identifier they declare: a plug-in's namesays what it does and a UUID says nothing, so the identifier decides whose they are. A launch job is weighedby the program it runs, since anyone can name its file: a job that runs a program inside the app is the@@ -95,73 +103,94 @@ Take the most common case, uninstalling an app. Every other page follows the sam- The question before the move freezes what it asks about, and the move takes exactly that(`RemovalQuestion`, which also runs one removal at a time and holds the page's scans until it is over).- Before any of it, the app has to quit, and Peel offers Force Quit when it doesn't (`QuitBeforeRemoving`).+ When the app had to quit, its page scans again before asking, since what it wrote until then was not there+ when the page scanned.- The app moves first, and its files follow only once it has moved, so an app that stays keeps everything of- its own (`TrashService`'s `trash(apps:thenFiles:)`, which an app's page, several apps' page, Remove Peel, and- `peel uninstall` share).+ its own (`TrashService`'s `trash(apps:thenFiles:usingHelperFor:lettingTheirProgramsRun:)`, which an app's+ page, several apps' page, Remove Peel, and `peel uninstall` share). A folder named for the app or its maker+ that the move leaves empty goes with them (`MakersFolders`).- `TrashService` asks `RemovalGuard` about each item first, holds the folder around the item open, asks againabout what the kernel calls that folder, and moves the item through it, so the thing judged is the thingmoved. Items only an administrator can move go through the helper, and the links an app's tools and theirshell completions left in `/usr/local` go last, once the app they lead into has moved. A browser's manifest in`/Library` goes through the helper too, which takes it only once the program it names is gone.- An item stays where it is while a program holds it (`OpenFiles`): a file one of the user's programs holds- open, or the program any process runs from it. Inside an app, which is code and loses nothing when it moves,- a file open only for reading holds nothing, and neither does the program running from an app that- uninstalls itself once it has moved (`UninstallsItself`: Mullvad VPN's daemon, and Citrix Workspace's agent and- TeamViewer's daemon, each known by the `WatchPaths` of its job file), whose uninstaller's files are held back- (`leftToItsUninstaller`) rather than moved first.+ open, or the program any process runs from it. When only an app's own background programs hold it, the move+ stops their launch jobs, moves the app, and starts each job again unless its file went to the Trash too.+ Inside an app, which is code and loses nothing when it moves, a file open only for reading holds nothing, and+ neither does the program running from an app that uninstalls itself once it has moved (`UninstallsItself`:+ Mullvad VPN's daemon, and Citrix Workspace's agent and TeamViewer's daemon, each known by the `WatchPaths` of+ its job file), whose uninstaller's files are held back (`leftToItsUninstaller`) rather than moved first.- What Peel itself runs from never moves, nor anything holding it, such as the folder a copy built from sourceruns from: only Remove Peel moves Peel (`TrashFailure.Reason.peelRunsFromIt`).- An app carrying a system extension macOS installed is left to Finder (`RemovedElsewhere.byFinder`): Finder'smove asks macOS to remove the extension and Peel's would not, so Peel moves nothing of the app, on its page,- among several apps and in `peel uninstall` alike (`AppExtensions.installed(carriedBy:)`, which also says whether- System Settings deletes every one: `AppExtension.systemSettingsDeletesIt`, a network extension on macOS 27, by- the category `systemextensionsctl` lists it under).+ among several apps, on the Package Receipts and Homebrew pages, and in `peel uninstall` alike+ (`AppExtensions.installed(carriedBy:)`, which also says whether System Settings deletes every one:+ `AppExtension.systemSettingsDeletesIt`, a network extension on macOS 27, by the category `systemextensionsctl`+ lists it under).+ - A security or management agent whose maker removes it with an uninstaller of its own is left to that+ uninstaller (`RemovedElsewhere.byItsMaker`, `MakersUninstaller`), and so is an uninstaller app its maker+ documents, such as Chrome Remote Desktop Host Uninstaller. Each is known by its checked signing team and the+ identifier its maker documents; its page names the maker's step and links the instructions, nothing of it is+ selected or moved, and `peel uninstall` refuses it.- A program another account runs, root's included, can't be quit by the person or by Peel (`kill(2)` answers`EPERM`), so it is never in the question to quit apps (`RunningCopies.Process.mayBeQuit`), and what it runs- from stays with a reason of its own (`heldByAnotherAccount`). `OpenFiles.refusal(of:)` is the one rule.+ from stays with a reason of its own (`heldByAnotherAccount`), as does an item only macOS's own programs hold+ (`inUseByMacOS`), since nobody quits those. `OpenFiles.refusal(of:lettingItsProgramsRun:)` is the one rule.- The app's privacy permissions are reset, when that was chosen, just before the move and only once thechecks the move makes first (the guard, History, and the programs holding it) say it will go(`PrivacyReset`).6. **Finish.** Only for what really moved: the launch jobs whose files went are stopped, macOS is told to- forget the preference domains whose files went, and an uninstalled app's Dock icon comes out- (`DockTiles`).+ forget the preference domains whose files went, and an uninstalled app's Dock icon comes out (`DockTiles`),+ unless Also remove from the Dock was turned off, or `peel uninstall` was given `--keep-in-dock`. On macOS 27,+ an app's page and several apps' page also say when macOS still starts the app's login items at login, now from+ the Trash, until the Trash is emptied (`TrashResult.startsFromTheTrash`).7. **Record.**- Every removal goes into History (`removals.json`, through `RemovalLog`), with where each item came from andwhere it went, so it can be put back; History keeps the most recent 20,000 items. A removal is one entry,even when it moved what was selected on several pages.- - As it records, History adds what moved to the totals Home shows (`totals.json`, through `RemovalTotals`), so- the app and `peel` count alike.+ - As it records, History adds what moved to the totals Home and the menu bar panel show (`totals.json`, through+ `RemovalTotals`), so the app and `peel` count alike.- Each item is also written down the moment it moves (`removals.journal`, through `RemovalJournal`), so what a- removal cut short moved reaches History the next time it is read, as an interrupted removal. Quitting the app- waits for a removal until History has it (`QuitGuard`), as `peel` carries on through Ctrl-C- (`Uninterrupted`).+ removal moved before it was cut short reaches History the next time History is read, as an interrupted+ removal. Quitting the app waits for a removal until History has it (`QuitGuard`), as `peel` carries on+ through Control-C (`Uninterrupted`).- While History cannot be read nothing moves (`RemovalLog.canBeRead`, asked by `TrashService` before a removal)- until the History page starts it over.+ until Start Over, on the History page, sets the unreadable file aside.- What Peel refused to move is recorded too (`refusals.json`), and History lists it under Not Moved, oneremoval to an entry.+ - What only an administrator can move, from a place the helper doesn't serve, stays where it is, and once the+ app has moved, an uninstall records it (`left-for-an-administrator.json`, through `LeftForAnAdministrator`),+ so Orphaned Files lists it under Needs an Administrator, judged again as its scan judges what it finds.8. **Put back.** History's Put Back reads its record as a request, not as a fact: an item returns only from areal Trash, only to a place the guard allows, only when it is the item that went (`TrashedItem.identity`,its inode and birth time, read in the Trash as it landed and asked again of the item Put Back holds open),and, through the helper, only if the helper's own ledger says it moved that very item from that very place.- An app that comes back gets its Dock icon back where it was.+ An app that comes back gets its Dock icon back where it was, a launch job the move stopped starts again as the+ file back in place declares it, and the apps put back are made known to Launch Services again only once every+ item is back.## What keeps data safeA handful of ideas carry most of the weight. Each is enforced in one place and tested there.-- **The Trash, never deletion.** Nothing in Peel deletes anything of the user's; what it deletes outright holds+- **The Trash, never deletion.** Nothing in Peel deletes anything of the user's. What it deletes outright holdsnothing of theirs: the empty placeholder `TrashMover` makes to hold a name on a disk that cannot rename without- replacing (exFAT), when the move it was made for fails, the folder `PreferenceBackup` makes for a reset's saved- settings, when saving fails while it is still empty, and the empty file cfprefsd writes back where a moved settings- file was when `PreferenceCleanup` forgets a domain it still holds, which would keep History from putting that file- back. Its list of refusals goes to the Trash when `peel history --refused --clear` asks. Four- actions can't be undone by History, and each says so where it is confirmed: Homebrew's own uninstall and clean up,- resetting an app's privacy permissions, and Force Quit for an app that is still open 10 seconds after Peel asked it to- quit (`QuitBeforeRemoving`). Forgetting a preference domain happens only once its file is in the Trash, so putting the- file back undoes it, or, when saved settings are put back, once the settings in use are saved as a copy of their own- (`PreferenceBackup`). Every `brew` call runs without Homebrew's automatic cleanup (`HOMEBREW_NO_INSTALL_CLEANUP`), so- an upgrade never deletes on its own; when a `brew.env` file of the user's turns that back on (`Homebrew.overrides()`,- from `brew config`), the Homebrew page says so and leaves upgrades to Terminal.+ replacing (exFAT), when the move it was made for fails; the folder `PreferenceBackup` makes for a reset's saved+ settings, when saving fails while it is still empty; and the empty file cfprefsd writes back where a moved+ settings file was when `PreferenceCleanup` forgets a domain it still holds, which would keep History from putting+ that file back. Peel's list of refusals goes to the Trash when `peel history --refused --clear` asks. Four+ actions can't be undone by History, and each says so where it is confirmed: Homebrew's own uninstall and+ cleanups, resetting an app's privacy permissions, and Force Quit for an app that is still open 10 seconds after+ Peel asked it to quit (`QuitBeforeRemoving`). Moving Mullvad VPN, Citrix Workspace, or TeamViewer starts that+ app's own uninstaller, which deletes what History can't bring back, and Peel says so before it moves them+ (`UninstallsItself`). Forgetting a preference domain happens only once its file is in the Trash, so putting the+ file back undoes it, or, when saved settings are put back, once the settings in use are saved as a copy of their+ own (`PreferenceBackup`). Every `brew` call runs without Homebrew's automatic cleanup+ (`HOMEBREW_NO_INSTALL_CLEANUP`), so an upgrade never deletes on its own; when a `brew.env` file of the user's+ turns that back on (`Homebrew.overrides()`, from `brew config`), the Homebrew page says so and leaves upgrades to+ Terminal.- **One guard.** `RemovalGuard` decides, for the app and the `peel` tool alike, whether an item may move. Itslist of what nothing can bring back lives in `ProtectedData`, in PeelPrivileged, so the helper applies thesame list without asking the app. The guard judges the item and not the spelling of its path: each rule is@@ -169,7 +198,10 @@ A handful of ideas carry most of the weight. Each is enforced in one place and tby path (in the home, the keychains, and the folders that stay themselves) are known by device and inode aswell, wherever a link leads them. It finds those places without opening them, since opening a folder insideanother app's container makes macOS ask for that app's data. A path is read name by name (`PathComponents`),- never as text, since a slash and a combining mark after it are one Swift `Character`.+ never as text, since a slash and a combining mark after it are one Swift `Character`. The guard also refuses+ anything that syncs to other devices (`SyncedFolders`): what iCloud or a File Provider keeps, and what sits in a+ folder Syncthing, Resilio Sync, Synology Drive Client, or MEGA keeps in step, since the Trash would take it from+ those devices too.- **Exclusions everywhere.** The user's exclusions reach every scanner, so an excluded item never appears, anda folder with something excluded inside is never moved.- **Unknown stays unknown.** A size that couldn't be measured, a list a tool didn't give, an answer that didn't@@ -182,11 +214,19 @@ A handful of ideas carry most of the weight. Each is enforced in one place and tThe helper (`com.tuguidragos.Peel.Helper`) is registered with `SMAppService` when the user asks for it, andmacOS asks the user to approve it once. It talks to the app over XPC.+- Only an administrator installs, repairs, or uninstalls it. macOS lets any account unregister a daemon, so the app+ asks again at that moment whether this account is an administrator (`PrivilegedHelper.changeAsAnAdministrator`),+ and Remove Peel, from an account that isn't, leaves the helper and Peel where they are.- It answers administrators only, asked when a connection opens and again with each message, and it acceptsonly a copy of Peel signed by the same team and no older a build than itself, checked when a connection opensand for every message after it.A released helper refuses a build that can be debugged, and launchd starts the helper only as the team's ownbuild of it (`SpawnConstraint` in its launchd property list).+- Its calls are declared by `PeelHelperProtocol`, in+ `Packages/PeelCore/Sources/PeelPrivileged/HelperInterface.swift`, and the app reaches them through+ `PrivilegedHelper`, which first asks whether the helper answers, within 15 seconds, and waits at most 120 seconds+ for a request. Every request passes `HelperRequest.admit` before any work: the protocol version, at most 100 items,+ no path longer than macOS allows, and then the account behind it.- It does three things: moves items to the Trash, puts them back, and starts, stops, enables, or disables anothervendor's launch daemon, never one macOS ships and never itself. When Peel is removed, it also moves its own ledgerto the Trash.@@ -199,25 +239,28 @@ macOS asks the user to approve it once. It talks to the app over XPC.`F_FULLFSYNC`), and History is on the drive before the journal lets a removal's items go. While the ledger can't beread it moves nothing, and one it can't make sense of is kept under another name (`DamagedFile`), never writtenover.-- An update needs nothing from the person. launchd starts `Contents/MacOS/PeelHelper` from the app as it is at- that moment, under a spawn constraint that names only the team and the helper's identifier, so the next request- runs the new helper, and a helper still running when an update replaced its program quits as soon as it is idle- (`HelperLifetime`). That holds while the helper's identifier and its launchd property list stay the same: a- version that changes either has to register the helper again (`SMAppService.h`).+- An update needs nothing from the person, although Apple's `SMAppService.h` asks an app that changes a daemon's+ program or property list to register it again, or it may not launch. launchd starts `Contents/MacOS/PeelHelper`+ from the app as it is at that moment, under a spawn constraint that names only the team and the helper's+ identifier, so the next request runs the new helper, and a helper still running when an update replaced its+ program quits as soon as it is idle (`HelperLifetime`). That holds only while the helper's identifier and its+ launchd property list stay the same: a version that changes either has to register the helper again.- Any change to the helper means bumping `HelperIdentity.protocolVersion`, so Peel never works with a helper ofanother version.## The app-- **Pages and models.** The sidebar lists the tools. Each has its page in `Peel/Views/<Tool>/`, but for- Applications, whose views sit directly in `Peel/Views/`, and a model in `Peel/Model/` (`AppLibrary`,- `OrphanLibrary`, `DuplicateLibrary`, and so on) that owns its scan and its selection. The pages share- `RemovalRow` for a row that can be selected and `RemovalBar` for the button that moves the selection. On the- pages that free space (Orphaned Files, Space, Developer, Build Artifacts, Installers and Backups, Duplicates,- and File Search) the selection travels: what is selected on every such page the user has opened stays selected,- and Move to Trash on any of them moves it all as one removal, each page's part by its own tool with that tool's- checks (`SelectionCarrier`, over `CarriedSelection` in PeelCore).-- **Concurrency.** The app target runs on the main actor by default. Heavy work lives in PeelCore and is marked+- **Pages and models.** The sidebar lists the tools (`ToolSidebar`, over `Tool`, in `Peel/Navigation/` with the+ menu commands and the App Shortcuts). Each tool has its views in `Peel/Views/<Tool>/`, named for its case of+ `Tool`, and a model in `Peel/Model/` (`AppLibrary`, `OrphanLibrary`, `DuplicateLibrary`, and so on) that owns+ its scan and its selection. Applications' views sit directly in `Peel/Views/`, beside the views every page+ shares: `RemovalRow` for a row that can be selected and `RemovalBar` for the button that moves the selection. On+ the pages that free space (Orphaned Files, Space, Developer, Build Artifacts, Installers and Backups,+ Duplicates, and File Search) the selection travels: what is selected on every such page the user has opened+ stays selected, and Move to Trash on any of them moves it all as one removal, each page's part by its own tool+ with that tool's checks (`SelectionCarrier`, over `CarriedSelection` in PeelCore).+- **Concurrency.** Everything builds with Swift 6.4 in the Swift 6 language mode (Xcode 27). The app target runs on+ the main actor by default (`SWIFT_DEFAULT_ACTOR_ISOLATION`). Heavy work lives in PeelCore and is marked`@concurrent`, so it runs off the main actor.- **Two looks.** Home, the menu bar panel, and About use Peel's own look, a paper sheet with stickers. Everyother page reads as macOS: system type, forms, native controls, color on symbols rather than on words, and Liquid@@ -226,30 +269,47 @@ macOS asks the user to approve it once. It talks to the app over XPC.languages. The key is the English, so changing a sentence means translating it again; the tests fail untilevery language has it. PeelCore never translates: it returns plain English, and the app turns knownsentences into the reader's language (`FixedSentence`).-- **Terminal.** The Terminal page writes Terminal's own preferences, and only files of Peel's own for the rest:+- **Terminal.** The Terminal page writes Terminal's own preferences, makes `~/.hushlogin`, and changes Git's+ settings through `git config --global`; everything else it writes is a file of Peel's own:- Peel's themes are profiles of their own, each built by `TerminalProfile` from Apple's Clear Dark, beside theprofile Terminal opens with and two keys in the Peel theme in use (`TerminalOption`). `TerminalThemeLedger`keeps what Terminal used before and the fingerprint of each profile Peel wrote, so Put Back takes away only aprofile still as Peel wrote it. Peel writes these only while Terminal is closed: an open Terminal does not reada change made outside it, and writes its own settings over it.- - For the "Last login" line, Peel makes an empty `~/.hushlogin` (`HushLogin`), which turning it off moves to the- Trash. The switch that keeps Terminal from reopening its windows is a tweak (`TweakCatalog.terminalWindows`)- and sets Terminal's `NSQuitAlwaysKeepsWindows` at once, since Terminal reads it only when it quits.+ - To hide the "Last login" line Terminal prints, Peel makes an empty `~/.hushlogin` (`HushLogin`), which turning+ the switch off moves to the Trash. The switch that keeps Terminal from reopening its windows is a tweak+ (`TweakCatalog.terminalWindows`) and sets Terminal's `NSQuitAlwaysKeepsWindows` at once, since Terminal reads+ it only when it quits.- The Shell and SSH tabs write only files of Peel's own in its folder, `Terminal/zshrc` (`ShellFile`, with theprompt from `Prompt`) and `Terminal/ssh_config` (`SSHFile`), which zsh and ssh read through lines the personadds: Peel never edits `~/.zshrc` or `~/.ssh/config`.- The Git tab changes Git's settings only through `git config --global` (`GitConfig`), and `GitLedger` keeps what- each key held before Peel set it, so turning a setting off puts that back, while a setting the person made goes- back to Git's default.+ each key held before Peel set it, so turning a setting off puts that back, leaves a value the person changed+ since as it is, and returns a setting the person made themselves to Git's default.- A setting is offered only when the tool on the Mac knows it: zsh lists its options and functions(`ZshRequirements`), Git its keys (`git help --config`), and ssh accepts the options on its own command line.The Tools tab installs nothing: `TerminalTool` gives each tool's Homebrew formulae and the lines itsdocumentation gives, and Homebrew is asked whether it still offers them.- **Peel's own updates.** Sparkle, built from its source by `Scripts/build_sparkle.sh`, reads Peel's signed feed- on GitHub (`PeelUpdater`) and installs a new version only when the person chooses it, once the update is signed- with Peel's update key. What it may do is set in the Info.plist, the one place Sparkle reads its security+ on GitHub (`PeelUpdater`) and installs a new version only when the person chooses it, once the feed and the disk+ image it offers are signed with Peel's update key. For a change of key, Sparkle keeps a second way: a disk image+ signed with Peel's Developer ID passes when the key's signature does not, and a feed whose signature has kept+ failing for 20 days is read anyway, without its release notes or its critical mark. So the update key, the+ Developer ID, and the account that publishes the releases are what guard every copy. What Sparkle may do is set+ in the Info.plist (`SUFeedURL`, `SUPublicEDKey` from the project's `SPARKLE_PUBLIC_ED_KEY`, `SURequireSignedFeed`,+ `SUVerifyUpdateBeforeExtraction`, and `SUAllowsAutomaticUpdates` off), the one place Sparkle reads its securitysettings from. It asks on its own only while Check for app updates is on (`OwnUpdateCheck`), and the updateround of the other apps passes over Peel.+- **Updates of other apps.** `UpdateChecker` asks each app's own feed, or the App Store about an app from the App+ Store, and uses what Homebrew knows for an app a cask installed. Every answer that changes nothing makes the next+ check of that app wait longer, up to a week (`UpdateSchedule`), and `UpdateMemory` keeps the last answer across+ launches.+- **Orphaned Files.** `OrphanScanner` lists what no installed app claims, under the app Peel saw go when it can+ name it (`AppMemory`), and selects nothing for the person.+- **Resetting an app.** `AppReset` selects an app's settings, caches, and window state, which the app makes again+ when it next opens, and offers its website data and the data it keeps for the person without selecting them. It+ never offers the app itself, only files certainly the app's that nothing else claims, and it saves each preference+ domain first (`PreferenceBackup`): a reset whose copy fails moves nothing.- **Watching the Trash.** `TrashMonitor` notices an app the user moves to the Trash: the home's, and the Trash ofeach other disk Peel lists apps on (`VolumeTrashes`), where an app thrown away from that disk lands. `TrashService`tells it about Peel's own moves (`OwnTrashMoves`), by where each item landed, so Peel never offers to clean up@@ -282,40 +342,46 @@ where a Homebrew install takes them from.| `~/Library/Application Support/Peel/refusals.json` | What Peel was asked to move and refused, and why. || `~/Library/Application Support/Peel/totals.json` | The totals Home and the menu bar panel show: what the app and `peel` moved since Peel was installed. || `~/Library/Application Support/Peel/exclusions.json` | The user's exclusions. |-| `~/Library/Application Support/Peel/Preference Backups/` | The settings Peel saved before resetting an app. |+| `~/Library/Application Support/Peel/Preference Backups/` | The settings Peel saved before resetting an app, and before putting a saved copy back. || `~/Library/Application Support/Peel/digests.bin` | What Duplicates already read, so an unchanged file isn't read again. |-| `~/Library/Application Support/Peel/apps.json`, `teams.json` | What Peel remembers about apps and their signing teams between launches. |+| `~/Library/Application Support/Peel/apps.json` | The apps Peel has seen, kept once they are gone, so Orphaned Files can name what they left (`AppMemory`). |+| `~/Library/Application Support/Peel/teams.json` | Which team signs each app, so a change of signer can be told (`TeamRegistry`). || `~/Library/Application Support/Peel/orphan-owners.json` | The orphaned files the user said belong to an installed app. |-| `~/Library/Application Support/Peel/left-for-an-administrator.json` | What an uninstall left that only an administrator can move, so Orphaned Files lists it once the app is gone. |+| `~/Library/Application Support/Peel/left-for-an-administrator.json` | What an uninstall left that only an administrator can move, from a place the helper doesn't serve, so Orphaned Files lists it under Needs an Administrator once the app is gone. || `~/Library/Application Support/Peel/dock-tiles.json` | The Dock icons an uninstall took out, and where each was, so History puts them back with their app. || `~/Library/Application Support/Peel/app-folders.json` | The folders the user chose for Peel to look for apps in, beside the Applications folders. || `~/Library/Application Support/Peel/homebrew.json` | The `brew` the user chose for a Homebrew in a folder of its own, which the app and `peel` run. || `~/Library/Application Support/Peel/Terminal/zshrc`, `Terminal/ssh_config` | The shell and ssh settings chosen on the Terminal page, which zsh and ssh read through the lines the user adds. || `~/Library/Application Support/Peel/release-notes.json` | What is new in each update that waits, as the app's own sources say it, so its page shows it with no connection. |-| `~/Library/Application Support/Peel/` `*.lock` | The lock beside each file the app and `peel` both change, so a read and the write after it are one step (`FileLock`). |-| `~/Library/Application Support/Peel/` `*-damaged-*` | A file of Peel's that could not be read, set aside under another name so the next save doesn't overwrite it (`DamagedFile`). |+| `~/Library/Application Support/Peel/*.lock` | The lock beside each file the app and `peel` both change, so a read and the write after it are one step (`FileLock`). |+| `~/Library/Application Support/Peel/*-damaged-*` | A file of Peel's that could not be read, set aside under another name so the next save doesn't overwrite it (`DamagedFile`). || `~/Library/Logs/Peel/<name>` | What the app measured while `PEEL_MEASURE=<name>` was set. || `~/Library/Caches/com.tuguidragos.Peel/org.sparkle-project.Sparkle/` | Sparkle's download of an update the user chose to install, and what it prepares to install it. |+| `~/Library/Caches/com.tuguidragos.Peel/Cache.db`, `fsCachedData/`, `~/Library/HTTPStorages/com.tuguidragos.Peel/`, `~/Library/HTTPStorages/com.tuguidragos.Peel.binarycookies` | What macOS's networking keeps for Sparkle's requests: a cache of their answers, what servers said about reaching them again, and a store of cookies that stays empty, since Peel accepts none (`PeelUpdater`). || `/private/var/db/com.tuguidragos.Peel.Helper/` | The helper's ledger of what it moved. || Peel's preferences | Settings, the day Peel was installed, what each tool found the last time it looked, the last answer of each update check, when Sparkle last looked for a new Peel, and what the tweaks, Terminal, and Git held before Peel changed them, so turning a setting off puts that back. |-| Outside Peel's own files | `~/.hushlogin` from the Terminal page; the Dock's two lists of icons (`persistent-apps` and `recent-apps`, through `DockTiles`); the settings Tweaks changes; Terminal's profiles and options; Git's settings; and the Time Machine mark on each folder Build Artifacts leaves out of backups. |+| Outside Peel's own files | `~/.hushlogin` from the Terminal page; the Dock's two lists of icons (`persistent-apps` and `recent-apps`, through `DockTiles`); the settings Tweaks changes; Terminal's profiles and options; Git's settings; the Time Machine mark on each folder Build Artifacts leaves out of backups; and the background items disabled on the Background Items page, which launchd keeps disabled across restarts. |Remove Peel, in Settings, takes all of Peel's own files to the Trash but `Terminal/`, the settings zsh and ssh readthrough the user's own lines (`SelfRemoval`), gathered first into one folder named Peel so the Trash shows one item,-and leaves what it changed outside them as it is. The helper moves its own ledger there, since nothing else can,-just before Peel unregisters it, and before that the link to the `peel` command when only an administrator can move-it (`Uninstallation.unreviewedLinks`): it leads into Peel until Peel has moved, and the helper takes such a link-only when it leads to the tool of the Peel it runs from (`PrivilegedPathPolicy`'s `ownTool`). Both are asked of the-helper only once it has answered (`SelfRemoval.beforeTheHelperGoes`): one that cannot start would keep each request-waiting, so then both stay, and Remove Peel names them with what stayed. It is the only way-Peel removes itself: Peel's own page in Applications, and Peel among several chosen apps, list it and select nothing-of it (`Uninstallation.isPeel`), and `peel uninstall` refuses it. For a copy Homebrew installed, Settings shows-`brew uninstall --zap` in its place (`SettingsView`).+and leaves what it changed outside them as it is. It takes no step while Peel's own move would be refused. The+helper moves its own ledger there, since nothing else can, just before Peel unregisters it, and before that the+link to the `peel` command when only an administrator can move it (`Uninstallation.unreviewedLinks`): it leads into+Peel until Peel has moved, and the helper takes such a link only when it leads to the tool of the Peel it runs from+(`PrivilegedPathPolicy`'s `ownTool`). Both are asked of the helper only once it has answered+(`SelfRemoval.beforeTheHelperGoes`): one that cannot start would keep each request waiting, so then both stay, and+Remove Peel names them with what stayed. Peel's login item is unregistered before Peel moves, and once Peel is in+the Trash, Remove Peel ends the Finder extension still running from it (`SelfRemoval.endExtensions`) and takes+Peel's icon out of the Dock without remembering it. It is the only way Peel removes itself: Peel's own page in+Applications, and Peel among several chosen apps, list it and select nothing of it (`RemovedElsewhere.byRemovePeel`),+and `peel uninstall` refuses it. For a copy Homebrew installed, Settings shows `brew uninstall --zap --cask peel` in+its place (`SettingsView`), whose zap takes Peel's whole folder, `Terminal/` included.## Testing-- `swift test --package-path Packages/PeelCore` runs the whole suite. Tests use temporary folders- (`TemporaryDirectory`) and never touch the user's own state.+- `swift test --package-path Packages/PeelCore -Xswiftc -warnings-as-errors` runs the whole suite, held to+ warnings as errors as the app is. Tests use temporary folders (`TemporaryDirectory`) and never touch the user's+ own state.- Scanners take their slow parts as parameters (how to measure a folder, how to run a tool), so a test canstand in for a folder that never answers or a tool that fails.- The `Attack*Tests` files try to get past the safety rules on purpose: another case, a link, a `/.vol` path, a@@ -324,42 +390,53 @@ of it (`Uninstallation.isPeel`), and `peel uninstall` refuses it. For a copy Hom(`PEEL_TEST_THIS_MAC=1`).- `PeelUITests` runs Xcode's accessibility audit on every page, About, Settings, and the menu bar panel, in bothappearances. It drives the pointer and quits a Peel that is open, so it has a scheme of its own and runs by hand- before a release; the checks only build it.+ before a release; the Checks workflow only builds it.- `Scripts/sync_localizations.py --check` fails when a string catalog is behind the code, and`Scripts/generate_manual.py --check` when the manual page of `peel` is behind the tool.+- The Checks workflow (`.github/workflows/checks.yml`) runs on every push and pull request: the suite, Sparkle's+ build, the app in Debug and in Release with every binary's three slices and its class data signed, the+ accessibility audit's build, and both `--check` scripts.## Releases`Scripts/release.sh` builds a Release copy, signs it with a Developer ID, has Apple notarize it, staples the ticket,checks the result with Gatekeeper, and prints the path and SHA-256 of `Peel-<version>.dmg`, for people, and of-`Peel-<version>.zip`, for Homebrew. The disk image is signed, notarized, and stapled too. It opens on a window of-the album's paper with an arc from Peel to Applications, which `Scripts/make_dmg.sh` lays out with dmgbuild, run by-uv, so nothing drives Finder; the background carries no words, since Finder writes the names in each Mac's language.-It starts only from a committed tree whose package tests pass with warnings as errors, builds Sparkle from its source,-and refuses a build in which any of the four programs can be debugged, in which any program, Sparkle's included, is-not signed with Peel's Developer ID, the hardened runtime, and a secure timestamp, lacks any of its arm64e, arm64, and-x86_64 slices, or has its class data unsigned, in which Sparkle carries its XPC services, in which a language is-missing, or which `syspolicy_check distribution` says macOS would not open.+`Peel-<version>.zip`, for Homebrew, and the path of its update feed. The disk image is signed, notarized, and+stapled too. It opens on a window of the album's paper with an arc from Peel to Applications, which+`Scripts/make_dmg.sh` lays out with dmgbuild, run by uv, so nothing drives Finder; the background carries no words,+since Finder writes the names in each Mac's language. It starts only from a committed tree whose package tests pass+with warnings as errors, builds Sparkle from its source, and refuses a build:++- in which any program, Sparkle's included, can be debugged, or is not signed with Peel's Developer ID, the hardened+ runtime, and a secure timestamp;+- in which any program or library lacks its arm64e, arm64, or x86_64 slice, or has its class data unsigned;+- in which Sparkle carries its XPC services, or a language is missing;+- or which `syspolicy_check distribution` says macOS would not open.Last, it makes `appcast.xml`, the update feed every copy of Peel reads from the latest release: Sparkle's`generate_appcast` offers the disk image at the release's download address, signs it and the feed with the update keyin the Keychain, marks the update critical, so Sparkle's window offers no Skip This Version, and embeds the changelog's-entry for the version as Markdown release notes. `Scripts/check_appcast.swift` then refuses a feed that offers more-than this one update, another version, build, or minimum macOS than the app's, a hardware requirement (which keeps an-update from every Mac without that processor), another address or length, a disk image or a feed whose signature the-app's own `SUPublicEDKey` doesn't verify, or no release notes. `generate_appcast` leaves the disk image unsigned, with-only a warning, when the app inside names another key, and such a feed would fail every update.+entry for the version as Markdown release notes. `Scripts/check_appcast.swift` then refuses a feed that offers+anything but this one update, another version, build, or minimum macOS than the app's, an update that isn't critical+from every version, a hardware requirement (which keeps an update from every Mac without that processor), another+address or length, a disk image or a feed whose signature the app's own `SUPublicEDKey` doesn't verify, or no release+notes. `generate_appcast` leaves the disk image unsigned, with only a warning, when the app inside names another key,+and such a feed would fail every update.++The script publishes nothing. The release on GitHub, `v<version>`, carries the disk image, the zip, and+`appcast.xml`, and every copy reads the feed of the latest release only, so the feed goes up with the files it+points to, in a release that is neither a draft nor a prerelease.Before it runs, the version is set by hand in each of the project's targets: `MARKETING_VERSION`, and-`CURRENT_PROJECT_VERSION`, the build every program carries, written as the year, month, and day it was set (261013),-with the release's entry in CHANGELOG.md. The script needs a Developer ID Application certificate in the keychain, a-notary profile stored once with `xcrun notarytool store-credentials` (it uses the one named Peel unless given another),-the update key in the Keychain under the account peel, made once with Sparkle's `generate_keys --account peel`, and-uv (`brew install uv`), and it refuses to start without uv.+`CURRENT_PROJECT_VERSION`, the build every program carries, written as the year, month, and day it was set, such as+261013 for 1.1.0, with the release's entry in CHANGELOG.md. The script needs a Developer ID Application certificate+in the keychain, a notary profile stored once with `xcrun notarytool store-credentials` (it uses the one named Peel+unless given another), the update key in the Keychain under the account peel, made once with Sparkle's+`generate_keys --account peel`, and uv (`brew install uv`), and it refuses to start without uv.A Release build of every program has pointer authentication (`ENABLE_POINTER_AUTHENTICATION`, an arm64e slice-beside arm64 and x86_64), and the helper the rest of Enhanced Security too. Xcode gives the Swift packages only the-settings of the command line, so a Release build passes that setting there as well, with+beside arm64 and x86_64), and the helper, in every build, the rest of Enhanced Security too. Xcode gives the Swift+packages only the settings of the command line, so a Release build passes that setting there as well, with`MACOSX_DEPLOYMENT_TARGET=26.0`: a package that names no platform, such as swift-argument-parser, would otherwisebe built for an older macOS with its class data unsigned, and the linker would then leave the class data of thewhole `peel` tool unsigned. `release.sh` and the Checks workflow pass both, and Xcode's own Archive, which cannot,diff --git a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swiftindex f17d7d92..ac4fdd70 100644--- a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift+++ b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift@@ -44,6 +44,9 @@ struct DocumentationTests {("SAFETY.md", "keeps the most recent \(records) items"),("ARCHITECTURE.md", "keeps the most recent \(records) items"),("SAFETY.md", "at most \(HelperRequest.maximumItems) items in one request"),+ ("ARCHITECTURE.md", "at most \(HelperRequest.maximumItems) items"),+ ("ARCHITECTURE.md", "answers, within \(Int(PrivilegedHelper.answerWait)) seconds"),+ ("ARCHITECTURE.md", "at most \(Int(PrivilegedHelper.requestWait)) seconds for a request"),("SAFETY.md", "quits \(idle) seconds after its last request ends"),("AGENTS.md", "still open \(patience) seconds after Peel asked it"),("ARCHITECTURE.md", "still open \(patience) seconds after Peel asked it"),diff --git a/SAFETY.md b/SAFETY.mdindex b28e33e9..e7812e1b 100644--- a/SAFETY.md+++ b/SAFETY.md@@ -143,7 +143,7 @@ That includes what `pkgutil` and Homebrew would delete:or into its gone apps, to the Trash.A removal reaches History even when something cuts it short. Quitting Peel waits until History has it, `peel`-carries on through Ctrl-C or a closed terminal until it has written History, and each item is written down the+carries on through Control-C or a closed terminal until it has written History, and each item is written down themoment it moves, so one cut short by a crash or Force Quit still reaches History, as an interrupted removal, thenext time Peel or `peel` opens it.