ChocoClean — Édition Chocolat

Votre stockage, clairement expliqué.
Application macOS native, locale et open source — sans télémétrie, sans dépendance tierce, sans suppression pendant l’analyse.

Télécharger la dernière release · Voir la présentation · Consulter la checklist

ChocoClean est une application macOS native de gestion du stockage. Elle recherche des caches, des journaux anciens, le contenu de la Corbeille, certains artefacts Xcode et, après sélection explicite d’un dossier, des installateurs ou fichiers volumineux. Elle explique chaque résultat et ne supprime rien pendant l’analyse.

Le projet contient une vraie application SwiftUI, un moteur d’analyse asynchrone, une validation de sécurité centralisée, une quarantaine restaurable, un historique JSON local, des exclusions et des tests sur arborescences temporaires. Aucune bibliothèque tierce, aucune télémétrie et aucune API privée ne sont utilisées.

Avertissement : un outil de nettoyage agit sur des données réelles. Examinez la sélection avant chaque opération et conservez une sauvegarde à jour. ChocoClean privilégie volontairement les faux négatifs aux faux positifs : un fichier inutile peut être ignoré lorsqu’il existe un doute.

État de la version 1.0

Fonctionnel :

• application SwiftUI macOS 14+ et projet Xcode partagé ;
• interface « Édition Chocolat », navigation à dix sections et accueil en quatre étapes ;
• calcul de capacité totale, utilisée et disponible ;
• analyse concurrente limitée, progressive et annulable ;
• caches utilisateur, journaux anciens, Corbeille et données Xcode ;
• dossier choisi par l’utilisateur pour téléchargements, installateurs et gros fichiers ;
• sélection par élément ou catégorie, recherche, Finder et Coup d’œil ;
• niveaux de risque, raison de détection et conséquence de suppression ;
• exclusions persistantes et seconde vérification avant traitement ;
• quarantaine avec fiche de restauration atomique et noms anti-collision ;
• déplacement des fichiers personnels vers la Corbeille ;
• suppression définitive limitée aux éléments déjà dans la Corbeille, après double confirmation ;
• rapport séparant estimation, octets traités et capacité réellement observée comme libérée ;
• historique, export JSON et restauration sans écrasement silencieux ;
• notifications facultatives demandées au moment utile ;
• données de démonstration et aperçus SwiftUI sans accès au disque réel ;
• journal d’intention persistant avant chaque mutation, pour détecter une opération interrompue ;
• tests d’interface pour l’accueil, l’analyse, l’annulation, la sélection, la double confirmation, l’historique, la restauration et Coup d’œil ;
• français et localisation anglaise complète ;
• icône finale et page GitHub Pages responsive.

Voir l’analyse approfondie des risques et les invariants du moteur de sécurité avant toute distribution.

Prérequis

• macOS 14 Sonoma ou version ultérieure ;
• Xcode 16 ou version ultérieure recommandé ;
• Swift 6 est accepté, avec code compilé en mode de langage Swift 5 pour préserver la compatibilité macOS 14 ;
• Apple Silicon ou Intel 64 bits.

La V1 a été ouverte et vérifiée avec Xcode 26.6 (donc supérieur au minimum Xcode 16), puis compilée en Debug et Release sur Apple Silicon ainsi qu’en Release universelle arm64 + x86_64. La suite comprend Swift Testing, XCTest et cinq parcours XCUITest. Le test explicite à 100 000 fichiers et le test de frontière de volume APFS monté passent sur des volumes temporaires dédiés.

Ouvrir et exécuter dans Xcode

1. Ouvrir ChocoClean.xcodeproj dans Xcode 16+.
2. Sélectionner le schéma partagé ChocoClean et la destination My Mac.
3. Sans compte Apple Developer payant, laisser l’exécution locale utiliser la signature « Sign to Run Locally » ; aucune équipe n’est requise pour développer et tester localement.
4. Pour une publication signée Developer ID, choisir une équipe et vérifier que le Bundle Identifier com.chococlean.app est disponible.
5. Lancer avec ⌘R.
6. Exécuter les tests avec ⌘U.

Le dépôt reste aussi un Swift Package autonome : ouvrir Package.swift ou exécuter swift run ChocoClean permet un cycle de développement rapide, mais le projet .xcodeproj doit être utilisé pour produire et signer un véritable bundle .app.

Compilation en ligne de commande

Avec Xcode sélectionné :

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -project ChocoClean.xcodeproj -scheme ChocoClean -destination 'platform=macOS' build
xcodebuild -project ChocoClean.xcodeproj -scheme ChocoClean -destination 'platform=macOS' test

Le projet reste également compilable comme Swift Package :

swift build

