SP Chat — macOS natif
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.
Auteur : Simon-Pierre Boucher
Sommaire
- Aperçu
- Installer
- Fonctions
- Raccourcis
- Architecture
- Pile technique
- Structure du dépôt
- Développer
- Configuration
- Écrans
- API consommée
- Données locales
- Sécurité et vie privée
- Tests
- Performances
- Publication
- Dépannage
- Limites connues et suite prévue
- Auteur
- Licence
🎯 Aperçu
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 : l'interface, le rendu Markdown / LaTeX / code, le streaming et la persistance sont écrits avec les frameworks d'Apple.
| 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) |
| Système | macOS 15 ou plus récent · binaire universel (Apple Silicon et Intel) |
| Sécurité | App Sandbox, Hardened Runtime, session dans le trousseau, aucune clé d'API dans l'app |
| 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 |
- Ce que l'app reproduit du site, et les écarts : docs/FEATURE_MATRIX.md
- Architecture : docs/ARCHITECTURE.md · Sécurité : docs/SECURITY.md
- Preuves de test et mesures : docs/TEST_REPORT.md
- Installation : docs/INSTALL.md · Mises à jour et publication : docs/UPDATES.md
- Notes de version : docs/RELEASE_NOTES.md
Famille
| Client | Plateforme | Dépôt | Rôle |
|---|---|---|---|
| Chat SPBoucher AI | Web · PWA | chat-spboucher-ai | backend (Next.js, PostgreSQL), API, interface web — conservé tel quel |
| SP Chat (ce dépôt) | macOS 15+ | sp-chat | second client du même serveur : historique, brouillons, fichiers, mémoire et réglages partagés avec le site |
| SP Chat pour iOS / iPadOS | iOS · iPadOS | sp-chat-ios | client natif iPhone et iPad du même serveur |
L'app ne parle à aucun fournisseur d'IA directement et ne détient aucune clé : elle consomme le registre du serveur
(/api/models), qui n'expose que les modèles vérifiés par le banc d'essai. L'identifiant ai.spboucher.spchat est
partagé avec l'app iOS (voir docs/UPDATES.md).
📦 Installer
Ouvre SPChat-1.0.0.dmg, glisse SP Chat dans Applications, lance-la depuis Applications, puis
« Continuer avec ma clé d'accès ». Détails et dépannage : docs/INSTALL.md.
- Télécharge
SPChat-1.0.0.dmg(release v1.0.0 sur git.spboucher.ai/sp-chat/releases). Empreinte SHA-256 : fichierSPChat-1.0.0.dmg.sha256. - Ouvre l'image disque et glisse SP Chat dans Applications.
- 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).
- 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.
Configuration requise : macOS 15 ou plus récent, Mac Apple Silicon ou Intel, connexion Internet pour se connecter (l'historique déjà consulté reste lisible hors ligne).
SHA-256 du DMG 1.0.0 : 4fb90defeba390a155678e0f5fa7c48debd6899c6277b42bd72d9d2c1c3310a5 (10,6 Mo).
Sur un autre Mac
- Même compte iCloud, trousseau activé : la clé d'accès est déjà synchronisée, la connexion fonctionne directement.
- 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é.
Désinstaller
Glisse l'app à la corbeille. Données locales : ~/Library/Containers/ai.spboucher.spchat (cache, préférences) et
l'élément « ai.spboucher.spchat » du trousseau (jeton de session). « Se déconnecter de ce Mac » efface le cache et
révoque la session côté serveur.
✨ Fonctions
Nouveautés 2.0 « Next Generation ». Système visuel V2 « Graphite & Iris · Lumen » (logos des fabricants à la place
des pastilles de couleur, compositeur en capsule flottante, présence Lumen) ; catalogue OpenRouter complet avec
Explorateur de modèles et fiche Live Model Intelligence ; Réglages → Fournisseurs ; recherche web avec cartes de
sources ; Smart Follow-Ups ; panneau contextuel (Contexte, Chronologie + relecture, Response Lens, Branches) ;
Arena ; Cost Intelligence ; Constellation ; Centre de commandes ⌘K ; synchronisation continue avec le site et
l'app iOS. Détail : docs/RELEASE_NOTES.md, captures : docs/img/v2/ (Scripts/screenshots.sh).
Conversation. Streaming en temps réel plafonné à 30 images/s, générations détachées reprises après une coupure, arrêt, régénération (avec un autre modèle), modification d'un message, versions ◀ ▶, branches, approbation d'outils, brouillons partagés avec le site, pièces jointes validées sur leurs octets réels, lecture à voix haute et dictée.
Rendu. Markdown natif (tableaux, listes de tâches, citations), blocs de code colorés avec copie, formules LaTeX en ligne et en bloc composées avec CoreText, raisonnement repliable, appels d'outils, citations, images.
Modèles. Sélecteur des modèles vérifiés par fournisseur (OpenAI, Anthropic, xAI), routage manuel / auto / rapide / qualité / économie, effort de raisonnement, outils, profils d'usage. Le modèle se change par conversation.
Organisation. Historique groupé par date, épingles, favoris, archives, projets, recherche plein texte et sémantique (⌘F), palette de commandes (⌘K), cache local pour lire hors ligne.
Espace de travail. Projets, prompts, profils, fichiers, mémoire, laboratoire de modèles, utilisation (coûts), comparaison de modèles, recherche approfondie, images.
macOS. Fenêtres multiples restaurées, barre de menus complète, inspecteur, chat rapide flottant (⇧⌘Espace, raccourci
global optionnel), icône de barre des menus optionnelle, glisser-déposer, collage enrichi, copie RTF, export Markdown /
JSON / PDF natif, liens spchat://, notifications optionnelles.
Parité avec le site (résumé de docs/FEATURE_MATRIX.md)
Légende — ✓ reproduit · ◐ reproduit avec un écart documenté · ✗ non reproduit (justifié) · + propre à macOS.
| Domaine | État | Écart documenté |
|---|---|---|
| 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) |
| Envoi, streaming SSE, reprise après coupure, idempotence, arrêt, régénération, modification, versions, branches | ✓ | — |
| Markdown, tableaux, code coloré (~40 langages), LaTeX | ✓ | TeX non composable → affiché tel quel |
| Lecture à voix haute, dictée | ◐ | implémentées, pas d'essai audio réel |
| 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 |
| Sélection de texte | ◐ | par bloc ; « Copier la réponse » copie tout (texte + RTF) |
| Liste, filtres, renommer, épingler, favori, archiver, déplacer, supprimer, recherche | ✓ | — |
| Mode hors ligne | ✓ + | cache SQLite : liste, fils déjà ouverts, recherche plein texte locale |
| Modèles vérifiés, routage, effort, outils, profils | ✓ | laboratoire : onglets « rapport de benchmark » et « routage » non repris (◐) |
| Projets, fichiers, utilisation, comparer, recherche approfondie, images | ◐ | sous-fonctions secondaires non reprises (détail dans la matrice) |
| Prompts, profils, mémoire, réglages, export complet, suppression totale | ✓ | — |
Propre à macOS
NavigationSplitView, barre d'outils native, inspecteur, feuilles et popovers, clair / sombre automatique, plein écran.- Fenêtres multiples (une conversation par fenêtre, état partagé), restauration des fenêtres.
- Barre de menus complète et raccourcis.
- Palette de commandes ⌘K (commandes, modèles, conversations, recherche floue).
- Chat rapide (panneau flottant, ⇧⌘Espace, raccourci global ⌥⌘Espace optionnel).
- Icône de barre des menus optionnelle.
- Glisser-déposer et collage enrichi (fichiers, images) dans le compositeur.
- Copie enrichie (Markdown + RTF).
- Export PDF natif paginé (CoreText, texte sélectionnable).
- Liens profonds
spchat://c/<id>etspchat://new?text=…(jamais d'action destructive ni d'envoi). - Notifications de fin de réponse (optionnelles, permission demandée à l'activation).
- Taille du texte (⌘+ / ⌘-), libellés VoiceOver sur tous les boutons-icônes.
⌨️ Raccourcis
| Raccourci | Action | Raccourci | Action |
|---|---|---|---|
| ⌘N | nouvelle conversation | ⇧⌘N | nouvelle fenêtre |
| ⌘F | rechercher | ⌘K | palette de commandes |
| ⌘, | réglages | ⏎ ou ⌘⏎ | envoyer (au choix) |
| ⌘. | arrêter | ⇧⌘R | régénérer |
| ⇧⌘M | modèle | ⇧⌘I | recherche web |
| ⌥⌘I / T / L / B | panneau : contexte, chronologie, Lens, branches | ⌥⌘E / A / G | Explorateur, Arena, Constellation |
| / et @ | commandes et modèles dans le message | ⌘K | centre de commandes |
| ⇧⌘E / ⇧⌘P | export Markdown / PDF | ⌘/ | tous les raccourcis |
| ⇧⌘Espace | chat rapide | ⌘+ / ⌘- | taille du texte |
🏗 Architecture
SP Chat est un client du backend chat.spboucher.ai. Aucun moteur web n'est embarqué : ni WKWebView, ni
JavaScriptCore (vérifié par Scripts/verify-release.sh sur le binaire). Détail : docs/ARCHITECTURE.md.
flowchart TB
subgraph App["Cible SP Chat (MainActor par défaut)"]
UI["Components · Features<br/>SidebarView, ChatScreen, ComposerView,<br/>MarkdownView, MathView, 10 écrans d'espace de travail"]
VM["ChatViewModel (un par conversation)<br/>WindowModel (un par fenêtre)"]
ENV["AppEnvironment<br/>injection de dépendances"]
end
subgraph Core["Paquet SwiftPM SPChatCore (aucun import d'interface)"]
GE["GenerationEngine<br/>tour complet + reprise"]
SSE["SSEParser · MessageAccumulator"]
API["APIClient · Endpoints typés<br/>HTTPTransport (URLSession éphémère)"]
AUTH["AuthService<br/>cérémonies WebAuthn"]
CACHE["CacheStore<br/>SQLite + FTS5"]
SEC["SecretStore (trousseau)<br/>FileValidator · Redactor"]
MD["MarkdownParser · SyntaxHighlighter"]
end
UI --> VM --> GE --> SSE --> API
ENV --> VM
AUTH --> API
API --> SEC
VM --> CACHE
UI --> MD
API -- "HTTPS · Origin exact" --> S["chat.spboucher.ai<br/>(dépôt chat-spboucher-ai)"]
AUTH -. "AuthenticationServices<br/>Touch ID · trousseau iCloud" .-> OS["macOS"]
Flux d'un tour de conversation
sequenceDiagram autonumber participant C as ComposerView participant V as ChatViewModel participant G as GenerationEngine participant S as chat.spboucher.ai participant K as CacheStore C->>V: send() V->>G: start(.send, payload) G->>S: POST /api/chat (clé d'idempotence, 4 essais) S-->>G: SSE (SSEParser → ChatEvent → MessageAccumulator) G-->>V: live (≤ 30 Hz) Note over G,S: coupure ou silence de 45 s G->>S: GET /api/chat/stream?run=…&after=<dernier index> S-->>G: rejeu des événements manqués, puis direct G->>S: GET /api/conversations/:id?all=1 G->>K: saveDetail K-->>V: liste latérale à jour
- 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 de coupure le client se rattache avec l'index du dernier événement vu ; si le run n'existe plus, il recharge la conversation, dont les lignes font foi.
ChatViewModel.messages(messages stabilisés) etChatViewModel.live(réponse en cours) sont séparés : le streaming n'invalide jamais les lignes déjà affichées.MessageRowetChunkViewsontEquatable; le Markdown est découpé en blocs indépendants mis en cache, donc seul le dernier bloc est recalculé pendant le flux.
Connexion par clé d'accès
sequenceDiagram autonumber participant A as SP Chat participant M as macOS (AuthenticationServices) participant S as chat.spboucher.ai A->>S: POST /api/auth/login/options S-->>A: défi à usage unique + cookie de cérémonie (gardé en mémoire) A->>M: demande d'assertion pour webcredentials:chat.spboucher.ai M-->>A: assertion signée (Touch ID, vérification utilisateur exigée) A->>S: POST /api/auth/login/verify (Origin: https://chat.spboucher.ai) S-->>A: jeton de session A->>A: jeton rangé dans le trousseau (jamais sur disque en clair)
Injection et isolation
AppEnvironmentconstruit tout une fois (serveur,APIClient,AuthService,CacheStore,GenerationEngine, stores observables) et se transmet par l'environnement SwiftUI. Les tests injectent unHTTPTransportscripté et un authentificateur WebAuthn logiciel : aucun singleton réseau.- Cible d'application : isolation
MainActorpar défaut, concurrence stricte Swift 6. Le cœur estSendable(acteur pour SQLite, verrous pour le pot de cookies). - Un
ChatViewModelpar conversation, partagé par toutes les fenêtres ; unWindowModelpar fenêtre.
Extensibilité des fournisseurs
Ajouter OpenAI-compatible, un modèle local ou un service privé se fait côté serveur (un adaptateur src/lib/ai/*.ts +
une entrée de registre) ; l'app l'affiche sans mise à jour (Provider.label, couleur par défaut). Un nouveau backend
(autre serveur) n'exigerait qu'une autre implémentation de HTTPTransport/ServerConfiguration.
Modifications du backend (dépôt chat-spboucher-ai, commit 52ec509)
GET /.well-known/apple-app-site-association(public, liste3YM54G49SN.ai.spboucher.spchat, surchargeable parAPPLE_APP_IDS).- Libellé d'appareil « Mac · SP Chat » pour l'agent utilisateur de l'app.
Aucune route existante n'a été modifiée ; le site web fonctionne à l'identique.
🧱 Pile technique
| Couche | Technologie | Version | Rôle |
|---|---|---|---|
| Langage | Swift | mode de langage 6.0, SWIFT_STRICT_CONCURRENCY: complete (project.yml) |
toute l'app |
| Interface | SwiftUI + AppKit | système | fenêtres, menus, compositeur, rendu |
| Projet | XcodeGen (project.yml) → SPChat.xcodeproj |
— | 3 cibles : SPChat, SPChatTests, SPChatUITests |
| Cœur | paquet SwiftPM SPChatCore (Package.swift, swift-tools 6.0) |
plateforme minimale du paquet : macOS 14 | modèles, réseau, auth, streaming, persistance |
| Markdown | swiftlang/swift-markdown | 0.7.3 (épinglée) | analyse CommonMark/GFM — analyseur d'Apple (cmark-gfm), robuste sur les entrées hostiles |
| Mathématiques | mgriebling/SwiftMath | 1.7.3 (épinglée) | composition LaTeX (CoreText), sans moteur web |
| Persistance | SQLite (bibliothèque système sqlite3) + FTS5 |
système | cache local, recherche hors ligne |
| Frameworks système | Security, AuthenticationServices, Network, AVFoundation, Charts, QuickLook, UserNotifications, Carbon (raccourci global), CryptoKit (tests) | système | trousseau, passkeys, audio, graphiques, aperçus |
| Outils | Xcode 27 (rapport de tests : Xcode 27.2, Swift 6.4) | — | compilation, tests, archive |
🗂 Structure du dépôt
123 fichiers suivis, dont 68 fichiers Swift (12 851 lignes).
SPChat/
├── App/ 6 fichiers — entrée (@main), scènes, commandes de menu, AppDelegate (liens, raccourci global,
│ notifications), AppEnvironment (injection de dépendances), WindowModel (navigation par fenêtre)
├── Core/ 15 fichiers — paquet SwiftPM « SPChatCore » : aucun import d'interface, testable avec `swift test`
│ ├── Models/ DTO du serveur (décodage tolérant : colonnes numériques en chaînes, champs inconnus conservés)
│ ├── Networking/ HTTPTransport (URLSession éphémère), APIClient (cookie → trousseau, Origin, erreurs, ré-auth), Endpoints typés
│ ├── Authentication/ AuthService : cérémonies WebAuthn (options → authentificateur → vérification), sessions, passkeys
│ ├── Streaming/ SSEParser (octets → événements), ChatEvent, MessageAccumulator, GenerationEngine (tour complet + reprise)
│ ├── Persistence/ CacheStore (SQLite + FTS5) : listes, fils complets, catalogues, recherche hors ligne
│ ├── Security/ SecretStore (trousseau), FileValidator (type sur octets réels), Redactor (journaux sans secrets)
│ ├── Markdown/ MarkdownParser (blocs, math protégée, découpage incrémental), SyntaxHighlighter
│ └── Export/ export Markdown / JSON local
├── Features/ 26 fichiers — Account · Conversations · Chat · ModelSelector · Attachments · Search · Settings · Workspace
├── Components/ 6 fichiers — DesignSystem, SidebarView, MessageView, ComposerView, MarkdownView, MathView
├── Resources/ Info.plist, entitlements (Release / Debug), Assets.xcassets (AppIcon clair + sombre, AccentColor)
└── Tests/ CoreTests (Swift Testing), AppTests (XCTest hébergé), UITests (XCUITest)
Scripts/ build, tests, performance, provisionnement, signature, notarisation
docs/ matrice de parité, architecture, sécurité, tests, installation, mises à jour, notes de version, brand/
project.yml définition XcodeGen · Package.swift / Package.resolved : paquet SPChatCore🛠 Développer
Il faut Xcode 27 et XcodeGen.
Scripts/build.sh debug # génère SPChat.xcodeproj et compile en Debug
Scripts/build.sh core-test # 167 tests du cœur (swift test, ~1 s)
Scripts/build.sh app-test # 65 tests hébergés dans l'app
Scripts/integration-test.sh # parcours complet contre le backend de DÉVELOPPEMENT (WebAuthn logiciel, vrais modèles)
Scripts/ui-test.sh # XCUITest contre le backend de développement
Scripts/run-dev.sh # lance le build Debug sur le backend de développement (session de dev, sans Touch ID)
Scripts/perf.sh launch|stream # temps de lancement, mémoire, trace Instruments d'un long streaming
Scripts/release.sh && Scripts/verify-release.sh && Scripts/notarize.sh # archive signée → contrôles → notarisation + DMGLes builds Debug ont leur propre identifiant (ai.spboucher.spchat.debug) et ne peuvent viser qu'un serveur en boucle
locale ; ils n'ont pas le droit « Associated Domains », donc pas de passkey : la session de développement est injectée.
| Script | Rôle |
|---|---|
Scripts/build.sh |
point d'entrée de développement : generate, debug, core-test, app-test, ui-test |
Scripts/check-headers.sh |
échoue si un fichier source maison n'a pas l'en-tête d'auteur (Author / File / Description) |
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) |
Scripts/integration-test.sh |
tests de bout en bout du cœur contre le backend de développement (jamais la production) |
Scripts/ui-test.sh |
suite XCUITest sur l'app Debug contre le backend de développement |
Scripts/run-dev.sh |
lance le build Debug avec une session de développement, capture d'écran optionnelle |
Scripts/perf.sh |
temps de lancement, mémoire au repos, trace xctrace Time Profiler d'une longue réponse |
Scripts/provision.py · Scripts/asc.py |
identifiant, capacité Associated Domains et profil Developer ID par l'API App Store Connect (clé existante) |
Scripts/release.sh |
archive Release signée avec l'identité Developer ID existante et le profil de provisionnement |
Scripts/verify-release.sh |
contrôles du binaire signé : signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets |
Scripts/notarize.sh |
notarisation de l'app, agrafage, DMG signé, notarisation et agrafage du DMG, fichier .sha256 |
Scripts/window-shot.swift |
capture la fenêtre au premier plan d'une app nommée (preuve des contrôles visuels) |
⚙️ Configuration
| Réglage | Valeur | Où |
|---|---|---|
| Identifiant (Release) | ai.spboucher.spchat |
project.yml |
| 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 |
| Équipe | 3YM54G49SN |
project.yml |
| Version | MARKETING_VERSION 2.0.0 · CURRENT_PROJECT_VERSION 2 |
project.yml |
| Cible de déploiement | macOS 15.0 | project.yml |
| Langue de développement | fr |
project.yml |
| 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 |
| Domaine associé | webcredentials:chat.spboucher.ai (Release seulement) |
SPChat/Resources/SPChat.entitlements |
| Schéma d'URL | spchat:// |
SPChat/Resources/Info.plist |
| Catégorie | public.app-category.productivity |
SPChat/Resources/Info.plist |
| Flux de mise à jour | clé SPChatUpdateFeedURL, vide en 1.0 |
docs/UPDATES.md |
| Profil de notarisation | profil trousseau notarytool nommé « MacLustr-Notarize » (existant, rien n'est créé) |
Scripts/notarize.sh |
Aucune variable d'environnement ni clé d'API n'est nécessaire à l'exécution : les fournisseurs sont appelés par le serveur.
🖥 Écrans
| Zone | Fichiers | Contenu |
|---|---|---|
| Fenêtre principale | App/MainWindow.swift, Components/SidebarView.swift |
NavigationSplitView : historique groupé par date, épinglées d'abord, filtres |
| Conversation | Features/Chat/ChatScreen.swift, Components/MessageView.swift, Components/ComposerView.swift |
transcription, compositeur, inspecteur (⌥⌘I) |
| Chat rapide | Features/Chat/QuickChat.swift |
panneau flottant |
| Connexion | Features/Account/LoginView.swift |
clé d'accès, première connexion par code, code de récupération |
| Sélecteur de modèles | Features/ModelSelector/ModelPickerView.swift |
par fournisseur, recherche, favoris, défaut (⇧⌘M) |
| Palette | Features/Search/CommandPalette.swift |
commandes, modèles, conversations, recherche floue (⌘K) |
| Réglages | Features/Settings/SettingsView.swift |
préférences, sécurité (passkeys, appareils, journal), mémoire, dépenses, données |
Les 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) :
| Écran | Fichier | Écran | Fichier |
|---|---|---|---|
| Projets | ProjectsScreen.swift |
Modèles (laboratoire) | ModelsScreen.swift |
| Prompts | PromptsScreen.swift |
Utilisation (Swift Charts) | UsageScreen.swift |
| Profils d'usage | PresetsScreen.swift |
Comparer | CompareScreen.swift |
| Fichiers | FilesScreen.swift |
Recherche approfondie | ResearchScreen.swift |
| Mémoire | MemoryScreen.swift |
Images | ImagesScreen.swift |
🔌 API consommée
L'app est un client de l'API du dépôt chat-spboucher-ai ; elle n'expose
aucun serveur. Les chemins sont typés dans SPChat/Core/Networking/Endpoints.swift (26 préfixes /api/… distincts),
les cérémonies d'authentification dans Core/Authentication/AuthService.swift, le streaming dans
Core/Streaming/GenerationEngine.swift.
| Domaine | Chemins |
|---|---|
| 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 |
| Conversation | /api/chat, /api/chat/stream, /api/chat/cancel, /api/chat/edit, /api/chat/regenerate, /api/chat/approve |
| Conversations | /api/conversations, /api/conversations/:id, /api/search, /api/drafts |
| Catalogue | /api/models, /api/models/refresh, /api/presets, /api/prompts, /api/settings |
| Contenus | /api/attachments, /api/artifacts/:id, /api/images, /api/memories, /api/memories/export, /api/projects |
| Voix | /api/stt, /api/tts |
| Compte | /api/owner, /api/usage, /api/health |
Règles respectées par APIClient : Origin: https://chat.spboucher.ai sur chaque mutation ; 401 locked → jeton
effacé et retour à l'écran de connexion ; 403 reauth_required → la clé d'accès est demandée une fois puis la requête
est rejouée ; HTTPS obligatoire hors boucle locale.
🗄 Données locales
| Donnée | Emplacement | Détail |
|---|---|---|
| Jeton de session | trousseau du Mac, élément « ai.spboucher.spchat » | kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, non synchronisé |
| 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 |
| Préférences | conteneur de l'app | persistées sans secret |
| Cookies de cérémonie | mémoire seulement | session URLSession éphémère : ni cookies, ni cache, ni identifiants sur disque |
À la fin de session (déconnexion, session révoquée ou expirée) : jeton effacé, cache SQLite vidé (secure_delete,
VACUUM, troncature du WAL), fichiers en cache supprimés.
🛡 Sécurité et vie privée
Détail : docs/SECURITY.md.
| Sujet | Choix |
|---|---|
| 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 |
| Hardened Runtime | activé, aucune exception (disable-library-validation, JIT, mémoire exécutable : absents) |
| 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 |
| Validation serveur | inchangée : défi à usage unique, origine et RP id exacts, signature vérifiée par @simplewebauthn/server |
| TLS | validation système, TLS ≥ 1.2, jamais de contournement. HTTP refusé sauf boucle locale (développement) |
| CSRF | Origin exact sur chaque mutation (exigence du serveur) |
| 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 |
| 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 |
| 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 |
| Clés d'API | aucune dans l'app ni dans le dépôt ; Scripts/verify-release.sh recherche des secrets dans le bundle |
| Journaux | pas de contenu de message ni de jeton ; Redactor masque cookies, jetons et clés |
| 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é |
✅ Tests
Rapport complet, preuves et points non vérifiés : docs/TEST_REPORT.md (17 novembre 2026, MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2).
| Suite | Commande | Résultat rapporté |
|---|---|---|
| Cœur, unitaires (Swift Testing) | Scripts/build.sh core-test |
167 / 167 en ~1 s (2.0) |
| Cœur, intégration bout en bout | Scripts/integration-test.sh |
1 / 1 (≈ 15–18 s, vrais appels de modèle) |
| App, tests hébergés (XCTest) | Scripts/build.sh app-test |
65 / 65 (2.0) |
| Interface (XCUITest) | Scripts/ui-test.sh |
2 / 2 (≈ 45 s) |
| Contrôles du binaire signé | Scripts/verify-release.sh |
13 contrôles, 0 échec |
| En-têtes de fichiers | Scripts/check-headers.sh |
OK |
Répartition des 73 @Test de SPChat/Tests/CoreTests/ : Markdown 20 · moteur de génération 13 · streaming 11 ·
décodage des modèles 10 · réseau 10 · authentification et cache 8 · intégration 1. Les 27 tests hébergés sont dans
SPChat/Tests/AppTests/ (AppStateTests.swift, ChatFlowTests.swift), les 2 tests d'interface dans
SPChat/Tests/UITests/SPChatUITests.swift.
Ce que chaque suite prouve
Unitaires du cœur — décodage des charges réelles du serveur ; analyseur SSE découpé à chaque octet y compris au
milieu d'un caractère UTF-8 ; accumulation du message (rejeu après reconnexion sans doublon) ; pot de cookies (jeton dans
le magasin secret seulement, rotation, expiration) ; HTTPS obligatoire hors boucle locale ; Origin sur les mutations ;
session verrouillée → jeton effacé ; ré-authentification unique sans boucle ; moteur de génération : clé d'idempotence
identique sur les nouvelles tentatives, coupure en pleine réponse reprise à after=<index> sans perte ni doublon,
run disparu, connexion muette abandonnée, annulation ; cérémonies WebAuthn avec un authentificateur logiciel ; cache
SQLite (ordre, filtres, recherche plein texte sans diacritiques, entrée hostile, effacement vérifié dans le fichier,
4 000 messages) ; Markdown (tableaux, math protégée, monnaie ≠ math, $ dans le code, HTML jamais interprété, découpage
stable pendant le streaming) ; politique de liens ; coloration ; détection de type de fichier ; rédaction des journaux ;
exports.
Intégration (vrai backend de développement) — API verrouillée sans session ; mauvais code refusé ; enrôlement d'une passkey (signature P-256 réellement vérifiée par le serveur) ; déconnexion → l'ancien jeton est refusé ; reconnexion par passkey ; passkeys, appareils, codes de récupération, journal ; catalogue ; téléversement (fichier binaire refusé en 415) ; message réel streamé utilisant la pièce jointe ; régénération et versions ; modification ; arrêt en cours de génération ; renommer, épingler, favori, recherche, brouillon, export ; cache hors ligne ; branche, archive, suppression ; révocation de l'appareil → session terminée.
Hébergés dans l'app — envoi → streaming → état final → cache ; 3 000 événements de jetons ne provoquent pas plus de ~30 mises à jour d'écran par seconde ; texte et fichiers rendus au compositeur quand rien n'est parti ; refus 402 affiché ; arrêt ; régénération avec un autre modèle, versions, modification ; rattachement à une génération encore en cours ; ouverture hors ligne depuis le cache ; approbation d'outil ; préparation des pièces jointes (photo de 3000 × 2000 réduite à 2048 px) ; session expirée ou révoquée → déconnexion et cache vidé ; liens profonds strictement validés ; deux fenêtres partageant une conversation ; palette floue ; PDF paginé à texte sélectionnable ; copie RTF ; composition LaTeX à la bonne taille.
Interface (vraie app, vrais événements clavier) — historique listé ; frappe et envoi par Retour ; réponse streamée puis stabilisée ; commandes de menu activées selon la conversation ; ⌘K → palette → écran Utilisation ; ⌘N ; ⌘F ; ⌘, ; ⇧⌘N ; lancement avec serveur injoignable : app utilisable, indicateur hors ligne, échec expliqué et texte rendu au compositeur.
Validation manuelle sur la production (17 nov. 2026) — connexion par clé d'accès avec Touch ID dans le binaire signé ; historique du site visible dans l'app ; session conservée entre deux lancements ; installation depuis le DMG.
⚡ Performances
Mesures du rapport de tests (docs/TEST_REPORT.md).
| Mesure | Résultat | Méthode |
|---|---|---|
| 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 |
| Empreinte mémoire au repos, connecté | 61–65 Mo (RSS 122–126 Mo) | footprint, ps |
| 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) |
| Fenêtre présente après arrêt forcé puis relance | 10 / 10 | boucle kill -9 + open |
Lecture : le coût pendant le streaming est celui de la mise en page SwiftUI du dernier bloc, à 30 images/s ; rien n'est recalculé pour les messages et blocs déjà affichés.
🚀 Publication
Chaîne reproductible (docs/UPDATES.md) :
# 1. version : MARKETING_VERSION / CURRENT_PROJECT_VERSION dans project.yml
Scripts/build.sh core-test && Scripts/build.sh app-test && Scripts/integration-test.sh && Scripts/ui-test.sh
Scripts/provision.py # idempotent : identifiant, capacité Associated Domains, profil Developer ID (clé API App Store Connect existante)
Scripts/release.sh # archive Release signée (identité Developer ID du trousseau + profil), dist/SP Chat.app
Scripts/verify-release.sh # signature, runtime durci, bac à sable, droits, profil, absence de moteur web et de secrets
Scripts/notarize.sh # notarytool (profil trousseau « MacLustr-Notarize ») → agrafage → DMG signé → notarisation → agrafage
spctl -a -vv -t exec "dist/SP Chat.app" && spctl -a -vv -t open --context context:primary-signature dist/SPChat-<version>.dmgRien n'est créé côté certificats : release.sh échoue s'il n'existe pas d'identité « Developer ID Application ».
provision.py remplace le profil si Apple l'a invalidé (c'est le cas dès qu'une capacité de l'identifiant change —
l'identifiant ai.spboucher.spchat est partagé avec l'app iOS).
Publication : pousser le dépôt et l'étiquette v<version> sur spbgit, puis déposer SPChat-<version>.dmg et son
.sha256 dans M1M32:~/srv/spbgit/data/releases/sp-chat/v<version>/.
| État de la 1.0.0 (1) | |
|---|---|
| Étiquette | v1.0.0 |
| Identité | Developer ID Application: Simon-Pierre Boucher (3YM54G49SN) — certificat existant, aucun créé |
| Profil | « SP Chat Developer ID » (MAC_APP_DIRECT, Associated Domains), embarqué |
| Notarisation | app et DMG Accepted ; stapler validate OK pour les deux |
| Gatekeeper | spctl : accepted, source=Notarized Developer ID (app, DMG, app du DMG monté) |
| DMG | dist/SPChat-1.0.0.dmg, 10,6 Mo |
Mettre à jour (1.0) — manuel : télécharger le nouveau DMG et remplacer l'app dans Applications. La session (trousseau) et les préférences sont conservées ; le cache local est reconstruit si son schéma change.
🩺 Dépannage
| Symptôme | Cause | Remède |
|---|---|---|
| « 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) |
| La feuille Touch ID ne propose aucune clé | La clé d'accès n'est pas sur ce Mac | Voir « Sur un autre Mac » |
| « 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 |
| 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 |
| 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 |
| 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) |
| 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) |
| 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) |
🚧 Limites connues et suite prévue
Écarts assumés avec le site (docs/FEATURE_MATRIX.md) :
- 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.
- Sélection continue sur plusieurs blocs : limite de
TextSwiftUI ; compensée par la copie de la réponse entière. - Sous-fonctions secondaires de Comparer, Recherche, Images, Projets, Utilisation et du laboratoire de modèles.
- 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.
- Interface en français uniquement (comme le site).
Limites de sécurité (docs/SECURITY.md) :
- Le cache SQLite n'est pas chiffré par l'application : il repose sur le bac à sable et FileVault. Il est vidé à la déconnexion.
- Les fichiers ouverts avec Coup d'œil sont copiés dans le dossier temporaire du conteneur (purgé par le système).
- L'app fait confiance au serveur configuré en dur (
chat.spboucher.ai) ; il n'y a pas d'épinglage de certificat.
Non vérifié (extrait de docs/TEST_REPORT.md)
- 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.
- Écrans de l'espace de travail : compilés et relus, non exercés contre le serveur, sauf Utilisation (ouvert par le test d'interface).
- 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.
- Restauration des fenêtres après un redémarrage, plein écran, onglets de fenêtres.
- VoiceOver : libellés posés sur les contrôles, aucun audit avec le lecteur d'écran.
- Enrôlement d'une passkey dans le binaire signé (seule la connexion l'a été) ; connexion par clé de sécurité matérielle.
- Fournisseurs OpenAI et xAI en conversation réelle depuis l'app (tests réels faits avec Anthropic).
- Instrument Leaks, mesure d'énergie, conversations réelles de plusieurs milliers de messages à l'écran.
Mise à jour automatique (prévue, non livrée) — l'architecture réserve le point d'entrée : clé SPChatUpdateFeedURL
d'Info.plist (vide en 1.0) et UpdateChecker (Features/Settings/SettingsView.swift). Conception retenue :
- un flux appcast servi en HTTPS par git.spboucher.ai, chaque entrée portant version, URL du DMG, taille et signature EdDSA ;
- 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 ;
- l'archive téléchargée doit en plus être signée par la même équipe Developer ID et notarisée (vérification
SecStaticCodeavant remplacement) ; - installation par un assistant hors bac à sable (service XPC), comme le fait Sparkle 2 pour les apps sandboxées.
Tant que ces quatre garanties ne sont pas en place, l'app n'installe rien d'elle-même.
👤 Auteur
Simon-Pierre Boucher — conception, développement, exploitation
📄 Licence
© 2026 Simon-Pierre Boucher — logiciel privé. Tous droits réservés.