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.

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.md
index 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.md
new file mode 100644
index 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.md
index 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.
```bash
xcodebuild -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 run
without 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 I
checked 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 be
traceable 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 problem
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift
index f3e530b2..f17d7d92 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/DocumentationTests.swift
@@ -5,8 +5,8 @@ import Testing
struct 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.md
index 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) expla
Bug 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 a
public issue.
- Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).