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.

46.6 KB
Raw Blame

Working on Peel

This file holds the rules every change to Peel follows. It is written for coding assistants, which read it before they start, and it binds the person directing one just the same: the rules don't change with who, or what, writes the code. CONTRIBUTING.md says how to propose a change, ARCHITECTURE.md how the parts fit together, and SAFETY.md what Peel protects.

Peel removes files from people's Macs. A bug here doesn't put a wrong number on a screen: it takes away something somebody wanted. That is why the rules are strict, and why none of them is a matter of taste.

How every change is made

Never change anything blindly. Every change goes through these steps, in this order, however small it looks: search, prove, and only then fix.

  1. Search. Read the code as it is now, and every caller and reader of what the change touches: the app, the peel command, the helper, and the tests. Read the current official documentation for every fact the change relies on: Apple's documentation, the SDK's headers (xcrun --show-sdk-path), the man page on this Mac, or the tool's own source at a named commit. Never work from memory: an API you remember may have changed.
  2. Prove the problem before changing anything. Show on a real Mac that it happens, and why: a measurement, a probe that is thrown away afterward, the app showing it, or a test that fails for the reason given. A suspicion that can't be proved is reported as one, and nothing changes for it.
  3. Write the test first. It fails without the change, for the reason the change gives, and passes with it. Check that it really catches the problem: put the old code back, watch it fail, and restore the fix. If it still passes, first make sure the old code really went back, then look for another layer that stops the problem before it, and give each layer a test of its own.
  4. Fix the cause, in the type or the rule where the fact belongs. No workaround, no special case keyed by a name, no table on the side. A defect found on the way is fixed the same way, with its own test.
  5. Follow the change along its whole path, from where it starts to where it shows, and check every step of it carefully. Find every function the change touches and every function that touches what it changed: callers, readers, overrides, observers, the app, peel, the helper, and the tests. Check that none of them works worse because of the change, and follow each one you find the same way, along its own path, until nothing that depends on the change is left unchecked. That includes every other way Peel reaches the same thing: an app moves from its own page, from several apps' page, from Package Receipts, and through the Homebrew page, so a rule about what may move an app is asked on each of them. Measure what the change adds where it runs often, for each item a scan walks or each line of a file it reads, on a large case as well as a small one.
  6. Build and test after every change, not only at the end: the whole package suite with warnings as errors, the app's Debug build, and the app's own tests, which run inside Peel (CONTRIBUTING.md has the commands). Before proposing the change, run what the Checks workflow runs too: the Release build with ENABLE_POINTER_AUTHENTICATION=YES and MACOSX_DEPLOYMENT_TARGET=26.0, since some of Swift's checks run only on optimized code, the accessibility audit's build, and python3 Scripts/sync_localizations.py --check and python3 Scripts/generate_manual.py --check.
  7. Check it where it shows, live: open the page the change touches, or run the peel command it changes, and see the result. Never on anyone's real files: tests use a temporary home, and a check that moves files runs on a disk image made for it. A Debug build is Peel to macOS: it shares the installed Peel's settings, History, exclusions, and helper record, and what it moves is yours. Check a removal on files made for it, such as a folder on a disk image given to peel duplicates or peel projects with --dry-run first, and never run Remove Peel in it. A made-up home (CFFIXED_USER_HOME) moves only the home folder: the temporary and cache folders macOS gives the account (confstr), Spotlight's home scope, and the Trash stay the real ones. Developer and Space read those folders and File Search that scope, so a check there selects and never moves, and what a check does move lands in your own Trash.
  8. Leave nothing behind: no probe, no debugging output, and nothing the change left unused.
  9. Say exactly what happened. Report a failing test with its output, a step you skipped as skipped, and what you couldn't prove as unproved. If something can't be checked on your Mac, say what and why in the pull request, and the maintainer will check it.

When you're stuck, read before you try. Don't guess at how macOS, Swift, or a tool behaves, and don't change Peel's code to see whether something helps. Read the current official documentation for the version Peel runs on: Apple's documentation and release notes, the SDK's headers, the man page on this Mac, or the tool's own source at a named commit. Rely on what the source itself says, never on a summary of it, and prove it on a Mac with a probe before a fix rests on it.

A choice about what Peel does for people, what it selects, what it says, or how it looks, is the maintainer's. Propose it with your reasons; don't make it on the way.

What Peel tells the person to do is documented or proved. A place in System Settings, a menu, or a command Peel sends someone to is one that Apple's documentation, the man page, or the tool's own documentation gives, or one shown on a Mac. Never a guess at where macOS keeps a control: a step that leads nowhere leaves the person stuck.

What must never break