Pour reproduire toute la validation locale, y compris le test de 100 000 fichiers, le volume APFS temporaire et les XCUITests :

./Scripts/test-all.sh

Pour produire localement le DMG universel signé ad hoc :

./Scripts/build-release.sh 1.0.0

Le DMG et sa somme SHA-256 sont écrits dans dist/.

Choix de distribution et bac à sable

La cible fournie prépare une distribution directe :

• Hardened Runtime activé ;
• App Sandbox désactivé ;
• aucune exécution en root ;
• aucune commande shell lancée par l’application ;
• toutes les opérations passent par FileManager, URL, AppKit et les API officielles.

Ce choix est assumé. Un bac à sable Mac App Store ne permet pas d’examiner globalement ~/Library/Caches, ~/.Trash et ~/Library/Developer/Xcode sans transformer l’expérience en une succession de sélections manuelles. Une variante Mac App Store doit activer App Sandbox, demander chaque dossier via NSOpenPanel, conserver des signets de sécurité et désactiver les catégories non autorisées.

ChocoClean ne demande pas l’accès complet au disque au premier lancement. Les erreurs TCC sont collectées emplacement par emplacement et l’analyse continue. Un bouton ouvre la page correspondante des Réglages Système, mais accorder cet accès reste un choix de l’utilisateur et ne change pas la liste interne des racines autorisées.

Capacités et réglages Xcode

Pour la distribution directe fournie :

• macOS Deployment Target : 14.0 ;
• Hardened Runtime : activé ;
• App Sandbox : désactivé ;
• Signing Certificate : Apple Development en Debug, Developer ID Application en Release hors Mac App Store ;
• Automatically manage signing : acceptable en développement ;
• User Notifications : aucune capacité spéciale, autorisation demandée à l’usage ;
• réseau : aucune capacité ni connexion nécessaire ;
• PrivacyInfo.xcprivacy : inclus dans les ressources ;
• architectures : réglage standard $(ARCHS_STANDARD).

Pour une variante sandboxée : activer App Sandbox et User Selected File en lecture/écriture, puis désactiver toute racine non choisie explicitement.

Signature, archive et notarisation

Avec un compte Apple Developer payant :

1. Régler une équipe et un Bundle Identifier uniques.
2. Choisir Any Mac (Apple Silicon, Intel) puis Product > Archive.
3. Dans Organizer, sélectionner Distribute App > Developer ID > Upload.
4. Conserver Hardened Runtime et signer tous les composants.
5. Laisser Xcode envoyer l’archive au service de notarisation Apple.
6. Une fois acceptée, exporter et vérifier :

codesign --verify --deep --strict --verbose=2 /chemin/ChocoClean.app
spctl --assess --type execute --verbose=4 /chemin/ChocoClean.app

Tester ensuite sur un compte macOS standard qui n’a jamais lancé ChocoClean, avec et sans autorisations TCC.

Sans compte Apple Developer payant, le script fourni crée à la place une signature ad hoc avec Hardened Runtime. codesign --verify --deep --strict réussit, mais Gatekeeper ne peut pas considérer cette build comme notarisée : spctl --assess la refuse normalement. La release GitHub doit donc l’annoncer explicitement et expliquer l’ouverture par clic droit > Ouvrir. Il ne faut jamais présenter cette build communautaire comme notarisée.

Architecture

Le projet suit MVVM et sépare strictement l’interface des accès disque :

ChocoClean/
├── ChocoClean.xcodeproj/        Projet macOS et schéma partagé
├── Package.swift                Construction Swift Package secondaire
├── Sources/ChocoClean/
│   ├── App/                     Point d’entrée, état global, injection, démo
│   ├── DesignSystem/            Palette et composants Édition Chocolat
│   ├── Models/                  Modèles fortement typés et Codable
│   ├── Scanners/                Analyseurs indépendants
│   ├── Services/                Scan, nettoyage, permissions, quarantaine
│   ├── Utilities/               Identité, empreinte, chemin, formatage
│   ├── Views/                   Vues SwiftUI par fonction
│   └── Resources/               Confidentialité et localisation
├── Tests/ChocoCleanTests/       Sécurité, persistance, annulation, performance
├── Tests/ChocoCleanUITests/     Parcours interface et accessibilité essentiels
├── Scripts/                     Tests complets et création reproductible du DMG
├── docs/                        Page de présentation GitHub Pages
└── Documentation/              Architecture, risques et règles de sécurité

Le flux est le suivant :

Scanner spécialisé
  → résultat typé + identité + empreinte
  → sélection explicite dans l’interface
  → validation centralisée complète
  → quarantaine / Corbeille / suppression autorisée de la Corbeille
  → résultat par élément
  → rapport et historique atomiques

