Merge pull request #1 from YKKULTRA/agent/repository-polish

Polish repository presentation

Author: YKKULTRA

Docs/SAFETY.md

@@ -0,0 +1,88 @@
+# Safety model
+
+SqueakyClean is designed around one default: incomplete evidence must stop cleanup. This document describes the guarantees implemented in the current release and the limits around them.
+
+## Current trust boundary
+
+The production cleanup profile is deliberately narrow. A file can become actionable only when all of the following are true:
+
+1. It is a user LaunchAgent plist discovered under the allowlisted user LaunchAgents root.
+2. Its configured `Program`, or first `ProgramArguments` value, resolves to an absolute target path.
+3. That target is definitively missing, not merely inaccessible or unresolved.
+4. The plist is not matched to an installed application and does not fall under an Apple-managed or protected path.
+5. The scan captured a usable filesystem identity and the action-time checks still match it.
+
+An unmatched cache, log, preference, Application Support folder, temporary item, installer receipt, script, or package is not evidence of abandonment. Those categories remain non-actionable in the current production rules.
+
+## Scan boundaries
+
+Standard scans inventory selected locations in the current user's Library plus the process temporary directory. Deep scans add selected `/Library` locations, shared launch items, and installer receipts.
+
+Every `/Library` finding is analysis-only. Deep mode does not enable system-wide cleanup.
+
+The scanner skips malformed plists and per-item metadata failures without aborting the entire scan. Unreadable roots are reported as skipped. A partial traversal is never treated as complete evidence.
+
+The inventory pass examines the immediate children of configured roots. Candidate sizing and fingerprinting are recursive and include hidden descendants and package contents.
+
+## Fail-closed classification
+
+- Installed-app data is blocked.
+- Unknown ownership is ignored, not treated as orphaned.
+- Apple-managed paths such as CloudKit, Mobile Documents, iCloud, Containers, and Group Containers are blocked.
+- SqueakyClean's own application data is blocked.
+- Symbolic-link candidates are rejected by the action-time path policy.
+- Relative, malformed, unresolved, inaccessible, or still-valid launch targets are left untouched.
+- Launch target checks expand `~`, `$HOME`, and `${HOME}` forms before evaluating the target.
+
+## Approval-time gate
+
+Scan results can become stale, so approval is not enough by itself. Immediately before quarantine, SqueakyClean:
+
+1. Resolves and validates the canonical source path.
+2. Confirms the path remains inside an allowed user root and outside every protected root.
+3. Rejects symbolic links.
+4. Verifies the filesystem number, file number, and modification state captured by the scan.
+5. Refreshes the installed-app catalog and blocks newly matched ownership.
+6. Rechecks that the launch target is still definitively missing.
+7. Fingerprints the payload.
+8. Rechecks the source identity and evidence once more before moving it.
+
+If any check is unavailable, unsupported, or different from the scan evidence, the move is refused.
+
+## Quarantine transactions
+
+Quarantine, restore, and purge use a serialized manifest that is written atomically. Each mutation first records a pending operation, then performs the filesystem change, and finally records the completed state.
+
+A filesystem lock serializes complete transactions across SqueakyClean processes. Managed payload paths, restore destinations, and the quarantine root identity are revalidated immediately around moves and deletion.
+
+At startup, pending operations are reconciled against the filesystem. Clear outcomes are finalized. Ambiguous outcomes are preserved as explicit interrupted records so the app never guesses that a payload was deleted, moved, or restored.
+
+## Payload integrity
+
+Fingerprint version 2 separates file, directory, and symbolic-link domains. It hashes full file contents and deterministic directory entries, including hidden files and package contents. Large files are streamed in 1 MiB chunks rather than loaded into memory.
+
+Restore accepts only a supported fingerprint version. It verifies the quarantined payload before moving it, verifies it again at the destination, and finalizes the record only after both checks succeed.
+
+Directory sizing and fingerprinting fail closed when any descendant cannot be enumerated. Partial results are never accepted as complete.
+
+## Space semantics
+
+Candidate sizes are allocated-byte estimates. Compression, clones, filesystem metadata, and changes after the scan can change the amount eventually reclaimed.
+
+Quarantine normally moves a payload on the same disk, so it does not free the payload's space. Only explicit permanent purge reclaims that space. Restored records can remain as audit history without retaining a quarantined payload.
+
+## Local records
+
+Scan snapshots, approval history, transaction state, and quarantined payloads are stored under:
+
+```text
+~/Library/Application Support/SqueakyClean
+```
+
+Read-only scanning is decoupled from audit and quarantine initialization, so a damaged local store does not disable the scanner itself.
+
+## Permission and distribution limits
+
+Full Disk Access is optional. The in-app access check probes selected protected locations, but it is not an authoritative verdict about the macOS privacy entitlement state.
+
+Local bundles are ad hoc signed and verified for development. A public release still needs a Developer ID identity, Apple notarization, and a finalized permissions story. These safety controls reduce risk, but they do not turn an early preview into a substitute for backups or careful review.