Tests enforce most of these rules, and the rest (QuitGuard, PeelUpdater) live in the app, where a change is checked by hand. If a change makes one of them fail, the rule is right and the change is wrong.

  • Nothing of the user's is ever deleted for good. Every removal goes to the Trash through TrashService and is recorded, so History can put it back. In the app it runs inside QuitGuard.shared.run from its first move until History has it, and so does a Put Back, so quitting waits for them. Peel deletes outright only five things, none of them the user's: the empty placeholder TrashMover makes to hold a name on a disk that can't rename without replacing (exFAT), once the move it was made for has failed; the folder PreferenceBackup makes for a reset's saved settings, when saving fails while it is still empty; the folders Put Back makes on the way back (DirectoryHandle.child(_:makingIfMissing:)), when the item then stays in the Trash and each is still the empty folder it made; the folder Remove Peel gathers its own files in (SelfRemoval), once they are back out of it because its move was refused; and the empty file cfprefsd writes back where a moved settings file was, when PreferenceCleanup forgets a domain cfprefsd still holds. Peel's list of refusals, with any copy of it set aside because it couldn't be read, goes to the Trash when peel history --refused --clear asks.
  • What History can't undo says so where the person confirms it: Homebrew's own uninstall and its 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. defaults delete for an app's preferences runs only once their file is in the Trash, and a reset exports the domain first, so putting the file back undoes it; putting saved settings back clears a domain only once it has been saved as a copy of its own, and asks first. Every brew call runs with HOMEBREW_NO_INSTALL_CLEANUP, so an upgrade never cleans up on its own, and when a brew.env file turns that back on (Homebrew.overrides()), Peel leaves upgrades to Terminal.
  • RemovalGuard refuses what nothing can bring back, in every account on the Mac: iCloud Drive and other cloud storage, the folders another app keeps in step with other devices (SyncedFolders), the home's Trash and every disk's, keychains, ~/.ssh, ~/.gnupg, and the other keys and credentials ProtectedData.homeFolders and ProtectedData.homeKeys name, the wallet keys ProtectedData.walletKeys names, a browser profile holding a wallet extension's vault, Mail, Messages, Safari, Contacts, Calendars, and Apple's other stores of personal data, every group container of Apple's own, work not saved yet, photo, music, and video libraries, a sandboxed app's Documents, the folders every account starts with, and work a tool keeps only in a cache folder. SAFETY.md lists every place. The guard judges the item, not how its path is spelled: each rule is asked of the path as written, as found on disk, and as the kernel names the item, and the places it protects are known by device and inode too. Every folder on the way to one that stays itself stays too, such as ~/Library/Audio on the way to the plug-in folders Peel searches, since moving it would take that place along (ProtectedObjects.ancestors); a browser's own data folder still goes with the browser.
  • Paths are compared name by name, never as text. A Swift String reads a slash and a combining mark after it as one Character, so hasPrefix(folder + "/") and split(separator: "/") miss a folder such a name sits in. Every "is this inside that folder" question goes through PathComponents. A path looked for in a file's text counts only where it stands whole, never inside a longer name (ShellReferences.holdsWhole).
  • Only certain and likely matches that no other installed app claims are selected for the user. Anything shared is shown and left unselected, and nothing is selected for an app that would stay.
  • What may exist nowhere else is never selected for the user. A folder with a wallet, a signing key, a password database, or a repository inside, one where an app keeps what may exist only on this Mac, or one Peel couldn't finish reading, is shown with its reason and moves only when the user selects it. peel uninstall, peel orphans --remove, and peel projects --remove pass it by, and Select All takes it only once the user has answered the question that counts what Peel doesn't recommend (SelectableRows.notRecommendedAdded). A repository can still be selected in two places, since its tool clones it again: inside Swift Package Manager's .build, which it tags as a cache (CACHEDIR.TAG), and inside a cache on the Developer page; a tag alone never makes a repository selectable (Definition.remakesItsClones).
  • The user's exclusions reach every scanner, so an excluded item never appears in the first place, but for an excluded app's jobs, which Background Items lists marked, acting on none, since that tab says what runs.
  • What a file says about itself is anyone's word. Any program can write a launch job, an app's Info.plist, or one of Peel's own records, so a program path that holds a NUL names no program, an app's name goes into a pattern only quoted, and a record Peel kept is believed only as a scan believes what it finds (LeftForAnAdministrator).
  • A folder a scan never walks into can't be chosen as the place to start one. Build Artifacts never enters a hidden folder, a Library, or a folder a tool fills, such as node_modules: what is there is a tool's own installation, and an editor's extension keeps its package.json beside the node_modules it runs with. So a folder chosen to scan that is one of those, or sits inside one, is refused like a package (ProjectArtifacts.refusal(for:)), in the app and in peel projects alike.
  • Peel never runs Git in a project, and never suggests a folder Git tracks. A project's own Git settings can name a program for Git to run (core.fsmonitor), so whether a build folder holds files Git tracks is read from the index itself, as gitformat-index(5) describes it (GitIndex), never asked of Git. A folder that holds tracked files, such as Pods kept in the repository as CocoaPods suggests, is listed with that reason and never recommended, and so is one in a repository whose index can't be read, or can't be read in time, each with its own reason.
  • Resetting an app clears its settings, never the app. It takes the app's own data only when the user selects it, needs the app to be quit, and inside a sandboxed app's container never touches Documents, Application Support, or Autosave Information.
  • A Homebrew cask counts as evidence only when it is proved, by naming the app bundle, the identifier it quits, or an installer receipt that is on this Mac. A guessed name is never believed on its own.
  • Duplicates always keep at least one copy, and refuse a file that changed since the scan.
  • An update check sends no more than PRIVACY.md says. A feed request carries Peel's name and no language, a redirect is followed only to https, the session keeps no cache or cookie a server could read back, and Apple is asked only about an app bought from the App Store (UpdatePrivacyTests). Peel's own check, through Sparkle, carries Peel's name and no language, and Peel takes no cookie (PeelUpdater).
  • No code reads macOS's privacy database. What macOS records about privacy is not API, and from macOS 27 apps can't read it, so App Management is learned from what a removal shows, on every macOS (PrivateDatabaseTests).
  • What can't be read is unknown, never empty or zero. A folder macOS won't let Peel read, or one that doesn't answer in time, has no size (FileSize answers nil) and is never taken for empty. Only a name that isn't there (lstat answering ENOENT) makes one of Peel's own files empty; anything else reads as unreadable, and while History or the exclusions can't be read, nothing moves. The guard's rules that look a level or two inside a folder answer ProtectedData.Finding, and a folder with one inside they couldn't list is refused, unless only the helper can move it, which looks inside as root. The exclusions' look for an excluded app answers nil the same way (Exclusions.appFolders(inside:)), which refuses even what the helper would move: the helper has no exclusions.

