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
Gather the rules every change follows in AGENTS.md
Țugui Dragoșe421a0785c5d
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex b79f4460..cff2fb12 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -8,9 +8,18 @@<!-- A test that failed before the change and passes after, and the page or command you checked it on. -->+## What couldn't be checked++<!-- Anything you couldn't check on your Mac, and why, so it can be checked before merging. -->++## Help from an assistant++<!-- If a coding assistant helped, say exactly how: what it wrote, reviewed, or translated, and what you checked yourself. If none did, delete this section. -->+## Checklist- [ ] The app builds with no warnings, and `swift test --package-path Packages/PeelCore -Xswiftc -warnings-as-errors` passes, apart from `StringCatalogTests` for new or changed interface text, whose translations are added before merging.+- [ ] The change follows [AGENTS.md](../AGENTS.md): the problem was proved on a Mac before the change, and a test failed first.- [ ] Nothing of the user's is deleted for good: every removal goes through `TrashService`.- [ ] New or changed interface text is in English, and `python3 Scripts/sync_localizations.py` ran after a Debug build.- [ ] A changed command of `peel` has its manual page written again with `python3 Scripts/generate_manual.py`.diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 00000000..f32a1a0a--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,225 @@+# 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](CONTRIBUTING.md) says how to propose a change, [ARCHITECTURE.md](ARCHITECTURE.md) how+the parts fit together, and [SAFETY.md](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++Every change goes through these steps, in this order, however small it looks.++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 afterwards, 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.+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 end to end**, from where it starts to where it shows, and check that nothing depending on+ it changes behavior: callers, overrides, observers, the app and `peel` alike.+6. **Build and test after every change**, not only at the end: the whole package suite with warnings as errors,+ and the app's Debug build ([CONTRIBUTING.md](CONTRIBUTING.md#what-you-need) has the commands).+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.+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.++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 must never break++Tests enforce these rules. 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 its own: the empty+ placeholder `TrashMover` makes to hold a name on a disk that can't rename without replacing (exFAT), when the move+ it was made for fails, and the folder `PreferenceBackup` makes for a reset's saved settings, when saving fails+ while it is still empty. Its list of refusals 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 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. `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 Trash itself, keychains and the keys and credentials `ProtectedData.homeKeys` names, 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](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.+- **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`.+- **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 a folder its tool tags as a cache+ (`CACHEDIR.TAG`), such as Swift Package Manager's `.build`, and inside a cache on the Developer page.+- **The user's exclusions reach every scanner**, so an excluded item never appears in the first place.+- **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](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`).+- **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`).++## 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 administrators only, asked when a connection opens and 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.+- 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.+- 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`), works only through that descriptor, and moves the item only while its identity is the one+ it checked, so a folder or an item swapped after the check leads nowhere.+- 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.++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.+- The files a test scans sit in a temporary home, never in yours, and nothing is registered with Launch Services+ from a test. 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`).+- 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, an+ installation, 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 every name a document writes in code font, `TerminalThemeTests` 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.+- Slower checks run only when asked for, and both are worth running before a release:+ `PEEL_TEST_THIS_MAC=1 swift test --package-path Packages/PeelCore --filter SuggestedSelectionOnThisMacTests`+ scans every app installed on the Mac and checks that nothing Peel would select is refused or shared, and the+ `PeelUITests` scheme runs Xcode's accessibility audit on every page, in light and dark, moving the pointer and+ typing, so it runs on a Mac nobody is using:+ `xcodebuild test -project Peel.xcodeproj -scheme PeelUITests -derivedDataPath build/DerivedData`.+- For work on Peel itself: `PEEL_SNAPSHOT=<folder>`, in a Debug build, renders Home, About, and the menu bar panel+ to PNG files in light and dark, each also with Increase Contrast, then quits; `PEEL_TERMINAL_EXPORT=<folder>`, in+ a Debug build, writes what `Terminal/` holds, then quits; `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.++## 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 the package is held to the same bar by `-warnings-as-errors` on the command line.+- Small, focused files, and code that reads like the code around it. A dependency only when nothing else will do.+- **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.+- **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.+- Everything can be used without a pointer. A switch whose label is hidden carries an+ `accessibilityRepresentation` that VoiceOver, Voice Control, and Switch Control can press, and every control is at+ least 20 by 20 points. Text takes the system's styles by role, so it follows the system's text size.+- 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.++## 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. The English is the key, so changed text loses its translations and new text has+ none: `StringCatalogTests` fails for that text, and only for it, until all 17 are written, which happens before+ the change is merged.+- 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,+ 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.+- 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.++## 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, ARCHITECTURE.md, CHANGELOG.md, and TERMINAL.md.+- The documents say what Peel does and why, with Apple's or the tool's own documentation as the source. They don't+ name other cleaners or uninstallers, or compare Peel with them.+- `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. Sign off every commit (`git commit -s`).+- 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.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 22e5c5b1..d4656091 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -2,26 +2,13 @@Thank you for wanting to help.-Peel removes files from people's Macs. That one fact shapes everything below: a bug here doesn't put a wrong-number on a screen, it takes away something somebody wanted. Most of this page is about the rules that keep that-from happening, and they are not up for negotiation.+> **Working with a coding assistant?** Give it [AGENTS.md](AGENTS.md) before the first change, and have it work by+> those rules. Many assistants read that file by themselves. The rules bind every change, with an assistant or+> without, so read it yourself too.-## The rule everything else serves--**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 that quitting waits for them. No code path in Peel deletes anything of the user's,-and a change that adds one won't be accepted. What Peel deletes outright is its own: 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, and the folder `PreferenceBackup` makes for a reset's saved settings, when saving fails while it is still empty.-Its list of refusals goes to the Trash when `peel history --refused --clear` asks. Four things Peel-starts can't be undone by History, and each says so where the user confirms it: 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. `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.+Peel removes files from people's Macs. That one fact shapes everything here: a bug doesn't put a wrong number on a+screen, it takes away something somebody wanted. So every change is proved before it is made, tested before it is+fixed, and checked where it shows, as [AGENTS.md](AGENTS.md) describes step by step.## What you need@@ -29,251 +16,71 @@ to Terminal.tested on by hand, so it has no code for an older macOS.- Xcode 27 or later, with Swift 6.4.- A team to sign with, even a free one. The project names its maintainer's team, so build with yours: add- `DEVELOPMENT_TEAM=YOUR_TEAM_ID` to the `xcodebuild` command, or choose your team for the targets under Signing &- Capabilities in Xcode and leave that change out of your commits. The helper accepts only an app signed by the- same team as itself, so the app and the helper you build in Debug work together; a Release helper accepts only a- Developer ID build that can't be debugged. launchd starts the helper only as the team named in- `Support/com.tuguidragos.Peel.Helper.plist` (`SpawnConstraint`), so to install the helper you build, put your- team there as well, again outside your commits. The package's tests need no signing.+ `DEVELOPMENT_TEAM=YOUR_TEAM_ID` to the `xcodebuild` command, or choose your team under Signing & Capabilities in+ Xcode, and leave that change out of your commits. launchd starts the helper only as the team named in+ `Support/com.tuguidragos.Peel.Helper.plist` (`SpawnConstraint`), so to install the helper you build, put your team+ there as well, again outside your commits. The package's tests need no signing.- Nothing else. The only dependency is Apple's swift-argument-parser, which Xcode fetches.-- A Release build needs `ENABLE_POINTER_AUTHENTICATION=YES` and `MACOSX_DEPLOYMENT_TARGET=26.0` on the- `xcodebuild` command line, since only the command line reaches the Swift packages: every program imports- them for arm64e too, and a package that names no platform would be built for an older macOS, with its class- data unsigned. `Scripts/release.sh` passes both; a Debug build needs nothing.```bashxcodebuild -project Peel.xcodeproj -scheme Peel -configuration Debug -derivedDataPath build/DerivedData DEVELOPMENT_TEAM=YOUR_TEAM_ID build``````bash-swift test --package-path Packages/PeelCore+swift test --package-path Packages/PeelCore -Xswiftc -warnings-as-errors```Build and test after every change, not only at the end. After a Debug build, run-`python3 Scripts/sync_localizations.py` so the string catalogs match the strings in the code. It refuses to run+`python3 Scripts/sync_localizations.py` so the string catalogs match the strings in the code; it refuses to runwithout build output rather than empty the catalogs. After changing a command of `peel`, run-`python3 Scripts/generate_manual.py` as well, which writes its manual page, `Support/peel.1`, from the tool just-built.--The project's targets build with warnings as errors, and that is the bar a change has to clear. The package's-manifest doesn't set it, so ask for it on the command line to hold the package, its tests included, to the-same bar, as the Checks workflow and `Scripts/release.sh` do:--```bash-swift test --package-path Packages/PeelCore -Xswiftc -warnings-as-errors-```--Tests run through the code Peel runs, on the Mac running them: a scan asks this Mac's Launch Services and reads its-system apps and a real disk, since an answer about Homebrew, launchd, Launch Services, or the disk is worth little-against a mock. A stand-in is only for what a Mac can't do on demand, such as a folder that never answers, and the-files a test scans sit in a temporary home, never in yours. When a test expects Peel to select an app's files, the-app it scans is a made-up one, under a domain kept for examples (such as `net.example`): a real app may be installed-anywhere on the Mac running the test, and another copy of it keeps those files. Some tests read this Mac on purpose,-so they are slower and depend on what you have installed. The slowest scans every app installed here, in full, to-check that nothing Peel would select is refused or shared. It takes minutes, so it runs only when asked for, and it-is worth running before a release:--```bash-PEEL_TEST_THIS_MAC=1 swift test --package-path Packages/PeelCore --filter SuggestedSelectionOnThisMacTests-```--Before a release, run Xcode's accessibility audit on every page, About, Settings, and the menu bar panel, in the-light appearance and the dark one. It moves the pointer, types, and quits a Peel that is open, so it has a scheme-of its own and runs only when asked for, on a Mac nobody is using. macOS asks once to give the test runner-Accessibility, and for an administrator's password when Automation Mode turns on. Each result comes with a picture-of the screen, in the test report:--```bash-xcodebuild test -project Peel.xcodeproj -scheme PeelUITests -derivedDataPath build/DerivedData DEVELOPMENT_TEAM=YOUR_TEAM_ID-```+`python3 Scripts/generate_manual.py`, which writes its manual page, `Support/peel.1`, from the tool just built.-A few environment variables are there 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, in the light and dark appearances, each also with Increase Contrast, then quits, so their layouts can be- checked in any language without a screenshot.-- `PEEL_TERMINAL_EXPORT=<folder>`, in a Debug build, writes what `Terminal/` holds into that folder, then quits.-- `PEEL_MEASURE=<name>`, in every build, since Release timings are the ones that count, appends to- `~/Library/Logs/Peel/<name>` how long after launch the first frame came, then the main thread's long turns and- missed frames on every `SIGUSR1` and when Peel quits. The name is a file name, never a path. It wakes Peel every- frame, so leave it off when measuring idle CPU.-- `PEEL_TEST_VOLUME=<folder>` lets the tests move a folder to the Trash of another volume and back. Name a folder- on a volume other than your home's, such as a disk image made for it, so nothing reaches your own Trash.--[ARCHITECTURE.md](ARCHITECTURE.md) explains how the parts fit together.+A Release build needs `ENABLE_POINTER_AUTHENTICATION=YES` and `MACOSX_DEPLOYMENT_TARGET=26.0` on the `xcodebuild`+command line, since only the command line reaches the Swift packages; `Scripts/release.sh` passes both.## Where things live-- `Peel/`: the SwiftUI app, with its pages (`Views/`), their models (`Model/`), navigation, and the licenses it ships.-- `PeelHelper/`: the privileged helper. Read its section below before touching it.+- `Peel/`: the SwiftUI app, with its pages (`Views/`) and their models (`Model/`).+- `PeelHelper/`: the privileged helper, which runs as root. Read its rules in [AGENTS.md](AGENTS.md) before+ touching it.- `PeelFinder/`: the sandboxed Finder Sync extension.- `PeelCLI/`: the `peel` command line tool, a thin entry point.- `PeelUITests/`: the accessibility audit, run by hand before a release.- `Packages/PeelCore/`: everything that decides and acts, with the tests. `PeelCore` scans, matches, and removes;`PeelPrivileged` is the part the helper shares; `PeelCommandLine` holds the `peel` commands; `PeelLink` is the`peel://open` link the Finder extension sends and the app reads.-- `Localization/`: every translation, and nothing else: the string catalogs of the app and the Finder extension.+- `Localization/`: every translation, and nothing else.- `Support/`: the Info.plists, the helper's launchd property list, and the manual page of `peel`.-- `Logo/`: the only source of the logo: the app icon (`Peel.icon`), the menu bar glyph, and `export.sh`, which- renders the icon as PNGs, of which the README shows `Peel-Dark.png`.-- `Scripts/`: `sync_localizations.py`, which keeps the catalogs in step with the code, `generate_manual.py`,- which keeps the manual page in step with `peel`, `release.sh`, which builds, signs, notarizes, and checks a- release, and `make_dmg.sh`, which lays out the disk image's window with dmgbuild (run by uv), from the settings- in `dmg_settings.py`, over the background `dmg_background.swift` draws.-- `Terminal/`: what TERMINAL.md links to and shows: each theme's Terminal profile (`Themes/`), a picture of it- (`Renders/`), and pictures of the prompt's layouts (`Prompts/`). A Debug build writes them again when- `PEEL_TERMINAL_EXPORT` names a folder, and `TerminalThemeTests` checks that each profile is still what that- export writes and that TERMINAL.md links to it and its picture.-- `readme-assets/`: the screenshots the documents show, and Tapetum's icon.-- `.github/`: the test workflow, the issue forms, and the pull request template.-- `docs/`: Peel's website, peel.tuguidragos.com, which GitHub Pages publishes from this folder as it is.-- The documents, at the root: [README.md](README.md) says what Peel is and how to get it, [GUIDE.md](GUIDE.md)- what each tool does, [PRIVACY.md](PRIVACY.md) what Peel sends, [SAFETY.md](SAFETY.md) what it protects,+- `Logo/`: the only source of the logo, the app icon and the menu bar glyph.+- `Scripts/`: the scripts that keep the catalogs and the manual page in step with the code, and build a release.+- `Terminal/`: the Terminal themes and the pictures TERMINAL.md shows.+- `readme-assets/`: the screenshots the documents show.+- `.github/`: the Checks workflow, the issue forms, and the pull request template.+- `docs/`: Peel's website, peel.tuguidragos.com.+- The documents, at the root: [README.md](README.md) says what Peel is and how to get it, [GUIDE.md](GUIDE.md) what+ each tool does, [PRIVACY.md](PRIVACY.md) what Peel sends, [SAFETY.md](SAFETY.md) what it protects,[TERMINAL.md](TERMINAL.md) every Terminal theme and setting, [SECURITY.md](SECURITY.md) how to report a- vulnerability, [CHANGELOG.md](CHANGELOG.md) what each release changed, and- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) what is expected of everyone taking part.- [ARCHITECTURE.md](ARCHITECTURE.md) and this page are for changing Peel.--## The rules a change must not break--Tests enforce these. If your change makes one of them fail, the rule is right and the change is wrong.--- **`RemovalGuard` refuses what nothing can bring back**, in every account on the Mac:- - iCloud Drive and other cloud storage folders, and the Trash itself;- - keychains, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.password-store`, the signing keys and credentials that- `ProtectedData.homeKeys` names one by one, and the wallet keys that `ProtectedData.walletKeys` names, each- read from the wallet's own documentation or source;- - a browser profile that holds a wallet extension's vault or Brave's own wallet, and a folder holding one a- level or two down (`ProtectedData.holdsABrowserWallet`);- - Mail (but a Mail plug-in directly in `Mail/Bundles`, which holds code and no mail), Messages, Safari, Contacts,- Calendars, Reminders, Shortcuts, HomeKit, Accounts, Finance, IdentityServices, FaceTime and call history,- Freeform, Journal, Stickies, the passes in Wallet, and every group container of Apple's own, where macOS keeps- notes and other data;- - `Autosave Information`, where apps keep work not saved yet;- - the spelling and text replacement stores, and iPhone and iPad backups;- - photo, music, and video libraries, and a folder holding one a level or two down;- - a sandboxed app's `Documents`, and its container while that folder holds anything or cannot be read;- - the folders of every account's home (Applications, Desktop, Documents, Downloads, Library, Movies,- Music, Pictures, Public) themselves, though not what is inside them;- - work a tool keeps in a cache folder (an IDE's local history, Deno's `location_data`), and the global- preferences files.-- It 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, so another case, a link, or a `/.vol` name reaches the same answer. The- places it protects by path (in the home, the keychains, and the folders that stay themselves) are known by- device and inode as well, wherever a link leads them, and are found without opening them- (`PathPattern.locatedWithoutOpening`): opening a folder inside another app's container makes macOS ask the- person for that app's data. [SAFETY.md](SAFETY.md) lists every protected place.-- **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 that such a name- sits in. Every "is this inside that folder" question goes through `PathComponents`.-- **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 could not- 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 a folder the tool tags as a- cache (`CACHEDIR.TAG`), such as Swift Package Manager's `.build`, and inside a cache on the Developer page, such as- the packages Xcode checks out into DerivedData.-- **The user's exclusions reach every scanner**, so an excluded item never appears in the first place.-- **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](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`).-- **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`).--## Changes that need a particular test--- **Matching**: `LeftoverMatcherTests`. A new rule needs the case it catches and a case it must not catch.-- **A wallet extension**: its ID goes into `BrowserWallets.swift` only in the comment above its SHA-256, never as- text the compiler keeps. XProtect, the malware scanner in macOS, takes a binary that carries a few wallet IDs for- a program that steals them and moves it to the Trash, a test binary included, so tests read the IDs from those- comments (`WalletIDs`). `BrowserWalletTests` checks every fingerprint against the ID above it.-- **The privileged helper**: `PrivilegedPathPolicyTests`, and for any change to the helper a bump of- `HelperIdentity.protocolVersion`.-- **`DeveloperCaches.definitions`**: a source showing the folder is a cache, and a `DeveloperCachesTests` run.- A link into a repository's files names the commit you read it at, not a branch, whose lines move with every- commit. Never a toolchain, never an installation, never a file holding an account or a token, and never a path- inside another path already in the table.-- **Anything that decides what may be removed**: a test that fails without your fix, written to get past the- rule rather than to confirm it. The `Attack*Tests` files hold these.-- **Anything a document names or counts**: the document changes in the same change. `DocumentationTests` looks in- the code for every name a document writes in code font, such as `TrashService`; `TerminalThemeTests` looks in- TERMINAL.md for every line the Terminal page writes and a link to every theme; `CommandLineTests` looks in- `Support/peel.1` for every command of `peel`; and `DesktopWalletTests` checks SAFETY.md's count of wallet places- against `ProtectedData.walletKeys`.--## 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 administrators only, asked when a connection opens and 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.-- 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 (`setCodeSigningRequirement` on each accepted connection), and- a released helper refuses a build that can be debugged.-- 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`), works only through that descriptor, and moves the item only while its identity is the- one it checked, so a folder or an item swapped after the check leads nowhere.-- A new operation needs `PrivilegedPathPolicyTests`, and any change to the helper a protocol version bump, so- Peel never works with a helper of another version. An update asks nothing of the person while the helper's- identifier and its launchd property list stay the same; a change to either means registering the helper again.--If you are unsure whether something belongs in the helper, it doesn't. The helper should stay small enough to-read in one sitting.--## Style--- Small, focused files, and code that reads like the code around it.-- **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 (a man page, an SDK header,- Apple's documentation). No history and no lab notes: a fixed bug belongs in the commit message, and the comment- keeps only the rule it left. Don't narrate what the next line does.-- **Lines within 120 columns**, code and comments alike. A string is never split to make its line fit, so a- sentence can still be found with a search: `LineLengthTests` measures each line of Swift without its strings,- and a script's line as it is written.-- **No dead code.** Whatever your change leaves unused (a function, a type, a string, a file, a test helper)- goes in the same change.-- **One English: American**, as the Apple Style Guide writes it: color, catalog, license, canceled, and the- serial comma. A checkbox is selected or deselected, never ticked.-- **No em or en dashes**, in the interface, in comments, or in documents, 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, and a translation the marks macOS writes in its language: Dutch keeps the- straight apostrophe, as Apple's Dutch does. The `peel` tool writes its own words in plain ASCII, and names,- paths, and macOS's own error messages as they are, in UTF-8, with what could hide or reorder text shown as `?`.-- **Every translation lives in `Localization/`.** Peel is translated into 17 languages, in the words macOS itself- uses in each. Write new or changed interface text in English, and run `python3 Scripts/sync_localizations.py`- after a Debug build so the catalog lists it. The translations are added before your change is merged; until- then `StringCatalogTests` fails for that text, and only for it. The `peel` tool and PeelCore stay in English.-- **Rows of a long list stay cheap to build.** A list builds its rows as they scroll into view. 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, since SwiftUI asks a- `Toggle`'s button for its size each time the row is measured. Duplicates' rows keep their `Toggle`: there the AppKit- checkbox costs as much, and it would dim the badge of the copy that stays differently. A button in each row takes- `RowButtonStyle` or `.borderless`: one of another style changes the window's list of focusable views whenever a row- scrolls in or out. A row a `ForEach` repeats never hides its own separator and is never a `Toggle` itself; the- `ForEach` hides the separators. A row that stands alone, such as a header or a notice, may hide its own, which costs- nothing.-- **Every switch can be pressed without a pointer.** SwiftUI gives a switch whose label is hidden with- `labelsHidden()` no action an assistive technology can perform, so such a switch carries an- `accessibilityRepresentation`: a `Toggle` labeled with the row's title, which VoiceOver, Voice Control, and Switch- Control can press. AppKit's `NSAccessibilityCheckBox` protocol requires every checkbox and switch to answer a press.-- **The interface follows Liquid Glass.** The sticker album look belongs to Home, the menu bar panel, and About- only; every other screen reads as macOS (system type, `Form` and `Section`, 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`) and peels it less on purpose, so its eyes have room: a- change to the logo's shape changes those numbers too.+ vulnerability, and [CHANGELOG.md](CHANGELOG.md) what each release changed. [ARCHITECTURE.md](ARCHITECTURE.md)+ explains how the parts fit together, and [AGENTS.md](AGENTS.md) holds the rules.++## The rules, in short++[AGENTS.md](AGENTS.md) has each of them in full, and tests enforce most. If a change makes one 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.+- **What nothing could bring back is refused**, whoever asks: keychains, crypto wallets, Mail, Messages, photo+ libraries, and the rest [SAFETY.md](SAFETY.md) lists.+- **Only what is certainly an app's, and no other app's, is selected for the user.** Anything shared, guessed, or+ possibly kept nowhere else is shown with its reason and left to the user.+- **Prove the problem on a real Mac before changing anything**, write a test that fails first, fix the cause, and+ check the result where it shows.+- **Tests run as Peel runs**, on the real Mac, with made-up apps and a temporary home, never your own files.+- **A fix is for every macOS; a visual change is for macOS 27 alone.** A bug is fixed for macOS 26 and 27 alike,+ while a change to how Peel looks goes in the macOS 27 branch and leaves macOS 26's code as it is.+- **Every translation lives in `Localization/`**, in the words macOS itself uses in each language.+- **Few comments, lines within 120 columns, American English, no em or en dashes, and no dead code.**## Proposing a change@@ -281,8 +88,11 @@ read in one sitting.2. One change per pull request, with a description of what goes wrong without it.3. Say how you tested it. "Tests pass" isn't that; "this test failed before the change and passes after, and Ichecked it on a real install of X" is.-4. If you found the behavior in Apple's documentation or a man page, quote it. Peel's decisions are meant to be+4. If something couldn't be checked on your Mac, say what and why, and the maintainer will check it.+5. If you found the behavior in Apple's documentation or a man page, quote it. Peel's decisions are meant to betraceable to something outside itself.+6. If an assistant helped, say so in the pull request, 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.## Reporting a security problemdiff --git a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swiftindex f3e530b2..f17d7d92 100644--- a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift+++ b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift@@ -5,8 +5,8 @@ import Testingstruct DocumentationTests {static let documents = [- "README.md", "SAFETY.md", "ARCHITECTURE.md", "CONTRIBUTING.md", "TERMINAL.md", "GUIDE.md", "PRIVACY.md",- "SECURITY.md", "CHANGELOG.md",+ "README.md", "SAFETY.md", "ARCHITECTURE.md", "CONTRIBUTING.md", "AGENTS.md", "TERMINAL.md", "GUIDE.md",+ "PRIVACY.md", "SECURITY.md", "CHANGELOG.md",]@Test func everyNameADocumentGivesIsInTheCode() throws {@@ -45,7 +45,7 @@ struct DocumentationTests {("ARCHITECTURE.md", "keeps the most recent \(records) items"),("SAFETY.md", "at most \(HelperRequest.maximumItems) items in one request"),("SAFETY.md", "quits \(idle) seconds after its last request ends"),- ("CONTRIBUTING.md", "still open \(patience) seconds after Peel asked it"),+ ("AGENTS.md", "still open \(patience) seconds after Peel asked it"),("ARCHITECTURE.md", "still open \(patience) seconds after Peel asked it"),("SAFETY.md", "still open after \(patience) seconds"),]diff --git a/README.md b/README.mdindex 4ec1923d..4a925058 100644--- a/README.md+++ b/README.md@@ -230,6 +230,8 @@ you build, put your team there as well. [ARCHITECTURE.md](ARCHITECTURE.md) explaBug reports, ideas, and pull requests are welcome.- Found a bug or have an idea? [Open an issue](https://github.com/TuguiDragos/Peel/issues/new/choose).+- Want to change Peel? [CONTRIBUTING.md](CONTRIBUTING.md) says how to start, and [AGENTS.md](AGENTS.md) holds the+ rules every change follows. Working with a coding assistant? Give it AGENTS.md first.- Found a security problem? Please report it privately, as [SECURITY.md](SECURITY.md) describes, and not in apublic issue.- Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).