Docs/images/scan-workspace.png

@@ -1,92 +1,161 @@
-# SqueakyClean
+<div align="center">
+  <h1>SqueakyClean</h1>
+  <p><strong>A macOS cleaner that treats uncertainty as a stop sign.</strong></p>
+  <p>Inspect known leftover locations, review the evidence, and quarantine only what you approve.</p>
+  <p>
+    <a href="https://github.com/YKKULTRA/squeakyclean/actions/workflows/ci.yml"><img alt="macOS CI" src="https://github.com/YKKULTRA/squeakyclean/actions/workflows/ci.yml/badge.svg"></a>
+    <img alt="macOS 14 or newer" src="https://img.shields.io/badge/macOS-14%2B-111827?logo=apple&logoColor=white">
+    <img alt="Swift 6.3" src="https://img.shields.io/badge/Swift-6.3-F05138?logo=swift&logoColor=white">
+  </p>
+  <p>
+    <a href="#quick-start">Build from source</a> ·
+    <a href="#safety-by-design">Safety model</a> ·
+    <a href="CHANGELOG.md">Changelog</a>
+  </p>
+</div>
+
+<p align="center">
+  <img src="Docs/images/scan-workspace.png" alt="SqueakyClean scan workspace in dark mode" width="100%">
+</p>
+
+SqueakyClean is a native SwiftUI utility for careful macOS cleanup. It scans an allowlisted set of leftover locations, explains why a finding is actionable, and keeps cleanup reversible until you explicitly purge it. Scanning and cleanup happen locally.
+
+> [!NOTE]
+> SqueakyClean is an early, deliberately narrow preview. Today it offers cleanup only for user LaunchAgent plists whose configured absolute target is definitively missing. It is not yet a general cache cleaner or app uninstaller.
+
+## Why SqueakyClean
+
+| Evidence first | Reversible by default | Local and transparent |
+|---|---|---|
+| Uncertain ownership is ignored, never treated as proof that data is abandoned. | Approved items enter an app-managed quarantine and can be restored before purge. | Every candidate includes a reason and evidence. There are no third-party Swift package dependencies. |
+
+Most cleaners optimize for how much they can find. SqueakyClean optimizes for how confidently it can leave the right things alone.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["Read-only scan"] --> B["Explain the evidence"]
+    B --> C["You review and approve"]
+    C --> D["Revalidate path, identity, and evidence"]
+    D --> E["Journal and quarantine"]
+    E --> F["Restore"]
+    E --> G["Explicit purge"]
+```
 
-`SqueakyClean` is a native macOS cleanup app built with `SwiftUI` and a safety-first scanning engine.
+1. **Scan:** Standard mode inventories selected user locations. Deep mode adds system-wide locations for analysis only.
+2. **Classify:** The rules fail closed. Protected, installed, Apple-managed, inaccessible, unresolved, and unknown data is not offered for cleanup.
+3. **Review:** Search, filter, inspect evidence, select one or many candidates, and approve the exact items you want moved.
+4. **Revalidate:** Immediately before a move, SqueakyClean checks the canonical path, filesystem identity, modification state, ownership, and missing-target evidence again.
+5. **Quarantine:** The move is journaled and fingerprinted. Restore remains available until a separately confirmed purge.
 
-## What It Does
+> [!IMPORTANT]
+> Quarantine normally does not free disk space because the payload remains on the same disk. Space is reclaimed only after a separate, explicitly confirmed purge. Displayed sizes are allocated-byte estimates.
 
-- Scans only allowlisted locations that commonly accumulate technical leftovers.
-- Treats installed-app data as blocked and unmatched app-like data as unknown, not orphaned.
-- Offers cleanup only when the scan has positive evidence, currently a user launch item whose resolved target is missing.
-- Inventories `/Library` in Deep mode for analysis, but never offers cleanup there.
-- Requires explicit user approval before cleanup.
-- Supports async scans, cancellation, search, kind filters, multi-select, and batch quarantine.
-- Shows an allocated-size estimate for candidates, including hidden files and package contents.
-- Moves approved items into an app-managed quarantine area with restore support. Quarantine itself does not free disk space.
-- Can permanently purge quarantined items through explicit destructive confirmation.
-- Records scan snapshots and approval history in the app's own storage.
+## Current cleanup scope
 
-## Current Scope
+| Finding | Current behavior |
+|---|---|
+| User LaunchAgent with an absolute target confirmed missing | Reviewable cleanup candidate |
+| Unmatched app-like data | Ignored as unknown |
+| Installed-app or Apple-managed data | Blocked |
+| Relative, malformed, unresolved, or inaccessible launch target | Left untouched |
+| Any `/Library` finding from Deep mode | Analysis only |
+| Cache, log, preference, Application Support, temporary, or receipt data | Inventoried, but not actionable in this release |
 
-Milestone 1 deliberately keeps its actionable scope narrow. In the production scan profile, a user LaunchAgent becomes reviewable only when its configured target resolves to an absolute path and that path is confirmed missing. A relative command, unresolved path, malformed plist, or still-valid launch item is not offered for cleanup.
+This narrow scope is intentional. A catalog miss or an old file is not enough evidence that something is safe to remove.
 
-An app-like folder or preference that fails to match the installed-app catalog is treated as unknown and ignored. A missing catalog match is not proof that an app was removed. Orphaned caches, logs, Application Support folders, preferences, stale scripts, and installer remnants are therefore not production cleanup categories today.
+## Safety by design
 
-Deep mode inventories selected `/Library` locations, including shared launch items and installer receipts, but every system-wide finding is analysis-only. The app deliberately does **not** propose cleanup for installed-app data, Apple-managed paths such as CloudKit, Mobile Documents, iCloud, Containers, or Group Containers, its own data, or any `/Library` item.
+- **Read-only until approval.** Scanning never mutates discovered files.
+- **Fail-closed decisions.** Unknown or incomplete evidence stops the cleanup path.
+- **Approval-time revalidation.** Allowed roots, protected paths, filesystem identity, modification state, installed-app ownership, and launch-target evidence are checked again around the move.
+- **Crash-aware transactions.** An atomically written journal and cross-process lock serialize quarantine, restore, and purge operations. Ambiguous interrupted states remain visible instead of being guessed away.
+- **Verified restore.** Type-separated SHA-256 fingerprints cover full file contents and deterministic directory entries, including hidden files and package contents. Restore verifies the payload before and after moving it.
 
-## Safety Model
+The detailed invariants and current trust boundaries are documented in [the safety model](Docs/SAFETY.md).
 
-- Scans are read-only until the user explicitly approves a candidate.
-- Classification fails closed: unknown ownership is ignored, while installed, Apple-managed, protected, and system-wide data is blocked.
-- Immediately before quarantine, an action-time gate requires a recorded filesystem identity, verifies the canonical path is inside an allowed user root, outside protected roots, is not a symbolic link, and still has the identity and modification state recorded by the scan. It also refreshes the installed-app catalog and, for dead launch items, confirms that the target is still definitively missing. It rechecks the candidate after fingerprinting and before moving it.
-- Quarantine writes a pending operation to a serialized, atomically saved manifest before moving the source. Pending quarantine, restore, and purge states are reconciled after interrupted operations; ambiguous states are preserved as interrupted instead of guessed or deleted.
-- A filesystem lock serializes complete quarantine, restore, and purge transactions across app processes. Managed payload and restore paths are revalidated immediately around mutations.
-- Version 2 fingerprints domain-separate files, directories, and symbolic links, then hash full file contents and deterministic directory entries, including hidden files and package contents. Restore requires a supported fingerprint and verifies it both before moving and at the destination before finalizing.
-- Candidate sizes are allocated-byte estimates, not guarantees of space that will be reclaimed. Filesystem compression, clones, metadata, and later changes can affect the result.
-- Quarantine preserves restore support but normally moves data on the same disk, so it frees no space. Only permanent purge reclaims the payload's space, and purge requires separate confirmation.
-- Malformed launch agent plists, unreadable files, and unreadable roots are skipped or surfaced as skipped roots instead of aborting the whole scan.
-- Launch agent target checks expand `~`, `$HOME`, and `${HOME}`-style paths before deciding whether a target is missing.
-- Large files are hashed with streaming SHA256 to avoid loading the whole payload into memory.
-- Directory sizing and fingerprinting fail closed if any descendant cannot be enumerated; partial traversals are never treated as complete evidence.
+## Quick start
 
-## Project Layout
+### Requirements
 
-- `Sources/SqueakyCleanCore`: scanning, ownership resolution, rule engine, quarantine, restore, audit persistence
-- `Sources/SqueakyCleanApp`: `SwiftUI` app shell and user flows
-- `Resources/Info.plist`: bundle metadata used by the local app build script
-- `Scripts/build-app.sh`: builds, signs, and verifies `build/SqueakyClean.app`
-- `Tests/SqueakyCleanCoreTests`: unit tests for the core safety and cleanup behavior
+- macOS 14 or newer
+- A Swift 6.3-capable toolchain
+- Xcode Command Line Tools for building and code signing
 
-## Run It
+### Build the app
 
 ```bash