The privileged helper

PeelHelper runs as root. Treat every argument it receives as hostile, even from Peel: the app is a program on a disk that somebody may have replaced.

  • It has no shell, accepts no path outside the folders it serves, and refuses whenever it is unsure.
  • It answers an administrator, and another account only for a request carrying an administrator's approval in force (AdministratorAuthorization), asked again with each message. The account is the connection's and says nothing about which process sent a message (xpc_connection_create(3)), so no rule may rest on it for that.
  • The approval is for Apple's system.privilege.admin, never a right of Peel's own: macOS lets any process add a right that doesn't exist yet (config.add.), so another process of the account could define one as granted first.
  • It accepts only a copy of Peel signed by the same team and no older a build than itself, checked when a connection opens and for every message after it, and a released helper refuses a build that can be debugged.
  • Only an administrator changes it. macOS lets any account unregister a system daemon without asking, so every install, repair, and uninstall asks again, at that moment, whether this account is an administrator (PrivilegedHelper.changeAsAnAdministrator).
  • Every question and request goes to it from a task of its own at user-initiated quality, which makes its own connection (PrivilegedHelper.ask): XPC delivers a reply at the quality its message went out with, so a reply to a lower one waits while Peel is busy, and the wait for it ends first.
  • It never uses a path again after checking it: it opens the folder, checks the item there as the kernel names the folder (F_GETPATH), and works only through that descriptor, so a folder swapped after the check leads nowhere.
  • A rename still goes by name, so every item the helper moves passes through Staging, beside its ledger, which only root can reach (HelperLedger.whileStaging), and is checked there before it goes on; anything but the item goes back. It never renames by name out of a folder another account can write, and never takes a name with a placeholder.
  • A new operation needs PrivilegedPathPolicyTests, and any change to the helper a bump of HelperIdentity.protocolVersion, so Peel never works with a helper of another version.
  • The helper's identifier and its launchd property list stay the same from one version to the next. Updates rely on it: launchd starts the new helper by itself, and a version that changed either would have to register it again.
  • macOS keeps a background item's record by its team and bundle identifier, never its path or build, so a Debug build and a release share one record and its approval (sfltool dumpbtm lists them, without sudo but with an administrator's password). Registering again right after unregistering is refused until macOS has saved its records, a few seconds later, so PrivilegedHelper.register waits and tries again.

If you are unsure whether something belongs in the helper, it doesn't.

