Développement
Configurez le dépôt de l'application de bureau Oleafly, récupérez ses sidecars épinglés, lancez l'application et découvrez ses principaux points d'extension.
Oleafly est une application de bureau Tauri 2 (s’ouvre dans un nouvel onglet). Son frontend React et TypeScript communique avec Rust via l’IPC de Tauri. Rust gère les fichiers de projet, la compilation, les secrets, le routage MCP et les requêtes vers les fournisseurs d’IA.
Organisation du dépôt
Section intitulée « Organisation du dépôt »Oleafly/├── src/ React app shell (stores, Tauri client, UI kit, port adapters)│ ├── components/ ui (shadcn-style), layout, editor glue, preview panes, ai│ ├── contributions/ registers rail tabs / commands / AI toolsets into the registry│ ├── features/ compile, synctex, export│ ├── lib/ tauri wrappers, github, spellcheck, utils, package shims│ └── store/ zustand stores├── packages/ @oleafly/* frontend packages consumed as TS source│ ├── latex/ latex-intelligence/ ai-core/ ai-tools/ registry/│ └── editor/ preview/ diagram/ preflight/ pdf-to-latex/ templates/ wysiwyg/├── crates/│ └── oleafly-agent/ provider clients, streaming, and agent orchestration├── src-tauri/│ ├── src/ Tauri commands, engines, config, Git, MCP, paths, projects│ ├── binaries/ fetched Tectonic, Biber, and Typst sidecars│ ├── resources/ templates, dictionaries, TeX data, language servers│ └── tauri.conf.json├── scripts/fetch-tectonic.sh├── scripts/fetch-biber.sh├── scripts/fetch-typst.sh├── scripts/fetch-language-servers.mjs└── docs/Le frontend est un workspace pnpm. Les fonctionnalités réutilisables vivent dans packages/* derrière des ports injectés, et le shell de l’application les assemble. Lisez Architecture du frontend avant de toucher à packages/ : cet article couvre le motif des ports, le registre de contributions et le câblage des alias.
Prérequis
Section intitulée « Prérequis »- Node.js 22.13+ et pnpm 11.9+ (la version exacte de pnpm est déclarée dans
package.json) - Rust (stable) via rustup (s’ouvre dans un nouvel onglet)
- Les dépendances système de Tauri 2 (s’ouvre dans un nouvel onglet) pour votre système d’exploitation
- Facultatif pendant la configuration : pandoc (s’ouvre dans un nouvel onglet) pour la compilation PDF de Markdown et l’export de documents (l’application peut installer sa version épinglée à la demande)
Premier lancement
Section intitulée « Premier lancement »pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devPour une seule plateforme, passez le triplet cible Rust de celle-ci à chaque script shell de récupération. Utilisez rustc -vV pour trouver le triplet de l’hôte. La commande des serveurs de langage sélectionne l’hôte actuel, sauf si vous transmettez une cible au script sous-jacent.
Au quotidien
Section intitulée « Au quotidien »pnpm tauri dev # run the app with hot reload (frontend) + cargo incremental (backend)pnpm build # typecheck + build the frontend (tsc -b && vite build)pnpm tauri build # produce a distributable bundleVérifications avant d’ouvrir une PR
Section intitulée « Vérifications avant d’ouvrir une PR »Lancez les vérifications locales pertinentes avant d’ouvrir une pull request :
pnpm build # frontend typecheck (noUnusedLocals/Parameters on)pnpm test # vitest across src/ and packages/pnpm audit --prod --audit-level high # registry-backed npm advisory checkcargo check --workspace --all-targets # Rust workspace compilescargo deny --manifest-path src-tauri/Cargo.toml check # Rust advisories, licenses, and sourcesLes deux commandes d’audit exigent un accès au registre et au réseau. La CI enregistre leurs résultats courants à chaque changement de code. Une exécution locale hors ligne ne peut pas certifier que le graphe de dépendances est exempt d’avis de sécurité.
Pour les changements visibles par les utilisateurs, lancez aussi la suite de bout en bout contre l’application et le compilateur réels. Voir e2e/README.md (s’ouvre dans un nouvel onglet).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downComment fonctionne une compilation
Section intitulée « Comment fonctionne une compilation »- Le frontend charge le descripteur
project_enginedu backend et ses indicateurs de capacité, puis appellecompileProject(projectId, mainDoc, offline)via l’IPC de Tauri. - Rust effectue la répartition via
DocumentEngine. Le code de l’interface ne doit pas déduire le comportement d’un moteur d’un nom de fichier. - LaTeX utilise le Tectonic intégré par défaut. Un projet peut sinon choisir pdfLaTeX, XeLaTeX ou LuaLaTeX via
latexmk. Une installation TeX système complète prend la priorité sur le TinyTeX géré par Oleafly. Le détecteur partagé exige les compilateurs de base,latexmk,kpsewhichet Biber avant d’accorder cette priorité. - Typst exécute exactement la version que le projet épingle dans
project.json: le sidecar intégré, un téléchargement vérifié par somme de contrôle, ou untypstsystème qui rapporte cette version. Il compile le document principal.typsélectionné avec des diagnostics lisibles et un chemin de sortie PDF explicite. Avec la compilation automatique activée, Rust garde plutôt un processustypst watchpar projet (src-tauri/src/typst_watch.rs). Le fichierdocs/typst-toolchain.mddu dépôt de l’application couvre la résolution, les épinglages et le Tinymist correspondant. - Markdown appelle Pandoc directement sur
.md/.markdown, avec un chemin de sortie explicite et--pdf-engine=<absolute bundled Tectonic path>. Le manuel de Pandoc prend explicitement en charge un chemin complet de moteur PDF. Ne remplacez pas cela par unpdflatexsystème implicite, car la version empaquetée d’Oleafly ne doit pas dépendre d’une installation TeX non déclarée. Le processus s’exécute avec la racine du projet comme répertoire de travail, pour que les images, les fichiers de bibliographie et les fichiers CSL relatifs fonctionnent aussi bien pour les documents principaux à la racine que pour ceux imbriqués.
La documentation des sidecars de Tauri (s’ouvre dans un nouvel onglet) définit
les entrées bundle.externalBin avec des suffixes de triplet cible et expose le
sidecar empaqueté sous son nom sans suffixe à l’exécution. L’adaptateur Pandoc
d’Oleafly résout cet exécutable Tectonic empaqueté à côté de l’exécutable de
l’application, conformément à la disposition du bundle de bureau de Tauri. Les
tests unitaires couvrent les candidats de bundle d’app macOS et de build
debug/release de Cargo, tandis que le workflow de publication inspecte, sur
chaque cible, le voisin sans suffixe qui a été préparé.
Les téléchargements de Tectonic, Biber, Typst et des serveurs de langage sont versionnés et épinglés par somme de contrôle. Leurs scripts de récupération valident la structure des archives et n’extraient que les chemins d’exécutables ou de ressources vérifiés. La CI et les builds de publication utilisent les mêmes scripts.
- Tous les moteurs diffusent des événements de journal et d’erreur normalisés. Rust renvoie les métadonnées de compilation via l’IPC JSON. Le PDF lui-même est récupéré séparément en IPC binaire brut plutôt qu’intégré en base64 dans le résultat.
- Le frontend affiche les octets du PDF avec pdf.js et publie les diagnostics normalisés vers CodeMirror.
Les descripteurs de moteur modélisent la politique de compilation ainsi que les profils de formatage et de prévérification du source, et les ensembles de fonctionnalités, d’export et de types de modèle. Les consommateurs du frontend utilisent le descripteur du magasin de fichiers à échec fermé plutôt que de deviner d’après les extensions. Voir la matrice des moteurs de document (s’ouvre dans un nouvel onglet).
Typst rapporte supports_synctex=true et supports_offline=true, avec
supports_isolated_compile=false. La synchronisation source-PDF passe par le
Tinymist correspondant du projet et exige Tinymist 0.13.30 ou une version
ultérieure ; typst_toolchain::describe_project abaisse donc supports_synctex
à false pour un projet épinglé sur Typst 0.11 ou 0.12
(typst_sync::supported_for_project). Le mode hors ligne bloque les
téléchargements de paquets Typst : une compilation utilise alors uniquement le
cache de paquets partagé et le dossier typst-packages du projet. La
compilation isolée reste réservée à LaTeX : le chemin des figures TikZ refuse
les projets Typst, et les outils de figures de l’assistant affichent les
extraits Typst, comme un canevas CeTZ ou un diagramme fletcher, avec
render_typst_snippet à la place. N’ajoutez un comportement de moteur qu’une
fois que la capacité du backend devient véridique. N’ajoutez pas d’exceptions
d’interface fondées sur les extensions.
Où vit l’état
Section intitulée « Où vit l’état »- Configuration :
~/.oleafly/config.json(0600sur Unix). Les préférences non secrètes vivent ici. - Secrets :
~/.oleafly/ai-secrets.jsonet~/.oleafly/app-secrets.json, chiffrés avec la clé~/.oleafly/ai-secrets.keyréservée au propriétaire. GitHub et MCP partagentapp-secrets.json. Les identifiants des fournisseurs d’IA utilisentai-secrets.json. - Projets :
~/.oleafly/projects/<id>/, de simples dossiers avec.git. - Journal de l’application :
~/.oleafly/app.log.
Principaux points d’extension
Section intitulée « Principaux points d’extension »- Ajouter un fournisseur d’IA → mettre à jour
crates/oleafly-agent/src/provider.rs, puis répliquer ses métadonnées d’affichage danspackages/ai-core/src/providers.ts. Le test de parité des catalogues garde les deux listes alignées. - Ajouter une commande Tauri → déclarer dans
src-tauri/src/*.rs, enregistrer danssrc-tauri/src/lib.rs, encapsuler danssrc/lib/tauri.ts. - Ajouter un moteur de document → implémenter
DocumentEnginedanssrc-tauri/src/document_engine.rs, exposer des capacités véridiques, ajouter un chemin de récupération et de test de fumée du sidecar épinglé par somme de contrôle, puis consommer le descripteur dans les contrôles de l’interface. - Ajouter un modèle de projet → déposer un dossier avec un manifeste
template.jsondanssrc-tauri/resources/templates/(les métadonnées de modèle indépendantes du moteur restent un travail prévu). - Ajouter un outil pour l’IA →
packages/ai-tools/src/tools.ts. Les services de l’application dont il a besoin passent parAiToolsHostdanssrc/lib/ai-tools.ts. - Ajouter un onglet de rail, une commande de palette ou d’omnibar ou un ensemble d’outils IA → l’enregistrer dans
src/contributions/(voir Architecture du frontend).
Synchronisation et fonctionnement interne de GitHub
Section intitulée « Synchronisation et fonctionnement interne de GitHub »Le flux d’appareil OAuth s’exécute côté serveur en Rust (src-tauri/src/github.rs) parce que les points de terminaison OAuth ne prennent pas CORS en charge. Les appels d’API (api.github.com) se font depuis le frontend.
Style de code
Section intitulée « Style de code »- TypeScript : suivez ce qui existe déjà. Pas de commentaires sauf demande. Respectez
noUnusedLocals/noUnusedParameters. - Rust : idiomatique, commandes courtes, messages d’erreur conviviaux.
- Interface : Tailwind v4 + jetons Geist. Réutilisez les primitives
Button,TooltipetSelect.
Publication
Section intitulée « Publication »L’empaquetage cible macOS Apple Silicon, Windows x64, Linux x64 et Linux ARM64. Chaque build récupère et vérifie ses sidecars de compilation et sa ressource intégrée de serveurs de langage. Les builds de publication prennent en charge la signature et la notarisation Apple sur macOS et Azure Artifact Signing sur Windows. Voir publication et installation côté utilisateur.