+git clone https://github.com/YKKULTRA/squeakyclean.git
+cd squeakyclean
 Scripts/build-app.sh
 open build/SqueakyClean.app
 ```
 
-The default build targets the current Mac architecture and uses an ad hoc signature, which is suitable for local development. To create a universal app containing both Apple silicon and Intel executables:
+The default local build targets the current Mac architecture and uses an ad hoc signature. To build a universal app for Apple silicon and Intel Macs:
 
 ```bash
 ARCHS="arm64 x86_64" Scripts/build-app.sh
 ```
 
-For a distribution build, select an installed signing identity. Non-ad-hoc identities automatically enable the hardened runtime and request a secure timestamp:
+For Developer ID signing, select an installed identity:
 
 ```bash
 ARCHS="arm64 x86_64" \
 CODE_SIGN_IDENTITY="Developer ID Application: Example, Inc. (TEAMID)" \
 Scripts/build-app.sh
 ```
 
-`BUILD_DIR` can select another output directory, `MACOSX_DEPLOYMENT_TARGET` can raise the plist default, and `WARNINGS_AS_ERRORS=1` enables strict compiler warnings during packaging. Running the raw SwiftPM executable can make Finder open a Terminal window. Use the `.app` bundle above for normal macOS launching.
+Real signing identities automatically enable the hardened runtime and request a secure timestamp. `BUILD_DIR`, `MACOSX_DEPLOYMENT_TARGET`, and `WARNINGS_AS_ERRORS=1` provide additional build controls.
 
-## Verify It
+## Development
 
 ```bash