Tests

  • Tests run as Peel runs, on the Mac running them: the real Launch Services, the real system apps, the real disk. Nothing (a flag, a default, an environment variable) makes a test skip what Peel does. A stand-in is only for what a Mac can't do on demand, such as a folder that never answers, and for what would change the Mac itself: unless a test passes its own, TrashService's initializer for tests starts and stops no launchd job, forgets no preference domain, registers no app with Launch Services, changes no Dock, and acts as if there were no helper.
  • A test never assumes how the Mac running it is set. With Show all filename extensions on, Finder names Calculator "Calculator.app", while Peel never puts the extension in an app's name, so a test that compares Peel's names with Finder's reads Finder's as Peel does.
  • A test that fails now and then has a cause. Run the whole suite again and again until it fails, find what differed, and fix that. Never run it again until it passes, and never widen a timeout to hide it.
  • Never bound a test by the clock. In a full run a short sleep or a timer can resume seconds late, so a test waits for the thing it measures (a program's end, a file's change), and work it waits on runs at user-initiated priority rather than the default. A test that reads this Mac through a tool (pluginkit, mdfind) waits for the tool's whole answer, never the time limit the page gives it: a runner with three processors takes longer.
  • The files a test scans sit in a temporary home, never in yours, and nothing is registered with Launch Services from a test. In the package's tests that home is a TemporaryDirectory, which takes it away when the test ends, and no other test there names the temporary folder (TemporaryDirectoryTests); a test of the app removes the folder it made before it returns. An app a test expects Peel to act on is a made-up one, named under a domain kept for examples (org.example, com.example, net.example). A program a test starts from a folder of its own is a copy of /bin/cat signed ad hoc (TemporaryDirectory.runningProgram, or runningPrograms for several): macOS kills a plain copy of one of its own programs started from anywhere else, usually within a second, for breaking its launch constraints. Every copy is made before any starts, since once a program inside an app runs, macOS takes away other processes' right to write into that app. A copy is handed to the test only once it has echoed a line written to it, since until then Gatekeeper checks it where it started and ends it if the test has moved it, and it runs until the test ends it or the suite ends and its input closes: letting go of the Process ends nothing. A folder a test makes never ends in a package's extension: org.example.App is an app to macOS and to Peel, so nothing inside it is looked at as a folder's contents.
  • A test of the app writes nothing of the person's. Its preferences live in a domain of its own (MadeUpDefaults), and it never calls what writes Peel's own folder, such as AppLibrary.refresh(), which remembers the apps it read.
  • Some changes need a particular test:
    • matching: LeftoverMatcherTests, with the case the rule catches and a case it must not catch;
    • anything that decides what may be removed: a test that fails without the fix, written to get past the rule rather than to confirm it (the Attack*Tests files);
    • a wallet extension: its ID goes into BrowserWallets.swift only in the comment above its SHA-256, never as text the compiler keeps, because XProtect takes a binary carrying a few wallet IDs for a program that steals them; BrowserWalletTests checks every fingerprint against the ID above it;
    • a developer cache in DeveloperCaches.definitions: a source showing the folder is a cache, a link into a repository naming a commit and not a branch, and a DeveloperCachesTests run. Never a toolchain, the version of a tool in use, or a file holding an account or a token;
    • anything a document names or counts: the document changes in the same change. DocumentationTests looks in the code for the type each code-font name in a document starts with (RemovalLog of RemovalLog.canBeRead), so a member, a name in lowercase or in capitals, and a call's labels are checked by hand, and it holds a few numbers the documents give to the code's. TerminalThemeTests looks in TERMINAL.md for every line the Terminal page writes, CommandLineTests in Support/peel.1 for every command of peel, and DesktopWalletTests checks SAFETY.md's count of wallet places. Anything peel --help says that changes has its manual page written again with python3 Scripts/generate_manual.py after a Debug build: the Checks workflow compares the whole page.
  • Slower checks run only when asked for, and both are worth running before a release. PEEL_TEST_THIS_MAC=1 runs the tests that read this Mac rather than a fixture: with --filter SuggestedSelectionOnThisMacTests it scans every app installed on the Mac and checks that nothing Peel would select is refused or shared, and without the filter three more read this Mac's system extensions, Trash, and storage, the first of them failing on a Mac with no system extension. The PeelUITests scheme runs Xcode's accessibility audit on every page, and on a row's page of Background Items, Extensions, and Plug-ins, in light and dark, moving the pointer, typing, and quitting a Peel that is open, so it runs on a Mac nobody is using; macOS asks once for Accessibility for the test runner, and for an administrator's password each time Automation Mode turns on: xcodebuild test -project Peel.xcodeproj -scheme PeelUITests -destination "platform=macOS,arch=$(uname -m)" -derivedDataPath build/DerivedData DEVELOPMENT_TEAM=YOUR_TEAM_ID.
  • For work on Peel itself: PEEL_SNAPSHOT=<folder>, in a Debug build, renders Home, About, and the menu bar panel to PNG files in that folder, made if it isn't there, in light and dark, each also with Increase Contrast, then quits; PEEL_TERMINAL_EXPORT=<repository>/Terminal, in a Debug build, writes the themes and pictures Terminal/ holds, then quits, and a change to a theme or to the prompt preview needs it, since TerminalThemeTests compares Terminal/ with what Peel writes; PEEL_MEASURE=<name>, in every build, appends launch and frame timings to ~/Library/Logs/Peel/<name>; and PEEL_TEST_VOLUME=<folder> lets the tests use the Trash of another volume, on a disk image made for it.

