# 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](https://tauri.app). 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

```
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](/docs/engineering/architecture/) avant de toucher à `packages/` : cet article couvre le motif des ports, le registre de contributions et le câblage des alias.

## 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](https://rustup.rs)
- Les [dépendances système de Tauri 2](https://v2.tauri.app/start/prerequisites/) pour votre système d'exploitation
- Facultatif pendant la configuration : [pandoc](https://pandoc.org/installing.html) pour la compilation PDF de Markdown et l'export de documents (l'application peut installer sa version épinglée à la demande)

## Premier lancement

```bash
pnpm install
./scripts/fetch-tectonic.sh all
./scripts/fetch-biber.sh all
./scripts/fetch-typst.sh all
pnpm language-servers:fetch
pnpm tauri dev
```

Pour 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

```bash
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 bundle
```

### Vérifications avant d'ouvrir une PR

Lancez les vérifications locales pertinentes avant d'ouvrir une pull request :

```bash
pnpm build                                # frontend typecheck (noUnusedLocals/Parameters on)
pnpm test                                 # vitest across src/ and packages/
pnpm audit --prod --audit-level high      # registry-backed npm advisory check
cargo check --workspace --all-targets     # Rust workspace compiles
cargo deny --manifest-path src-tauri/Cargo.toml check  # Rust advisories, licenses, and sources
```

Les 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](https://github.com/Oleafly/Oleafly/blob/main/e2e/README.md).

```bash
pnpm test:e2e:app                         # builds + launches the app, runs Playwright, tears down
```

## Comment fonctionne une compilation

1. Le frontend charge le descripteur `project_engine` du backend et ses indicateurs de capacité, puis appelle `compileProject(projectId, mainDoc, offline)` via l'IPC de Tauri.
2. 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.
3. 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`, `kpsewhich` et Biber avant d'accorder cette priorité.
4. 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 un `typst` système qui rapporte cette version. Il compile le document principal `.typ` sélectionné avec des diagnostics lisibles et un chemin de sortie PDF explicite. Avec la compilation automatique activée, Rust garde plutôt un processus `typst watch` par projet (`src-tauri/src/typst_watch.rs`). Le fichier `docs/typst-toolchain.md` du dépôt de l'application couvre la résolution, les épinglages et le Tinymist correspondant.
5. 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 un `pdflatex` systè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](https://v2.tauri.app/develop/sidecar/) 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.

6. 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.
7. 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](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

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

- Configuration : `~/.oleafly/config.json` (`0600` sur Unix). Les préférences
  non secrètes vivent ici.
- Secrets : `~/.oleafly/ai-secrets.json` et
  `~/.oleafly/app-secrets.json`, chiffrés avec la clé
  `~/.oleafly/ai-secrets.key` réservée au propriétaire. GitHub et MCP partagent
  `app-secrets.json`. Les identifiants des fournisseurs d'IA utilisent
  `ai-secrets.json`.
- Projets : `~/.oleafly/projects/<id>/`, de simples dossiers avec `.git`.
- Journal de l'application : `~/.oleafly/app.log`.

## 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 dans `packages/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 dans `src-tauri/src/lib.rs`, encapsuler dans `src/lib/tauri.ts`.
- Ajouter un moteur de document → implémenter `DocumentEngine` dans `src-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.json` dans `src-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 par `AiToolsHost` dans `src/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](/docs/engineering/architecture/#the-contribution-registry)).

## 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

- 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`, `Tooltip` et `Select`.

## 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](/docs/engineering/releasing/) et [installation](/docs/install/) côté utilisateur.