-swift build
-swift test
-WARNINGS_AS_ERRORS=1 Scripts/build-app.sh
-plutil -lint build/SqueakyClean.app/Contents/Info.plist
-codesign --verify --deep --strict --verbose=2 build/SqueakyClean.app
+swift build -Xswiftc -warnings-as-errors
+swift test -Xswiftc -warnings-as-errors
+ARCHS="arm64 x86_64" WARNINGS_AS_ERRORS=1 Scripts/build-app.sh
 ```
 
-GitHub Actions runs release builds and tests with warnings treated as errors, then packages and verifies a universal app bundle.
+GitHub Actions performs strict release builds and tests, packages a universal app bundle, verifies its architectures and signature, and uploads the archive as a workflow artifact.
+
+### Project layout
+
+| Path | Purpose |
+|---|---|
+| `Sources/SqueakyCleanCore` | Inventory, classification, path policy, quarantine, restore, and audit logic |
+| `Sources/SqueakyCleanApp` | SwiftUI interface and user workflows |
+| `Tests/SqueakyCleanCoreTests` | Core correctness and transaction-safety coverage |
+| `Resources/Info.plist` | App bundle metadata |
+| `Scripts/build-app.sh` | Native or universal app packaging, signing, and verification |
+
+## FAQ
+
+<details>
+<summary><strong>Does SqueakyClean delete anything automatically?</strong></summary>
+
+No. Scans are read-only. A candidate moves only after explicit approval, and permanent purge requires a separate destructive confirmation.
+</details>
+
+<details>
+<summary><strong>Is Full Disk Access required?</strong></summary>
+
+No. Start without it. The app explains when a deliberately selected scan location could not be read, and its access check is a practical probe rather than an operating-system entitlement verdict.
+</details>
+
+<details>
+<summary><strong>Does it remove caches or Application Support folders?</strong></summary>
+
+Not in the current release. Those locations may be inventoried, but only positively identified dead user LaunchAgents can become cleanup candidates.
+</details>
 
-## Local App Data
+<details>
+<summary><strong>Where does SqueakyClean keep its own data?</strong></summary>
 
-The app stores its own audit and quarantine data under:
+Audit history, transaction state, and quarantined payloads live under `~/Library/Application Support/SqueakyClean`.
+</details>
 
-`~/Library/Application Support/SqueakyClean`
+## Project status
 
-## Distribution Status
+SqueakyClean is currently version `0.1.0` and under active development. This repository ships source code and development artifacts, not a notarized public release. Public distribution still requires Developer ID signing, Apple notarization, and a finalized permissions story.
 
-The local app bundle is ad-hoc signed and strictly verified. That is appropriate for development and personal testing. Public distribution still needs a Developer ID identity, Apple notarization, and a clearer permissions story. The build script supports Developer ID signing and the hardened runtime, but it deliberately does not submit credentials or notarize automatically.
+A project license has not yet been selected. See the [changelog](CHANGELOG.md) for the latest work and known scope.