Facts of macOS the code relies on

  • Finding a place asks macOS nothing; opening it can ask the person. Inside another app's container, lstat, stat, and realpath raise no question, while opening a file or listing a folder asks for access to that app's data. Code that runs without being asked, such as the guard built for every scan, finds places with PathPattern.locatedWithoutOpening and never opens them.
  • lstat on a path that ends in a slash follows a link to where it leads. A folder walk hands back folders with that slash, so paths are compared and checked through PathPattern.comparablePath, which drops it.
  • What removing a file frees is never its length: a file that may share blocks with a clone (EF_MAY_SHARE_BLOCKS) frees its private size, the bytes "not trapped inside a clone or snapshot" (getattrlist(2), ATTR_CMNEXT_PRIVATESIZE), and any other file every block it takes, since what a snapshot keeps comes back once macOS deletes the snapshot. Once iCloud has uploaded a file, the copy it keeps of it shares the file's blocks, so removing that download frees nothing. ReclaimableSpace.of measures every size Peel offers to free, and iCloud Drive says how many downloads it leaves out for that (CloudScan.sharedDownloads).
  • Settings are forgotten with defaults delete, never by deleting their file. cfprefsd keeps a domain in memory and writes it back, and defaults delete of a domain it still holds writes an empty file where the moved one was. PreferenceCleanup handles both.
  • A program's end is learned from the kernel. NSRunningApplication.isTerminated isn't always updated once an app has quit, so ProcessEnds watches the kernel's report of the process ending, set up before Peel asks the app to quit. AppKit's list of running apps still names an app for a few milliseconds after it ended, so whether a process still runs is asked of the kernel too (ProcessEnds.isRunning).
  • Only macOS removes a system extension. Finder's move of the app that carries it asks macOS to, and so does Delete Extension in System Settings, which on macOS 27 deletes a network extension even once its app is gone; a move by any other app tells macOS nothing, and macOS may still keep one Finder asked about (a running network extension stayed after a restart). So an uninstall never claims a .systemextension, an app carrying one macOS installed is left to Finder (RemovedElsewhere.byFinder), Peel names System Settings' step only where it is proved (AppExtension.systemSettingsDeletesIt), and Orphaned Files says why the copy in /Library/SystemExtensions stays (HoldBack.systemExtension, HoldBack.deletableSystemExtension).
  • skipDescendants() skips the folder last handed back. Called after a file, it skips the next folder in the same place instead, so a walk calls it only for a folder.
  • Listing a folder that a file provider keeps only in the cloud makes the provider download it (NSFileProviderReplicatedExtension.h), so every walk passes by such a folder (FileSize.isDataless).
  • Some folders are made only once. macOS doesn't make the account's crash reports folder again, and brew services start makes a service's log folder while launchd makes again only a missing log file, so Space empties such folders and never moves them (SpaceInventory.emptiedFolders, SpaceItem.keepsItsFolders).
  • An app in the Trash keeps its login items and agents. macOS starts what an app registered through ServiceManagement from the Trash at every login until the Trash is emptied, and launchctl names no program for such a job, so it isn't taken for one with nothing left to run.
  • Registering an app with Launch Services starts its extensions, which make their folders again, so a Put Back registers the apps it brings back only once every item is back.
  • Asking for an app's name or icon registers it with Launch Services. FileManager.displayName, the localizedNameKey and effectiveIconKey resource values, and IconServices register the bundle they are asked about, so Peel asks them only about an app Launch Services already knows at that place, and names or draws any other from its own files (AppInspector.displayName, AppInspector.icon(ofAppAt:)).
  • Code that can run after Peel has moved stops trusting its bundle. Peel's Finder extension can keep running from the Trash, where NSImage(resource:) traps on an asset it no longer finds, so it offers nothing once its bundle has left. Once Remove Peel has moved Peel, the main bundle still names the place it left, so the last words are read from the moved copy, and Peel ends with _exit, since the cookie policy Peel sets makes CFNetwork write its store again when the process exits normally.
  • Homebrew warns on stderr and still exits 0, and JSON with a warning after it is no longer JSON. An answer Peel reads comes from standard output alone (Homebrew.Attempt), while what the person is shown keeps both streams, in the order Homebrew wrote them.
  • Never run brew by hand with HOMEBREW_NO_INSTALL_FROM_API=1: Homebrew then clones its whole core tap, over a gigabyte. Peel sets it for one question only, whether Homebrew's copy of its definitions is on the Mac.
  • Peel never runs one of Homebrew's developer commands (those in its dev-cmd folder, brew ruby among them): the first one turns Homebrew's developer mode on for good, and brew update then moves Homebrew to the latest commit of its main branch rather than its latest release (man brew, developer).
  • What Homebrew says of versions is as new as its last check for them. While Homebrew reads its definitions from its API, as it does by default, it dates their file at every download or confirmation (api.rb), and only that date says how new they are: brew update can touch .git/FETCH_HEAD in Homebrew's repository, the mark Homebrew compares with its own day, and leave the definitions as they were. What Homebrew says counts for a day after that date, or after FETCH_HEAD for a Homebrew that reads its taps (Homebrew.lastUpdateCheck(), Homebrew.autoUpdateInterval), while an update it knows of always shows.
  • Apple's lookup is limited and lags a release. Apple limits itunes.apple.com/lookup to about 20 calls a minute, so a process asks no faster (RequestWindow), and a copy of its catalog can name an older version for hours after a release, so an answer older than an update already found counts as a check that failed.
  • A setting has layers, and Peel writes one of them. macOS reads a key from a profile first, then from the person's layer for this Mac and for every Mac, then, for an app's domain, the person's global domain, and then every account's layers, and the first that holds it wins. Peel writes the person's layer for every Mac, so a value it can't change from there shows with a lock: one set for this Mac alone, and a switch that is on only through a layer below the person's (TweakStore). defaults write with no type stores a number as text, so a number is read from its text too, as UserDefaults.double(forKey:) reads it.

