Repository Public
1<!--2SP Chat — native macOS3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="Logo SP Chat" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="Icône SP Chat" width="112" height="112">1415# SP Chat — macOS natif1617**Client macOS entièrement natif (Swift 6, SwiftUI + AppKit) de chat.spboucher.ai : même backend, même historique, mêmes modèles vérifiés, connexion par clé d'accès avec Touch ID. Aucun WebView, aucun Electron, aucun HTML/JS.**1819**Auteur : [Simon-Pierre Boucher](https://www.spboucher.ai)**2021[](https://chat.spboucher.ai)222324252627282930313233343536373839[](https://git.spboucher.ai/sp-chat/commits)40[](https://git.spboucher.ai/sp-chat/commits)41[](https://git.spboucher.ai/sp-chat/insights)42[](https://git.spboucher.ai/sp-chat)43[](https://git.spboucher.ai/sp-chat/insights)44[](https://git.spboucher.ai/sp-chat)45[](https://git.spboucher.ai/sp-chat/branches)46[](https://git.spboucher.ai/sp-chat/tags)47[](https://git.spboucher.ai/sp-chat)4849505152535455565758596061626364656667</div>6869---7071## Sommaire7273- [Aperçu](#-aperçu)74- [Installer](#-installer)75- [Fonctions](#-fonctions)76- [Raccourcis](#-raccourcis)77- [Architecture](#-architecture)78- [Pile technique](#-pile-technique)79- [Structure du dépôt](#-structure-du-dépôt)80- [Développer](#-développer)81- [Configuration](#-configuration)82- [Écrans](#-écrans)83- [API consommée](#-api-consommée)84- [Données locales](#-données-locales)85- [Sécurité et vie privée](#-sécurité-et-vie-privée)86- [Tests](#-tests)87- [Performances](#-performances)88- [Publication](#-publication)89- [Dépannage](#-dépannage)90- [Limites connues et suite prévue](#-limites-connues-et-suite-prévue)91- [Auteur](#-auteur)92- [Licence](#-licence)9394---9596## 🎯 Aperçu9798Client macOS **entièrement natif** (Swift 6, SwiftUI + AppKit) de [chat.spboucher.ai](https://chat.spboucher.ai) :99même backend, même historique, mêmes modèles vérifiés, connexion par **clé d'accès avec Touch ID**. Aucun WebView,100aucun Electron, aucun HTML/JS : l'interface, le rendu Markdown / LaTeX / code, le streaming et la persistance sont101écrits avec les frameworks d'Apple.102103| | |104|---|---|105| Version | **2.0.0 (2) « Next Generation »** — construite et vérifiée localement, **pas encore signée pour diffusion, notarisée ni publiée** (dernière version publiée : 1.0.0) |106| Système | macOS 15 ou plus récent · binaire universel (Apple Silicon et Intel) |107| Sécurité | App Sandbox, Hardened Runtime, session dans le trousseau, aucune clé d'API dans l'app |108| Tests (2.0) | 167 unitaires · 5 d'intégration backend 1.0 (vrai backend, vrais modèles) · 65 hébergés dans l'app · 3 d'interface (XCUITest) — détail et limites dans [docs/TEST_REPORT.md](docs/TEST_REPORT.md) |109110- **Ce que l'app reproduit du site, et les écarts** : [docs/FEATURE_MATRIX.md](docs/FEATURE_MATRIX.md)111- **Architecture** : [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · **Sécurité** : [docs/SECURITY.md](docs/SECURITY.md)112- **Preuves de test et mesures** : [docs/TEST_REPORT.md](docs/TEST_REPORT.md)113- **Installation** : [docs/INSTALL.md](docs/INSTALL.md) · **Mises à jour et publication** : [docs/UPDATES.md](docs/UPDATES.md)114- **Notes de version** : [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md)115116### Famille117118| Client | Plateforme | Dépôt | Rôle |119|---|---|---|---|120| Chat SPBoucher AI | Web · PWA | [chat-spboucher-ai](https://git.spboucher.ai/chat-spboucher-ai) | backend (Next.js, PostgreSQL), API, interface web — **conservé tel quel** |121| **SP Chat** (ce dépôt) | macOS 15+ | [sp-chat](https://git.spboucher.ai/sp-chat) | second client du même serveur : historique, brouillons, fichiers, mémoire et réglages partagés avec le site |122| SP Chat pour iOS / iPadOS | iOS · iPadOS | [sp-chat-ios](https://git.spboucher.ai/sp-chat-ios) | client natif iPhone et iPad du même serveur |123124L'app ne parle à aucun fournisseur d'IA directement et ne détient aucune clé : elle consomme le registre du serveur125(`/api/models`), qui n'expose que les modèles **vérifiés par le banc d'essai**. L'identifiant `ai.spboucher.spchat` est126partagé avec l'app iOS (voir [docs/UPDATES.md](docs/UPDATES.md)).127128---129130## 📦 Installer131132Ouvre `SPChat-1.0.0.dmg`, glisse **SP Chat** dans **Applications**, lance-la depuis Applications, puis133« Continuer avec ma clé d'accès ». Détails et dépannage : [docs/INSTALL.md](docs/INSTALL.md).1341351. Télécharge `SPChat-1.0.0.dmg` (release v1.0.0 sur [git.spboucher.ai/sp-chat/releases](https://git.spboucher.ai/sp-chat/releases)). Empreinte SHA-256 : fichier `SPChat-1.0.0.dmg.sha256`.1362. Ouvre l'image disque et **glisse SP Chat dans Applications**.1373. Lance SP Chat **depuis le dossier Applications** (indispensable pour les clés d'accès). Gatekeeper l'accepte sans avertissement : l'app et le DMG sont signés Developer ID et notarisés par Apple (ticket agrafé, vérifiable hors ligne).1384. Clique « Continuer avec ma clé d'accès » : macOS propose la clé d'accès de `chat.spboucher.ai` (trousseau iCloud, Touch ID). Tu retrouves l'historique du site.139140Configuration requise : macOS 15 ou plus récent, Mac Apple Silicon ou Intel, connexion Internet pour se connecter141(l'historique déjà consulté reste lisible hors ligne).142143SHA-256 du DMG 1.0.0 : `4fb90defeba390a155678e0f5fa7c48debd6899c6277b42bd72d9d2c1c3310a5` (10,6 Mo).144145<details>146<summary><b>Sur un autre Mac</b></summary>147148- **Même compte iCloud, trousseau activé** : la clé d'accès est déjà synchronisée, la connexion fonctionne directement.149- **Autre Mac sans la clé** : dans SP Chat, « Première connexion sur ce Mac, ou code de récupération », saisis un code de récupération (Réglages → Sécurité sur un appareil connecté) ou un code créé sur le serveur (`pnpm auth bootstrap --recover`), puis enregistre une clé d'accès pour ce Mac. Autre possibilité : choisir « un autre appareil » dans la feuille macOS et scanner le code QR avec l'iPhone qui détient la clé.150151</details>152153<details>154<summary><b>Désinstaller</b></summary>155156Glisse l'app à la corbeille. Données locales : `~/Library/Containers/ai.spboucher.spchat` (cache, préférences) et157l'élément « ai.spboucher.spchat » du trousseau (jeton de session). « Se déconnecter de ce Mac » efface le cache et158révoque la session côté serveur.159160</details>161162---163164## ✨ Fonctions165166**Nouveautés 2.0 « Next Generation ».** Système visuel V2 « Graphite & Iris · Lumen » (logos des fabricants à la place167des pastilles de couleur, compositeur en capsule flottante, présence Lumen) ; catalogue **OpenRouter** complet avec168Explorateur de modèles et fiche Live Model Intelligence ; Réglages → Fournisseurs ; recherche web avec **cartes de169sources** ; Smart Follow-Ups ; panneau contextuel (Contexte, **Chronologie + relecture**, **Response Lens**, Branches) ;170**Arena** ; Cost Intelligence ; **Constellation** ; Centre de commandes ⌘K ; **synchronisation** continue avec le site et171l'app iOS. Détail : [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md), captures : `docs/img/v2/` (`Scripts/screenshots.sh`).172173**Conversation.** Streaming en temps réel plafonné à 30 images/s, générations détachées reprises après une coupure,174arrêt, régénération (avec un autre modèle), modification d'un message, versions ◀ ▶, branches, approbation d'outils,175brouillons partagés avec le site, pièces jointes validées sur leurs octets réels, lecture à voix haute et dictée.176177**Rendu.** Markdown natif (tableaux, listes de tâches, citations), blocs de code colorés avec copie, formules LaTeX en178ligne et en bloc composées avec CoreText, raisonnement repliable, appels d'outils, citations, images.179180**Modèles.** Sélecteur des modèles vérifiés par fournisseur (OpenAI, Anthropic, xAI), routage manuel / auto / rapide /181qualité / économie, effort de raisonnement, outils, profils d'usage. Le modèle se change par conversation.182183**Organisation.** Historique groupé par date, épingles, favoris, archives, projets, recherche plein texte et184sémantique (⌘F), palette de commandes (⌘K), cache local pour lire hors ligne.185186**Espace de travail.** Projets, prompts, profils, fichiers, mémoire, laboratoire de modèles, utilisation (coûts),187comparaison de modèles, recherche approfondie, images.188189**macOS.** Fenêtres multiples restaurées, barre de menus complète, inspecteur, chat rapide flottant (⇧⌘Espace, raccourci190global optionnel), icône de barre des menus optionnelle, glisser-déposer, collage enrichi, copie RTF, export Markdown /191JSON / **PDF natif**, liens `spchat://`, notifications optionnelles.192193### Parité avec le site (résumé de [docs/FEATURE_MATRIX.md](docs/FEATURE_MATRIX.md))194195Légende — **✓** reproduit · **◐** reproduit avec un écart documenté · **✗** non reproduit (justifié) · **+** propre à macOS.196197| Domaine | État | Écart documenté |198|---|---|---|199| Passkeys, bootstrap par code, codes de récupération, sessions révocables, ré-authentification, CSRF | ✓ | transition 0.2 → 0.3 non reprise (✗, fermée côté serveur) |200| Envoi, streaming SSE, reprise après coupure, idempotence, arrêt, régénération, modification, versions, branches | ✓ | — |201| Markdown, tableaux, code coloré (~40 langages), LaTeX | ✓ | TeX non composable → affiché tel quel |202| Lecture à voix haute, dictée | ◐ | implémentées, pas d'essai audio réel |203| Artefacts HTML / React / Mermaid | ◐ | **écart volontaire** : aucun moteur web embarqué — source colorée, copie, enregistrement, « Ouvrir dans le navigateur » ; aperçu natif pour SVG et Markdown |204| Sélection de texte | ◐ | par bloc ; « Copier la réponse » copie tout (texte + RTF) |205| Liste, filtres, renommer, épingler, favori, archiver, déplacer, supprimer, recherche | ✓ | — |206| Mode hors ligne | ✓ + | cache SQLite : liste, fils déjà ouverts, recherche plein texte locale |207| Modèles vérifiés, routage, effort, outils, profils | ✓ | laboratoire : onglets « rapport de benchmark » et « routage » non repris (◐) |208| Projets, fichiers, utilisation, comparer, recherche approfondie, images | ◐ | sous-fonctions secondaires non reprises (détail dans la matrice) |209| Prompts, profils, mémoire, réglages, export complet, suppression totale | ✓ | — |210211<details>212<summary><b>Propre à macOS</b></summary>213214- `NavigationSplitView`, barre d'outils native, inspecteur, feuilles et popovers, clair / sombre automatique, plein écran.215- Fenêtres multiples (une conversation par fenêtre, état partagé), restauration des fenêtres.216- Barre de menus complète et raccourcis.217- Palette de commandes ⌘K (commandes, modèles, conversations, recherche floue).218- Chat rapide (panneau flottant, ⇧⌘Espace, raccourci global ⌥⌘Espace optionnel).219- Icône de barre des menus optionnelle.220- Glisser-déposer et collage enrichi (fichiers, images) dans le compositeur.221- Copie enrichie (Markdown + RTF).222- Export PDF natif paginé (CoreText, texte sélectionnable).223- Liens profonds `spchat://c/<id>` et `spchat://new?text=…` (jamais d'action destructive ni d'envoi).224- Notifications de fin de réponse (optionnelles, permission demandée à l'activation).225- Taille du texte (⌘+ / ⌘-), libellés VoiceOver sur tous les boutons-icônes.226227</details>228229---230231## ⌨️ Raccourcis232233| Raccourci | Action | Raccourci | Action |234|---|---|---|---|235| <kbd>⌘N</kbd> | nouvelle conversation | <kbd>⇧⌘N</kbd> | nouvelle fenêtre |236| <kbd>⌘F</kbd> | rechercher | <kbd>⌘K</kbd> | palette de commandes |237| <kbd>⌘,</kbd> | réglages | <kbd>⏎</kbd> ou <kbd>⌘⏎</kbd> | envoyer (au choix) |238| <kbd>⌘.</kbd> | arrêter | <kbd>⇧⌘R</kbd> | régénérer |239| <kbd>⇧⌘M</kbd> | modèle | <kbd>⇧⌘I</kbd> | recherche web |240| <kbd>⌥⌘I</kbd> / <kbd>T</kbd> / <kbd>L</kbd> / <kbd>B</kbd> | panneau : contexte, chronologie, Lens, branches | <kbd>⌥⌘E</kbd> / <kbd>A</kbd> / <kbd>G</kbd> | Explorateur, Arena, Constellation |241| <kbd>/</kbd> et <kbd>@</kbd> | commandes et modèles dans le message | <kbd>⌘K</kbd> | centre de commandes |242| <kbd>⇧⌘E</kbd> / <kbd>⇧⌘P</kbd> | export Markdown / PDF | <kbd>⌘/</kbd> | tous les raccourcis |243| <kbd>⇧⌘Espace</kbd> | chat rapide | <kbd>⌘+</kbd> / <kbd>⌘-</kbd> | taille du texte |244245---246247## 🏗 Architecture248249SP Chat est un client du backend `chat.spboucher.ai`. Aucun moteur web n'est embarqué : ni WKWebView, ni250JavaScriptCore (vérifié par `Scripts/verify-release.sh` sur le binaire). Détail : [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).251252```mermaid253flowchart TB254 subgraph App["Cible SP Chat (MainActor par défaut)"]255 UI["Components · Features<br/>SidebarView, ChatScreen, ComposerView,<br/>MarkdownView, MathView, 10 écrans d'espace de travail"]256 VM["ChatViewModel (un par conversation)<br/>WindowModel (un par fenêtre)"]257 ENV["AppEnvironment<br/>injection de dépendances"]258 end259 subgraph Core["Paquet SwiftPM SPChatCore (aucun import d'interface)"]260 GE["GenerationEngine<br/>tour complet + reprise"]261 SSE["SSEParser · MessageAccumulator"]262 API["APIClient · Endpoints typés<br/>HTTPTransport (URLSession éphémère)"]263 AUTH["AuthService<br/>cérémonies WebAuthn"]264 CACHE["CacheStore<br/>SQLite + FTS5"]265 SEC["SecretStore (trousseau)<br/>FileValidator · Redactor"]266 MD["MarkdownParser · SyntaxHighlighter"]267 end268 UI --> VM --> GE --> SSE --> API269 ENV --> VM270 AUTH --> API271 API --> SEC272 VM --> CACHE273 UI --> MD274 API -- "HTTPS · Origin exact" --> S["chat.spboucher.ai<br/>(dépôt chat-spboucher-ai)"]275 AUTH -. "AuthenticationServices<br/>Touch ID · trousseau iCloud" .-> OS["macOS"]276```277278### Flux d'un tour de conversation279280```mermaid281sequenceDiagram282 autonumber283 participant C as ComposerView284 participant V as ChatViewModel285 participant G as GenerationEngine286 participant S as chat.spboucher.ai287 participant K as CacheStore288 C->>V: send()289 V->>G: start(.send, payload)290 G->>S: POST /api/chat (clé d'idempotence, 4 essais)291 S-->>G: SSE (SSEParser → ChatEvent → MessageAccumulator)292 G-->>V: live (≤ 30 Hz)293 Note over G,S: coupure ou silence de 45 s294 G->>S: GET /api/chat/stream?run=…&after=<dernier index>295 S-->>G: rejeu des événements manqués, puis direct296 G->>S: GET /api/conversations/:id?all=1297 G->>K: saveDetail298 K-->>V: liste latérale à jour299```300301- Le serveur exécute chaque génération **détachée** de la connexion (il envoie un battement toutes les 15 s). Le flux SSE n'est qu'une *vue* du run : en cas de302 coupure le client se rattache avec l'index du dernier événement vu ; si le run n'existe plus, il recharge la303 conversation, dont les lignes font foi.304- `ChatViewModel.messages` (messages stabilisés) et `ChatViewModel.live` (réponse en cours) sont séparés : le streaming305 n'invalide jamais les lignes déjà affichées. `MessageRow` et `ChunkView` sont `Equatable` ; le Markdown est découpé en306 blocs indépendants mis en cache, donc seul le dernier bloc est recalculé pendant le flux.307308### Connexion par clé d'accès309310```mermaid311sequenceDiagram312 autonumber313 participant A as SP Chat314 participant M as macOS (AuthenticationServices)315 participant S as chat.spboucher.ai316 A->>S: POST /api/auth/login/options317 S-->>A: défi à usage unique + cookie de cérémonie (gardé en mémoire)318 A->>M: demande d'assertion pour webcredentials:chat.spboucher.ai319 M-->>A: assertion signée (Touch ID, vérification utilisateur exigée)320 A->>S: POST /api/auth/login/verify (Origin: https://chat.spboucher.ai)321 S-->>A: jeton de session322 A->>A: jeton rangé dans le trousseau (jamais sur disque en clair)323```324325### Injection et isolation326327- `AppEnvironment` construit tout une fois (serveur, `APIClient`, `AuthService`, `CacheStore`, `GenerationEngine`, stores328 observables) et se transmet par l'environnement SwiftUI. Les tests injectent un `HTTPTransport` scripté et un329 authentificateur WebAuthn logiciel : aucun singleton réseau.330- Cible d'application : isolation `MainActor` par défaut, concurrence stricte Swift 6. Le cœur est `Sendable` (acteur331 pour SQLite, verrous pour le pot de cookies).332- Un `ChatViewModel` par conversation, partagé par toutes les fenêtres ; un `WindowModel` par fenêtre.333334### Extensibilité des fournisseurs335336Ajouter OpenAI-compatible, un modèle local ou un service privé se fait côté serveur (un adaptateur `src/lib/ai/*.ts` +337une entrée de registre) ; l'app l'affiche sans mise à jour (`Provider.label`, couleur par défaut). Un nouveau *backend*338(autre serveur) n'exigerait qu'une autre implémentation de `HTTPTransport`/`ServerConfiguration`.339340### Modifications du backend (dépôt `chat-spboucher-ai`, commit `52ec509`)341342- `GET /.well-known/apple-app-site-association` (public, liste `3YM54G49SN.ai.spboucher.spchat`, surchargeable par `APPLE_APP_IDS`).343- Libellé d'appareil « Mac · SP Chat » pour l'agent utilisateur de l'app.344345Aucune route existante n'a été modifiée ; le site web fonctionne à l'identique.346347---348349## 🧱 Pile technique350351| Couche | Technologie | Version | Rôle |352|---|---|---|---|353| Langage | Swift | mode de langage 6.0, `SWIFT_STRICT_CONCURRENCY: complete` (`project.yml`) | toute l'app |354| Interface | SwiftUI + AppKit | système | fenêtres, menus, compositeur, rendu |355| Projet | XcodeGen (`project.yml`) → `SPChat.xcodeproj` | — | 3 cibles : `SPChat`, `SPChatTests`, `SPChatUITests` |356| Cœur | paquet SwiftPM `SPChatCore` (`Package.swift`, swift-tools 6.0) | plateforme minimale du paquet : macOS 14 | modèles, réseau, auth, streaming, persistance |357| Markdown | swiftlang/swift-markdown | 0.7.3 (épinglée) | analyse CommonMark/GFM — analyseur d'Apple (cmark-gfm), robuste sur les entrées hostiles |358| Mathématiques | mgriebling/SwiftMath | 1.7.3 (épinglée) | composition LaTeX (CoreText), sans moteur web |359| Persistance | SQLite (bibliothèque système `sqlite3`) + FTS5 | système | cache local, recherche hors ligne |360| Frameworks système | Security, AuthenticationServices, Network, AVFoundation, Charts, QuickLook, UserNotifications, Carbon (raccourci global), CryptoKit (tests) | système | trousseau, passkeys, audio, graphiques, aperçus |361| Outils | Xcode 27 (rapport de tests : Xcode 27.2, Swift 6.4) | — | compilation, tests, archive |362363---364365## 🗂 Structure du dépôt366367123 fichiers suivis, dont 68 fichiers Swift (12 851 lignes).368369```370SPChat/371├── App/ 6 fichiers — entrée (@main), scènes, commandes de menu, AppDelegate (liens, raccourci global,372│ notifications), AppEnvironment (injection de dépendances), WindowModel (navigation par fenêtre)373├── Core/ 15 fichiers — paquet SwiftPM « SPChatCore » : aucun import d'interface, testable avec `swift test`374│ ├── Models/ DTO du serveur (décodage tolérant : colonnes numériques en chaînes, champs inconnus conservés)375│ ├── Networking/ HTTPTransport (URLSession éphémère), APIClient (cookie → trousseau, Origin, erreurs, ré-auth), Endpoints typés376│ ├── Authentication/ AuthService : cérémonies WebAuthn (options → authentificateur → vérification), sessions, passkeys377│ ├── Streaming/ SSEParser (octets → événements), ChatEvent, MessageAccumulator, GenerationEngine (tour complet + reprise)378│ ├── Persistence/ CacheStore (SQLite + FTS5) : listes, fils complets, catalogues, recherche hors ligne379│ ├── Security/ SecretStore (trousseau), FileValidator (type sur octets réels), Redactor (journaux sans secrets)380│ ├── Markdown/ MarkdownParser (blocs, math protégée, découpage incrémental), SyntaxHighlighter381│ └── Export/ export Markdown / JSON local382├── Features/ 26 fichiers — Account · Conversations · Chat · ModelSelector · Attachments · Search · Settings · Workspace383├── Components/ 6 fichiers — DesignSystem, SidebarView, MessageView, ComposerView, MarkdownView, MathView384├── Resources/ Info.plist, entitlements (Release / Debug), Assets.xcassets (AppIcon clair + sombre, AccentColor)385└── Tests/ CoreTests (Swift Testing), AppTests (XCTest hébergé), UITests (XCUITest)386Scripts/ build, tests, performance, provisionnement, signature, notarisation387docs/ matrice de parité, architecture, sécurité, tests, installation, mises à jour, notes de version, brand/388project.yml définition XcodeGen · Package.swift / Package.resolved : paquet SPChatCore389```390391---392393## 🛠 Développer394395Il faut Xcode 27 et [XcodeGen](https://github.com/yonaskolb/XcodeGen).396397```sh398Scripts/build.sh debug # génère SPChat.xcodeproj et compile en Debug399Scripts/build.sh core-test # 167 tests du cœur (swift test, ~1 s)400Scripts/build.sh app-test # 65 tests hébergés dans l'app401Scripts/integration-test.sh # parcours complet contre le backend de DÉVELOPPEMENT (WebAuthn logiciel, vrais modèles)402Scripts/ui-test.sh # XCUITest contre le backend de développement403Scripts/run-dev.sh # lance le build Debug sur le backend de développement (session de dev, sans Touch ID)404Scripts/perf.sh launch|stream # temps de lancement, mémoire, trace Instruments d'un long streaming405Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh # archive signée → contrôles → notarisation + DMG406```407408Les builds Debug ont leur propre identifiant (`ai.spboucher.spchat.debug`) et ne peuvent viser qu'un serveur en boucle409locale ; ils n'ont pas le droit « Associated Domains », donc pas de passkey : la session de développement est injectée.410411| Script | Rôle |412|---|---|413| `Scripts/build.sh` | point d'entrée de développement : `generate`, `debug`, `core-test`, `app-test`, `ui-test` |414| `Scripts/check-headers.sh` | échoue si un fichier source maison n'a pas l'en-tête d'auteur (Author / File / Description) |415| `Scripts/dev-session.sh` | ouvre un tunnel SSH vers le backend de **développement** et y crée une session (builds Debug, tests d'interface) |416| `Scripts/integration-test.sh` | tests de bout en bout du cœur contre le backend de développement (jamais la production) |417| `Scripts/ui-test.sh` | suite XCUITest sur l'app Debug contre le backend de développement |418| `Scripts/run-dev.sh` | lance le build Debug avec une session de développement, capture d'écran optionnelle |419| `Scripts/perf.sh` | temps de lancement, mémoire au repos, trace `xctrace` Time Profiler d'une longue réponse |420| `Scripts/provision.py` · `Scripts/asc.py` | identifiant, capacité Associated Domains et profil Developer ID par l'API App Store Connect (clé existante) |421| `Scripts/release.sh` | archive Release signée avec l'identité Developer ID **existante** et le profil de provisionnement |422| `Scripts/verify-release.sh` | contrôles du binaire signé : signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets |423| `Scripts/notarize.sh` | notarisation de l'app, agrafage, DMG signé, notarisation et agrafage du DMG, fichier `.sha256` |424| `Scripts/window-shot.swift` | capture la fenêtre au premier plan d'une app nommée (preuve des contrôles visuels) |425426---427428## ⚙️ Configuration429430| Réglage | Valeur | Où |431|---|---|---|432| Identifiant (Release) | `ai.spboucher.spchat` | `project.yml` |433| Identifiant (Debug) | `ai.spboucher.spchat.debug` — une copie de développement ne doit jamais masquer l'app installée (macOS résout l'association de domaine par identifiant d'application) | `project.yml` |434| Équipe | `3YM54G49SN` | `project.yml` |435| Version | `MARKETING_VERSION` 2.0.0 · `CURRENT_PROJECT_VERSION` 2 | `project.yml` |436| Cible de déploiement | macOS 15.0 | `project.yml` |437| Langue de développement | `fr` | `project.yml` |438| Serveur | `chat.spboucher.ai`, configuré en dur ; serveur alternatif et session injectée en builds **DEBUG uniquement**, en boucle locale uniquement (`LaunchOptions`) | `docs/SECURITY.md` |439| Domaine associé | `webcredentials:chat.spboucher.ai` (Release seulement) | `SPChat/Resources/SPChat.entitlements` |440| Schéma d'URL | `spchat://` | `SPChat/Resources/Info.plist` |441| Catégorie | `public.app-category.productivity` | `SPChat/Resources/Info.plist` |442| Flux de mise à jour | clé `SPChatUpdateFeedURL`, vide en 1.0 | `docs/UPDATES.md` |443| Profil de notarisation | profil trousseau `notarytool` nommé « MacLustr-Notarize » (existant, rien n'est créé) | `Scripts/notarize.sh` |444445Aucune variable d'environnement ni clé d'API n'est nécessaire à l'exécution : les fournisseurs sont appelés par le serveur.446447---448449## 🖥 Écrans450451| Zone | Fichiers | Contenu |452|---|---|---|453| Fenêtre principale | `App/MainWindow.swift`, `Components/SidebarView.swift` | `NavigationSplitView` : historique groupé par date, épinglées d'abord, filtres |454| Conversation | `Features/Chat/ChatScreen.swift`, `Components/MessageView.swift`, `Components/ComposerView.swift` | transcription, compositeur, inspecteur (⌥⌘I) |455| Chat rapide | `Features/Chat/QuickChat.swift` | panneau flottant |456| Connexion | `Features/Account/LoginView.swift` | clé d'accès, première connexion par code, code de récupération |457| Sélecteur de modèles | `Features/ModelSelector/ModelPickerView.swift` | par fournisseur, recherche, favoris, défaut (⇧⌘M) |458| Palette | `Features/Search/CommandPalette.swift` | commandes, modèles, conversations, recherche floue (⌘K) |459| Réglages | `Features/Settings/SettingsView.swift` | préférences, sécurité (passkeys, appareils, journal), mémoire, dépenses, données |460461Les 10 écrans de l'espace de travail (`Features/Workspace/`), aiguillés par `LibraryScreen.swift` (qui route chaque section de la barre latérale vers son écran natif) :462463| Écran | Fichier | Écran | Fichier |464|---|---|---|---|465| Projets | `ProjectsScreen.swift` | Modèles (laboratoire) | `ModelsScreen.swift` |466| Prompts | `PromptsScreen.swift` | Utilisation (Swift Charts) | `UsageScreen.swift` |467| Profils d'usage | `PresetsScreen.swift` | Comparer | `CompareScreen.swift` |468| Fichiers | `FilesScreen.swift` | Recherche approfondie | `ResearchScreen.swift` |469| Mémoire | `MemoryScreen.swift` | Images | `ImagesScreen.swift` |470471---472473## 🔌 API consommée474475L'app est un client de l'API du dépôt [chat-spboucher-ai](https://git.spboucher.ai/chat-spboucher-ai) ; elle n'expose476aucun serveur. Les chemins sont typés dans `SPChat/Core/Networking/Endpoints.swift` (26 préfixes `/api/…` distincts),477les cérémonies d'authentification dans `Core/Authentication/AuthService.swift`, le streaming dans478`Core/Streaming/GenerationEngine.swift`.479480| Domaine | Chemins |481|---|---|482| Authentification | `/api/auth/state`, `/api/auth/login/options`, `/api/auth/login/verify`, `/api/auth/setup`, `/api/auth/register/options`, `/api/auth/register/verify`, `/api/auth/reauth/options`, `/api/auth/reauth/verify`, `/api/auth/passkeys`, `/api/auth/sessions`, `/api/auth/recovery-codes`, `/api/auth/events`, `/api/auth/logout` |483| Conversation | `/api/chat`, `/api/chat/stream`, `/api/chat/cancel`, `/api/chat/edit`, `/api/chat/regenerate`, `/api/chat/approve` |484| Conversations | `/api/conversations`, `/api/conversations/:id`, `/api/search`, `/api/drafts` |485| Catalogue | `/api/models`, `/api/models/refresh`, `/api/presets`, `/api/prompts`, `/api/settings` |486| Contenus | `/api/attachments`, `/api/artifacts/:id`, `/api/images`, `/api/memories`, `/api/memories/export`, `/api/projects` |487| Voix | `/api/stt`, `/api/tts` |488| Compte | `/api/owner`, `/api/usage`, `/api/health` |489490Règles respectées par `APIClient` : `Origin: https://chat.spboucher.ai` sur chaque mutation ; `401 locked` → jeton491effacé et retour à l'écran de connexion ; `403 reauth_required` → la clé d'accès est demandée une fois puis la requête492est rejouée ; HTTPS obligatoire hors boucle locale.493494---495496## 🗄 Données locales497498| Donnée | Emplacement | Détail |499|---|---|---|500| Jeton de session | trousseau du Mac, élément « ai.spboucher.spchat » | `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`, non synchronisé |501| Cache | SQLite dans `~/Library/Containers/ai.spboucher.spchat` | mode WAL, `secure_delete`, table virtuelle FTS5 `message_fts` (`unicode61 remove_diacritics 2`) : listes, fils complets déjà ouverts, catalogues, recherche hors ligne |502| Préférences | conteneur de l'app | persistées sans secret |503| Cookies de cérémonie | mémoire seulement | session URLSession éphémère : ni cookies, ni cache, ni identifiants sur disque |504505À la fin de session (déconnexion, session révoquée ou expirée) : jeton effacé, cache SQLite vidé (`secure_delete`,506`VACUUM`, troncature du WAL), fichiers en cache supprimés.507508---509510## 🛡 Sécurité et vie privée511512Détail : [docs/SECURITY.md](docs/SECURITY.md).513514| Sujet | Choix |515|---|---|516| Bac à sable | App Sandbox activé. Droits : réseau sortant, fichiers choisis par l'utilisateur (lecture / écriture), micro (dictée seulement). Pas de serveur réseau, pas de caméra, pas d'accès large au disque |517| Hardened Runtime | activé, aucune exception (`disable-library-validation`, JIT, mémoire exécutable : absents) |518| Passkeys | `AuthenticationServices` ; domaine associé `webcredentials:chat.spboucher.ai` (droit restreint porté par le profil Developer ID) ; vérification utilisateur exigée ; la cryptographie et la biométrie restent dans macOS |519| Validation serveur | inchangée : défi à usage unique, origine et RP id exacts, signature vérifiée par `@simplewebauthn/server` |520| TLS | validation système, TLS ≥ 1.2, jamais de contournement. HTTP refusé sauf boucle locale (développement) |521| CSRF | `Origin` exact sur chaque mutation (exigence du serveur) |522| Fichiers importés | type déterminé sur les octets réels, taille et nombre plafonnés, nom assaini avant tout envoi ; HEIC → JPEG ; photos réduites à 2048 px |523| Contenu des modèles | le HTML brut n'est jamais interprété (affiché en texte) ; seuls `http`, `https`, `mailto` sont ouvrables ; les images distantes ne sont jamais chargées automatiquement |524| Liens profonds | `spchat://c/<id>` (identifiant validé par expression régulière) et `spchat://new?text=` (pré-remplissage seulement). Aucun lien n'envoie, ne modifie ni ne supprime |525| Clés d'API | aucune dans l'app ni dans le dépôt ; `Scripts/verify-release.sh` recherche des secrets dans le bundle |526| Journaux | pas de contenu de message ni de jeton ; `Redactor` masque cookies, jetons et clés |527| Permissions système | micro : demandé à la première dictée. Notifications : demandées quand l'option est activée. Raccourci global : API Carbon, sans permission Accessibilité |528529---530531## ✅ Tests532533Rapport complet, preuves et points non vérifiés : [docs/TEST_REPORT.md](docs/TEST_REPORT.md) (17 novembre 2026,534MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2).535536| Suite | Commande | Résultat rapporté |537|---|---|---|538| Cœur, unitaires (Swift Testing) | `Scripts/build.sh core-test` | **167 / 167** en ~1 s (2.0) |539| Cœur, intégration bout en bout | `Scripts/integration-test.sh` | **1 / 1** (≈ 15–18 s, vrais appels de modèle) |540| App, tests hébergés (XCTest) | `Scripts/build.sh app-test` | **65 / 65** (2.0) |541| Interface (XCUITest) | `Scripts/ui-test.sh` | **2 / 2** (≈ 45 s) |542| Contrôles du binaire signé | `Scripts/verify-release.sh` | 13 contrôles, 0 échec |543| En-têtes de fichiers | `Scripts/check-headers.sh` | OK |544545Répartition des 73 `@Test` de `SPChat/Tests/CoreTests/` : Markdown 20 · moteur de génération 13 · streaming 11 ·546décodage des modèles 10 · réseau 10 · authentification et cache 8 · intégration 1. Les 27 tests hébergés sont dans547`SPChat/Tests/AppTests/` (`AppStateTests.swift`, `ChatFlowTests.swift`), les 2 tests d'interface dans548`SPChat/Tests/UITests/SPChatUITests.swift`.549550<details>551<summary><b>Ce que chaque suite prouve</b></summary>552553**Unitaires du cœur** — décodage des charges réelles du serveur ; analyseur SSE découpé à chaque octet y compris au554milieu d'un caractère UTF-8 ; accumulation du message (rejeu après reconnexion sans doublon) ; pot de cookies (jeton dans555le magasin secret seulement, rotation, expiration) ; HTTPS obligatoire hors boucle locale ; `Origin` sur les mutations ;556session verrouillée → jeton effacé ; ré-authentification unique sans boucle ; moteur de génération : clé d'idempotence557identique sur les nouvelles tentatives, **coupure en pleine réponse reprise à `after=<index>` sans perte ni doublon**,558run disparu, connexion muette abandonnée, annulation ; cérémonies WebAuthn avec un authentificateur logiciel ; cache559SQLite (ordre, filtres, recherche plein texte sans diacritiques, entrée hostile, effacement vérifié dans le fichier,5604 000 messages) ; Markdown (tableaux, math protégée, monnaie ≠ math, `$` dans le code, HTML jamais interprété, découpage561stable pendant le streaming) ; politique de liens ; coloration ; détection de type de fichier ; rédaction des journaux ;562exports.563564**Intégration (vrai backend de développement)** — API verrouillée sans session ; mauvais code refusé ; enrôlement d'une565passkey (signature P-256 réellement vérifiée par le serveur) ; déconnexion → l'ancien jeton est refusé ; reconnexion par566passkey ; passkeys, appareils, codes de récupération, journal ; catalogue ; téléversement (fichier binaire refusé en567415) ; **message réel streamé** utilisant la pièce jointe ; régénération et versions ; modification ; **arrêt en cours568de génération** ; renommer, épingler, favori, recherche, brouillon, export ; cache hors ligne ; branche, archive,569suppression ; révocation de l'appareil → session terminée.570571**Hébergés dans l'app** — envoi → streaming → état final → cache ; **3 000 événements de jetons ne provoquent pas plus572de ~30 mises à jour d'écran par seconde** ; texte et fichiers rendus au compositeur quand rien n'est parti ; refus 402573affiché ; arrêt ; régénération avec un autre modèle, versions, modification ; rattachement à une génération encore en574cours ; ouverture hors ligne depuis le cache ; approbation d'outil ; préparation des pièces jointes (photo de5753000 × 2000 réduite à 2048 px) ; session expirée ou révoquée → déconnexion et cache vidé ; liens profonds strictement576validés ; **deux fenêtres** partageant une conversation ; palette floue ; **PDF paginé** à texte sélectionnable ; copie577RTF ; composition LaTeX à la bonne taille.578579**Interface (vraie app, vrais événements clavier)** — historique listé ; frappe et envoi par Retour ; réponse streamée580puis stabilisée ; commandes de menu activées selon la conversation ; ⌘K → palette → écran Utilisation ; ⌘N ; ⌘F ; ⌘, ;581⇧⌘N ; lancement avec serveur injoignable : app utilisable, indicateur hors ligne, échec expliqué et texte rendu au582compositeur.583584**Validation manuelle sur la production (17 nov. 2026)** — connexion par clé d'accès avec **Touch ID** dans le binaire585signé ; historique du site visible dans l'app ; session conservée entre deux lancements ; installation depuis le DMG.586587</details>588589---590591## ⚡ Performances592593Mesures du rapport de tests ([docs/TEST_REPORT.md](docs/TEST_REPORT.md)).594595| Mesure | Résultat | Méthode |596|---|---|---|597| Lancement à froid → fenêtre à l'écran | 690–715 ms (premier lancement après installation : 1 054 ms) | `Scripts/perf.sh launch`, build Release notarisé, 5 lancements |598| Empreinte mémoire au repos, connecté | 61–65 Mo (RSS 122–126 Mo) | `footprint`, `ps` |599| Streaming d'un exposé de 1 500 mots (titres, tableau, code) | CPU moyen 29 % d'un cœur, pic 39 % ; mémoire max 154 Mo | `Scripts/perf.sh stream` : build Debug non optimisé avec Instruments attaché (majorant) |600| Fenêtre présente après arrêt forcé puis relance | 10 / 10 | boucle `kill -9` + `open` |601602Lecture : le coût pendant le streaming est celui de la mise en page SwiftUI du dernier bloc, à 30 images/s ; rien n'est603recalculé pour les messages et blocs déjà affichés.604605---606607## 🚀 Publication608609Chaîne reproductible ([docs/UPDATES.md](docs/UPDATES.md)) :610611```sh612# 1. version : MARKETING_VERSION / CURRENT_PROJECT_VERSION dans project.yml613Scripts/build.sh core-test && Scripts/build.sh app-test && Scripts/integration-test.sh && Scripts/ui-test.sh614Scripts/provision.py # idempotent : identifiant, capacité Associated Domains, profil Developer ID (clé API App Store Connect existante)615Scripts/release.sh # archive Release signée (identité Developer ID du trousseau + profil), dist/SP Chat.app616Scripts/verify-release.sh # signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets617Scripts/notarize.sh # notarytool (profil trousseau « MacLustr-Notarize ») → agrafage → DMG signé → notarisation → agrafage618spctl -a -vv -t exec "dist/SP Chat.app" && spctl -a -vv -t open --context context:primary-signature dist/SPChat-<version>.dmg619```620621Rien n'est créé côté certificats : `release.sh` échoue s'il n'existe pas d'identité « Developer ID Application ».622`provision.py` remplace le profil si Apple l'a invalidé (c'est le cas dès qu'une capacité de l'identifiant change —623l'identifiant `ai.spboucher.spchat` est partagé avec l'app iOS).624625Publication : pousser le dépôt et l'étiquette `v<version>` sur spbgit, puis déposer `SPChat-<version>.dmg` et son626`.sha256` dans `M1M32:~/srv/spbgit/data/releases/sp-chat/v<version>/`.627628| État de la 1.0.0 (1) | |629|---|---|630| Étiquette | `v1.0.0` |631| Identité | Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) — certificat existant, aucun créé |632| Profil | « SP Chat Developer ID » (MAC_APP_DIRECT, Associated Domains), embarqué |633| Notarisation | app et DMG **Accepted** ; `stapler validate` OK pour les deux |634| Gatekeeper | `spctl` : *accepted, source=Notarized Developer ID* (app, DMG, app du DMG monté) |635| DMG | `dist/SPChat-1.0.0.dmg`, 10,6 Mo |636637**Mettre à jour (1.0)** — manuel : télécharger le nouveau DMG et remplacer l'app dans Applications. La session638(trousseau) et les préférences sont conservées ; le cache local est reconstruit si son schéma change.639640---641642## 🩺 Dépannage643644| Symptôme | Cause | Remède |645|---|---|---|646| « macOS n'a pas (encore) validé l'association entre cette application et le domaine des clés d'accès » | Le service système qui valide le lien app ↔ `chat.spboucher.ai` n'a pas pu lire l'app. **Cas constaté** : app lancée depuis un dossier protégé (Bureau, Documents, Téléchargements) ou depuis l'image disque, ou plusieurs copies de l'app enregistrées sur le Mac | Mets l'app dans `/Applications`, supprime les autres copies, relance. La validation demande Internet au premier lancement (quelques secondes) |647| La feuille Touch ID ne propose aucune clé | La clé d'accès n'est pas sur ce Mac | Voir « Sur un autre Mac » |648| « Session terminée » au lancement | Session révoquée ou expirée (30 jours d'inactivité, 90 jours au total) | Se reconnecter avec la clé d'accès |649| Bandeau « Hors ligne — cache local » | Serveur ou réseau injoignable | Les conversations déjà ouvertes restent lisibles ; l'envoi reprend au retour du réseau |650| Aucune fenêtre après un arrêt forcé | — | Corrigé en 1.0.0 : une fenêtre principale est toujours rouverte au lancement ; cliquer l'icône du Dock en rouvre une |651| Pas de passkey en build Debug | Les builds Debug n'ont pas le droit « Associated Domains » | Normal : utiliser `Scripts/run-dev.sh` (session de développement injectée) |652| Le profil de provisionnement est refusé à la signature | Apple l'invalide dès qu'une capacité de l'identifiant change | Relancer `Scripts/provision.py` (idempotent) |653| Le lot de tests d'interface ne se charge pas | bundle de test ad hoc + validation de bibliothèque | `ENABLE_HARDENED_RUNTIME: NO` sur la cible `SPChatUITests` (déjà dans `project.yml`) |654655---656657## 🚧 Limites connues et suite prévue658659**Écarts assumés avec le site** ([docs/FEATURE_MATRIX.md](docs/FEATURE_MATRIX.md)) :6606611. **Aperçus vivants d'artefacts HTML / React / Mermaid** : exclus par la règle « aucun WebView ». Remplacés par la source colorée et l'ouverture dans le navigateur.6622. **Sélection continue sur plusieurs blocs** : limite de `Text` SwiftUI ; compensée par la copie de la réponse entière.6633. **Sous-fonctions secondaires** de Comparer, Recherche, Images, Projets, Utilisation et du laboratoire de modèles.6644. **Enregistrement d'une clé de sécurité matérielle** : la connexion par clé de sécurité est proposée, l'enregistrement se fait pour la clé de plateforme du Mac.6655. **Interface en français uniquement** (comme le site).666667**Limites de sécurité** ([docs/SECURITY.md](docs/SECURITY.md)) :668669- Le cache SQLite n'est pas chiffré par l'application : il repose sur le bac à sable et FileVault. Il est vidé à la déconnexion.670- Les fichiers ouverts avec Coup d'œil sont copiés dans le dossier temporaire du conteneur (purgé par le système).671- L'app fait confiance au serveur configuré en dur (`chat.spboucher.ai`) ; il n'y a pas d'épinglage de certificat.672673<details>674<summary><b>Non vérifié</b> (extrait de <code>docs/TEST_REPORT.md</code>)</summary>675676- **Autre Mac / autre version de macOS** : testé sur une seule machine (macOS 27, Apple Silicon). La tranche Intel du binaire universel et macOS 15 / 26 n'ont jamais été exécutés.677- **Écrans de l'espace de travail** : compilés et relus, **non exercés** contre le serveur, sauf Utilisation (ouvert par le test d'interface).678- Dictée et lecture à voix haute (aucun essai audio), notifications, icône de barre des menus, chat rapide et raccourci global, glisser-déposer et collage d'images, ouverture d'artefact dans le navigateur, Coup d'œil des pièces jointes.679- Restauration des fenêtres après un redémarrage, plein écran, onglets de fenêtres.680- VoiceOver : libellés posés sur les contrôles, aucun audit avec le lecteur d'écran.681- Enrôlement d'une passkey **dans le binaire signé** (seule la connexion l'a été) ; connexion par clé de sécurité matérielle.682- Fournisseurs OpenAI et xAI en conversation réelle depuis l'app (tests réels faits avec Anthropic).683- Instrument Leaks, mesure d'énergie, conversations réelles de plusieurs milliers de messages à l'écran.684685</details>686687**Mise à jour automatique (prévue, non livrée)** — l'architecture réserve le point d'entrée : clé `SPChatUpdateFeedURL`688d'Info.plist (vide en 1.0) et `UpdateChecker` (`Features/Settings/SettingsView.swift`). Conception retenue :6896901. un flux *appcast* servi en HTTPS par git.spboucher.ai, chaque entrée portant version, URL du DMG, taille et **signature EdDSA** ;6912. clé publique EdDSA embarquée dans l'app ; une archive dont la signature ne vérifie pas est refusée, même servie en HTTPS ;6923. l'archive téléchargée doit en plus être signée par la même équipe Developer ID et notarisée (vérification `SecStaticCode` avant remplacement) ;6934. installation par un assistant hors bac à sable (service XPC), comme le fait Sparkle 2 pour les apps sandboxées.694695Tant que ces quatre garanties ne sont pas en place, l'app n'installe rien d'elle-même.696697---698699## 👤 Auteur700701<div align="center">702703<img src="docs/brand/icon.png" width="64" height="64" alt="">704705**Simon-Pierre Boucher** — conception, développement, exploitation706707[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai708709</div>710711## 📄 Licence712713© 2026 Simon-Pierre Boucher — logiciel privé. Tous droits réservés.714