La persistance utilise un fichier JSON Codable, versionné et écrit atomiquement dans ~/Library/Application Support/ChocoClean. Cette solution native est plus simple à auditer que SwiftData pour le schéma limité de la version 1. Elle évite un conteneur de base de données supplémentaire dans le chemin critique de restauration.

Avant chaque mutation, un journal d’intention séparé écrit une fiche planned. La fiche devient completed ou failed après l’opération. Au prochain lancement, toute intention restée en attente est signalée afin qu’une interruption brutale ne soit pas confondue avec un succès.

Quarantaine

Chaque élément reçoit un dossier UUID :

~/Library/Application Support/ChocoClean/Quarantine/Items/<UUID>/
├── <nom-original>
└── record.json

Le moteur déplace d’abord l’élément, écrit immédiatement record.json de façon atomique, puis revient au chemin d’origine si l’écriture échoue. Une restauration refuse tout écrasement ; l’interface choisit actuellement un nom restauré, restauré 2, etc. La quarantaine reste sur le disque : elle compte donc zéro octet réellement libéré avant purge.

L’expiration est enregistrée et affichée, mais la version 1 ne purge jamais automatiquement. La méthode de purge existe dans le service et exige une confirmation, sans être exposée à l’interface. Cette omission est volontairement plus sûre qu’une expiration destructive silencieuse.

Tests

Les tests n’accèdent à aucune donnée personnelle réelle. Ils créent des dossiers UUID sous le répertoire temporaire du système et les suppriment à la fin. Ils couvrent :

• limites de composant de chemin ;
• racines système et zones personnelles sensibles ;
• lien symbolique interne, sortant et boucle ;
• remplacement d’inode entre analyse et traitement ;
• identité stable et règles d’exclusion ;
• quarantaine, collisions UUID et conflit de restauration ;
• persistance atomique ;
• annulation cohérente ;
• séparation traité/réellement libéré ;
• inspection mesurée de 1 000 fichiers ;
• fichier inaccessible, fichier immutable, lien physique multiple et clone APFS ;
• manque d’espace simulé lors de l’écriture de record.json, avec retour arrière ;
• signet périmé et opération interrompue détectée au lancement ;
• arborescence franchissant un volume APFS temporaire monté ;
• cinq parcours XCUITest couvrant l’accueil, le scan, l’annulation, la sélection, la double confirmation, l’historique, la restauration, le clavier et l’action Coup d’œil.

Le test synthétique de 100 000 fichiers est présent mais ne s’exécute que si CHOCOCLEAN_RUN_LARGE_PERF_TESTS=1, car sa création sollicite fortement le disque de la machine de développement.

Données locales et confidentialité

• aucun compte ;
• aucune télémétrie ;
• aucune requête réseau ;
• chemins complets absents des journaux techniques par défaut ;
• historique, réglages, exclusions et signets uniquement en local ;
• notifications locales uniquement après activation ;
• rapport exporté uniquement vers une destination choisie.

Limitations connues

• La détection de doublons exacts n’est pas incluse dans la version 1.
• Les simulateurs indisponibles et Device Support Xcode ne sont pas proposés : leur état actif n’est pas établi avec assez de certitude.
• La présence de Xcode et de services de compilation est détectée par identifiants d’applications ; un processus en ligne de commande atypique peut échapper à cette observation. Dans le doute, fermer les outils de compilation avant de traiter Derived Data.
• Les dates de dernier accès ne sont pas toujours fiables sur APFS et ne servent jamais seules à rendre un élément admissible.
• Les clones APFS, fichiers compressés et instantanés rendent l’espace physique récupérable difficile à prédire. Seule une variation de capacité observée est affichée comme gain réel après suppression définitive.
• Le nettoyage de la Corbeille est traité élément par élément, pas comme l’action Finder globale « Vider la Corbeille » sur tous les volumes.
• Les volumes externes sont désactivés, même si le réglage apparaît à titre informatif.
• Un audit VoiceOver humain complet, le retrait réel de l’accès complet au disque et le débranchement physique d’un disque restent des validations manuelles de publication.
• La build communautaire GitHub est signée ad hoc et non notarisée ; Gatekeeper peut demander une ouverture explicite.
• Une installation et un premier lancement sur une seconde machine restent nécessaires avant de qualifier une build de production.
• La purge de quarantaine n’est pas exposée dans l’interface et n’est jamais automatique.

Checklist avant publication

Consulter Documentation/FINAL_CHECKLIST.md. La release GitHub est une build communautaire universelle signée ad hoc et non notarisée : elle est destinée à l’évaluation et à la contribution open source. Une publication qualifiée Developer ID reste conditionnée à la notarisation, à l’audit VoiceOver humain, aux scénarios de permissions réels et à un essai sur une seconde machine.