Code

  • Swift 6.4 in the Swift 6 language mode, macOS 26 and later only, with no code for an older macOS. The app runs on the main actor by default, and heavy work in PeelCore is @concurrent. The project's targets build with warnings as errors, and so does the package, through its manifest (.treatAllWarnings(as: .error)), in every build; -warnings-as-errors on the command line names it again.
  • Never block on async work, and never wait in a loop. A semaphore parks one of the few threads Swift's tasks run on, and a canceled task refuses to sleep, so a sleeping loop spins: a wait is a continuation woken once, by the answer or by a timer, as FileSize and SlowRead wait. A timer that ends a wait runs at user-initiated quality (Subprocess.timers, PrivilegedHelper.timers): at utility quality it waits behind other utility work and fires seconds late on a busy Mac.
  • An object kept only by a weak reference is kept alive on purpose. Swift may release an object after its last use, and an open panel holds its delegate weakly, so the panel's delegate is kept with extendLifetime until the panel closes (ScreenshotFolderPanel). Only an optimized build reports the mistake.
  • Small, focused files, and code that reads like the code around it. A dependency only when nothing else will do. A Swift package's version is pinned twice, in Packages/PeelCore/Package.resolved and in the app's project, so a new version goes into both (PackageResolvedTests); Sparkle is built at the version and commit Scripts/build_sparkle.sh names. Dependabot proposes new versions of the GitHub Actions only, so both are updated by hand.
  • Scripts run in zsh: an unquoted variable isn't split into words, a pattern that matches nothing stops the line, and a word that begins with = names a command.
  • Few comments, written for people. Say what the code can't: what a declaration is for, why a rule exists, and which documented behavior of macOS forced a workaround, with its public source. No history and no notes from a session: a fixed bug belongs in the commit message. Code, comments, tests, and documents speak about Peel, never about who or what wrote them.
  • Lines within 120 columns, code and comments alike. A string is never split to fit: LineLengthTests measures each line of Swift without its strings, and each line of a shell, Python, or workflow file in Scripts/, Logo/, and .github/workflows/ as it is written.
  • No dead code. Whatever a change leaves unused goes in the same change.

macOS 26 and macOS 27

Peel runs on macOS 26 and later, and the two versions are treated differently in one way only.

  • A fix is for every version. A bug in what Peel does, whether in what it finds, selects, moves, refuses, or says, or a crash, is fixed once for macOS 26 and 27 alike, with no if #available.
  • A change to how Peel looks is for macOS 27 alone. How Peel looks and lays out on macOS 26 is settled, so a visual change goes in the macOS 27 branch of an if #available(macOS 27, *), and the macOS 26 branch keeps exactly the code it had. Before committing, read the diff and confirm that no line that runs on macOS 26 changed.
  • A visual bug whose cause holds on both versions is fixed on both, such as one that follows from a documented SwiftUI or AppKit rule, and the commit message says why the cause holds on both.

The interface

  • It follows Liquid Glass. The sticker album look belongs to Home, the menu bar panel, and About only; every other screen reads as macOS, with system type, Form and Section, and native controls. Icons are SF Symbols, and the logo comes only from Logo/, but for the face at the head of the sidebar, which draws the logo's shape in code so it can move (Face in PeelFace.swift): a change to the logo's shape changes those numbers too. A Debug build wears PeelDebug.icon, which only the Debug configurations name: a blueprint of Peel.icon drawn by blueprint, and drawn again whenever Peel.icon changes: blueprint Logo/Peel.icon --no-open -o Logo/PeelDebug.icon --color "#FFB25E,#FF9933,#F07A10" --badge DEV.
  • Everything can be used without a pointer. VoiceOver, Voice Control, and Switch Control can press every switch, named by its row's title: a row's switch is RowSwitch, whose label on macOS 27 is empty rather than hidden, since a hidden label leaves AppKit's own switch outside the accessibility tree, and which on macOS 26 hides its label and carries an accessibilityRepresentation; it gives its row's title the room first. Every control is at least 20 by 20 points, and text takes the system's styles by role, so it follows the system's text size.
  • Words take no color of their own outside Home, the menu bar panel, and About: orange, green, red, blue, or the accent color read under the 4.5:1 text needs on a light background. The color goes on a symbol beside the words, which keep the style of the text around them: StatusLabel for a warning or a state, a Badge's tint, and a note's caution.
  • A page's buttons follow one rule: they go in PageActions, under its last group at the right, with no box and no symbol, the main action last, laid out by ActionRow, which takes a second line at the right when a language's words leave no room, so never lay such a row out by hand. What concerns one row sits at that row's right end in an HStack, ShowInFinderButton on the row that says where the item is, and a section heading with nothing under it holds its button through HeadingWithActions. Adding to and removing from a list are + and - at its foot (ListEditingButtons). One button a page is prominent. A sheet's footer stays on the right, and buttons under a title stay in a FlowLayout.
  • Rows of a long list stay cheap to build. A checkbox in a row is NativeCheckbox beside the item, with checkboxTitleLine() on the first line of its title and checkboxTitle() on the title, rather than a checkbox Toggle whose label is the row; Duplicates' rows keep their Toggle, where the AppKit checkbox costs as much. A button in a row takes RowButtonStyle or .borderless, and the ForEach that repeats rows hides their separators, never a row its own. A Label beside a row's title pulls the row's separator under its own words, so a status or a tag sits in LeavesRowSeparatorAlone, as StatusLabel and Badge do.
  • A binding made in a page's body reads its value there. A SwiftUI Binding holds the value it was made with, so Bindable(plan).option written in a page's body makes the whole page depend on the option: every click runs the page's body again, and a List measures every visible row again. Make such a binding inside a small view of its own, as AppRemovalOptions and BulkRemovalOptions do. Prove a cost like this by counting how often a body runs, with a probe thrown away afterward: the time of one click changes with what the list shows.
  • A hosted AppKit view changes a value accessibility watches outside SwiftUI's update. A button's state set in updateNSView posts a notification, and AppKit then reads the row's elements from the view graph being updated: with a client watching the app and the rows read once, SwiftUI goes round in a cycle, at times for good. Keep the change for the view's next layout, as NativeCheckbox.Host does, which comes before the next frame.
  • A Group hands its modifiers to its children, so a .task on a Group that stays empty until the task loads something never runs: a list whose being empty decides whether its view exists is loaded by a model, or by a view that always exists (SavedSettings).
  • task(id:) runs again only when its id changes. A fact a page shows beside a scan is read in the model's refresh, or the task's id carries a count of scans (BackgroundItemLibrary's scans, RemovalHistoryStore's reloads); otherwise Rescan and Reload leave it as it was.
  • A frame with only a maximum height keeps any larger height it is offered, as Apple's documentation of frame says, so a popover or a Settings tab that has to shrink again adds fixedSize(horizontal: false, vertical: true) after frame(maxHeight:).
  • .accessibilityHidden(false) on a container shows VoiceOver everything inside it again, a decorative image included, so each part is hidden or shown on its own, as the column's search field does.
  • Nothing moves without end through a SwiftUI TimelineView: every tick lays out the whole window. The face at the head of the sidebar moves through Core Animation layers (FaceLayerView) and sends a frame only once something moved enough to be seen.
  • On macOS a window's scenePhase stays active behind another app: it says only whether a window can be seen. What Peel does when it comes forward follows NSApplication.didBecomeActiveNotification.
  • On macOS 26 a fixed header above a scroll view at the top of a column makes AppKit draw an opaque scroll edge with a line, an empty band under the title bar. Such a header goes in the toolbar or inside the scroll view.
  • A failure is a state of its own, never read from "not running". A setting flipped in one place and the work it starts in an onChange elsewhere leave a moment where the model still says off, so a warning that something failed waits for a real failure (TrashMonitor's unavailable).
  • A fact is read from the model that owns it, never from a copy. A copy taken at a model's own reads shows the old state until it reads again, so HomeModel reads the helper's state from HelperModel. While the fact changes, say what runs and show nothing half done: what the change left appears in one step, once a whole check has it (HelperModel.change). A failure goes back to whoever asked for the change and is shown there alone (HelperFailureAlert).
  • An alert names the first few of a list that can grow. AppKit never caps an alert's height, so a list of apps, pages, folders, or lines in one names its first four and counts the rest (RemovalFailureAlert.mostListed, RemovalFailureAlert.firstItems), and Copy Details, where the alert offers it, gives them all. What the person has to know whole before acting, the apps Peel asks to quit or would force quit and the formulae Clean Up uninstalls for good, is named whole, in one sentence.

Words and translations

  • One English, American, as the Apple Style Guide writes it: color, catalog, license, canceled, the serial comma. A checkbox is selected or deselected, never ticked. A place of macOS is spelled as macOS spells it, and a path through menus reads System Settings > General.
  • No em or en dashes, anywhere, and no spaced hyphen standing in for one: a colon, a comma, or parentheses say the same thing, and a range reads "3 to 4". Interface text writes the curly apostrophe (’), as macOS does.
  • Every translation lives in Localization/, and nowhere else. Peel speaks English and 17 other languages: Romanian, German, French, Spanish, Portuguese (Brazilian), Italian, Japanese, Simplified and Traditional Chinese, Dutch, Korean, Russian, Polish, Turkish, Swedish, Czech, and Ukrainian.
  • Write new or changed interface text in English, then run python3 Scripts/sync_localizations.py after a Debug build so the catalogs list it. In every catalog but InfoPlist the English is the key, so new text has no translations, and changed text is new text: the sync keeps the entry of the text it replaced, marked stale with its translations. StringCatalogTests fails for both until all 17 are written for the new text and the stale entry is gone, which happens before the change is merged. Text an Info.plist shows (a permission prompt, the copyright) keeps its key, and its translations are marked for review until they are written again.
  • Text a person reads goes through the catalogs: Text(verbatim:) is only for what is not words, or for a name. Text that only a Debug build shows (inside #if DEBUG) takes the DebugBuild table (tableName: "DebugBuild"), whose catalog the Release configuration leaves out (EXCLUDED_SOURCE_FILE_NAMES), so a release carries none of it.
  • A translation uses the words macOS itself uses in that language for every place, menu, and command, and writes the marks macOS writes there: Dutch keeps the straight apostrophe, German puts a no-break space before an ellipsis, French one before ? : ! and ; and inside « », App Store keeps one in the languages whose macOS writes it so, Czech, Polish, and Russian keep a one-letter word, and Polish a count, with the next word through a no-break space, and Romanian joins a Romanian word with a non-breaking hyphen (U+2011) but never a name or an option someone may copy. StringCatalogTests checks these, and also wants the ellipsis character, never three periods, each sidebar name and tab title within the room it is given, and SwiftUI's own words for the menu items SwiftUI builds.
  • The peel command stays in English, since scripts read it. PeelCore returns English and never looks up a translation, since the package has no catalog of its own: the app words what PeelCore sends.
  • A change to peel keeps what its tests and scripts read: an option's default is said in its own help ("Without it, 20."), never left to ArgumentParser's "(default: ...)", which the manual page drops; the exit codes stay those its help names; what it prints goes through Output; and a command that removes goes through Cleanup, so it asks, records, and exits as the others do.
  • String(localized:) leaves inflection markup as written, wherever its text goes (an alert's title or message, a notification, anything handed to AppKit), so text that counts and needs a plain String is built with String(inflecting:). InflectionMarkupTests refuses a String(localized:) that carries the markup.

Documents

  • A change that alters what Peel does updates every document that describes it in the same change: README.md, GUIDE.md, SAFETY.md, PRIVACY.md, SECURITY.md, ARCHITECTURE.md, CHANGELOG.md, and TERMINAL.md, and this file and CONTRIBUTING.md when a rule they state changes.
  • CHANGELOG.md's entry for the next release gives each place in Peel a heading of its own under Added, Changed, and Fixed, in the sidebar's order, with its lines under it. A line about two places goes under the first and names the other, or under a heading that names both where it holds for both alike.
  • The documents say what Peel does and why, with Apple's or the tool's own documentation as the source. Nothing in the repository or the app (code, comments, tests, the interface, documents, commit messages, release notes) names another cleaner or uninstaller or compares Peel with one. README's Thank you, which names the apps that inspired Peel, is the one exception.
  • docs/ is Peel's website. Only its text changes, and only to stay true to the app; its questions are written twice in index.html, the page and its data, and a change updates dateModified there and lastmod in sitemap.xml.

Commits and pull requests

  • One change per commit, each building and passing the tests, with a message that says in plain words what changed for the person using Peel and why. A commit that fixes what an issue reported ends with Refs # and the issue's number, so GitHub lists it on the issue, and with no word that closes it: the maintainer closes the issue.
  • One change per pull request. Its description says what goes wrong without it, how it was tested (the test that failed before and passes after, and the page or command it was checked on), and what couldn't be checked.
  • If an assistant helped, say so in the description, and exactly how: what it wrote, what it reviewed, what it translated, and what you checked yourself. If none did, there is nothing to say.