# Desarrollo

Configura el repositorio de escritorio de Oleafly, descarga sus sidecars fijados, ejecuta la app y conoce los principales puntos de extensión.

Oleafly es una app de escritorio hecha con [Tauri 2](https://tauri.app). Su frontend en React y TypeScript habla con Rust mediante IPC de Tauri. Rust se encarga de los archivos del proyecto, la compilación, los secretos, el enrutamiento de MCP y las solicitudes a los proveedores de IA.

## Estructura del repositorio

```
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/
```

El frontend es un espacio de trabajo de pnpm. Las funciones reutilizables viven en `packages/*` detrás de puertos inyectados, y el shell de la app las conecta entre sí. Lee
[Arquitectura del frontend](/docs/engineering/architecture/) antes de tocar `packages/`: explica
el patrón de puertos, el registro de contribuciones y la configuración de alias.

## Requisitos previos

- Node.js 22.13+ y pnpm 11.9+ (la versión exacta de pnpm está declarada en
  `package.json`)
- Rust (stable) mediante [rustup](https://rustup.rs)
- Las [dependencias del sistema de Tauri 2](https://v2.tauri.app/start/prerequisites/) para tu sistema operativo
- Opcional durante la configuración: [pandoc](https://pandoc.org/installing.html) para compilar Markdown a PDF y para exportar documentos (la app puede instalar su versión fijada cuando se necesite)

## Primera ejecución

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

Para una sola plataforma, pasa su triple de destino de Rust a cada script de descarga de shell. Usa `rustc -vV` para averiguar el triple del host. El comando de los servidores de lenguaje selecciona el host actual salvo que pases un destino a través de su script subyacente.

## Día a día

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

### Comprobaciones antes de abrir un PR

Ejecuta las comprobaciones locales pertinentes antes de abrir un 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
```

Los dos comandos de auditoría necesitan acceso al registro y a la red. CI registra
sus resultados actuales en cada cambio de código. Una ejecución local sin conexión no puede certificar que
el grafo de dependencias esté libre de avisos de seguridad.

Para los cambios visibles para el usuario, ejecuta también la suite de extremo a extremo contra la app real y el compilador. Consulta [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
```

## Cómo funciona una compilación

1. El frontend carga el descriptor `project_engine` del backend y sus indicadores de capacidad, y luego llama a `compileProject(projectId, mainDoc, offline)` mediante IPC de Tauri.
2. Rust despacha a través de `DocumentEngine`. El código de la interfaz no debe deducir el comportamiento del motor a partir del nombre de un archivo.
3. LaTeX usa Tectonic incluido de forma predeterminada. Un proyecto puede elegir en su lugar pdfLaTeX, XeLaTeX o LuaLaTeX mediante `latexmk`. Una instalación completa de TeX en el sistema tiene prioridad sobre el TinyTeX administrado por Oleafly. El detector compartido exige los compiladores principales, `latexmk`, `kpsewhich` y Biber antes de conceder esa prioridad.
4. Typst ejecuta la versión exacta que el proyecto fija en `project.json`: el sidecar incluido, una descarga con suma de verificación comprobada o un `typst` del sistema que informe esa versión. Compila el documento principal `.typ` seleccionado, con diagnósticos legibles y una ruta de salida del PDF explícita. Con la Compilación automática activada, Rust mantiene en su lugar un único proceso `typst watch` por proyecto (`src-tauri/src/typst_watch.rs`). El archivo `docs/typst-toolchain.md` del repositorio de escritorio explica la resolución, las versiones fijadas y el Tinymist correspondiente.
5. Markdown invoca Pandoc directamente sobre `.md`/`.markdown`, con una
   ruta de salida explícita y `--pdf-engine=<absolute bundled Tectonic path>`. El
   manual de Pandoc admite expresamente una ruta completa al motor de PDF. No lo sustituyas por un
   `pdflatex` implícito del sistema, porque Oleafly empaquetado no debe depender de una
   instalación de TeX sin declarar. El proceso se ejecuta con la raíz del proyecto como
   directorio de trabajo, para que las imágenes relativas, los archivos de bibliografía y los archivos CSL funcionen
   tanto con documentos principales en la raíz como anidados.

La [documentación de sidecars](https://v2.tauri.app/develop/sidecar/) de Tauri define
las entradas de `bundle.externalBin` con sufijos de triple de destino y expone el sidecar
empaquetado con su nombre sin sufijo en tiempo de ejecución. El adaptador de Pandoc de Oleafly resuelve
ese ejecutable de Tectonic empaquetado junto al ejecutable de la aplicación, igual que el diseño del paquete de escritorio de
Tauri. Las pruebas unitarias cubren los candidatos del paquete de app de macOS y de Cargo
debug/release, mientras que el flujo de trabajo de lanzamiento inspecciona el archivo hermano sin sufijo
preparado en cada destino.

Las descargas de Tectonic, Biber, Typst y los servidores de lenguaje están versionadas y fijadas por suma de verificación. Sus scripts de descarga validan la estructura del archivo comprimido y extraen solo los ejecutables o rutas de recursos revisados. CI y las compilaciones de lanzamiento usan los mismos scripts.

6. Todos los motores emiten eventos normalizados de registro y de error. Rust devuelve los metadatos de la compilación mediante IPC JSON. El PDF se obtiene por separado como IPC binario sin procesar, en lugar de incrustarse en base64 en el resultado.
7. El frontend renderiza los bytes del PDF con pdf.js y publica los diagnósticos normalizados en CodeMirror.

Los descriptores de motor modelan la política de compilación, además de los perfiles de formato y de verificación previa del código fuente y los conjuntos de funciones, exportaciones y tipos de plantilla. Los consumidores del frontend usan el descriptor del store de archivos, que falla en modo cerrado, en lugar de adivinar a partir de las extensiones. Consulta la
[matriz de motores de documento](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

Typst informa `supports_synctex=true` y `supports_offline=true`, con
`supports_isolated_compile=false`. La sincronización entre código fuente y PDF se ejecuta a través del
Tinymist correspondiente del proyecto y necesita Tinymist 0.13.30 o posterior, así que
`typst_toolchain::describe_project` baja `supports_synctex` a `false` para un
proyecto fijado a Typst 0.11 o 0.12 (`typst_sync::supported_for_project`).
El modo sin conexión bloquea las descargas de paquetes de Typst, de modo que una compilación usa entonces solo la
caché de paquetes compartida y la carpeta `typst-packages` del proyecto. La compilación aislada
sigue siendo exclusiva de LaTeX: la ruta de figuras TikZ rechaza los proyectos de Typst, y
las herramientas de figuras del asistente renderizan fragmentos de Typst, como un lienzo CeTZ o
un diagrama de fletcher, con `render_typst_snippet`. Añade
comportamiento del motor solo cuando la capacidad del backend sea veraz. No añadas
excepciones en la interfaz basadas en la extensión.

## Dónde vive el estado

- Configuración: `~/.oleafly/config.json` (`0600` en Unix). Aquí viven las
  preferencias que no son secretas.
- Secretos: `~/.oleafly/ai-secrets.json` y
  `~/.oleafly/app-secrets.json`, cifrados con la clave `~/.oleafly/ai-secrets.key`,
  accesible solo para su propietario. GitHub y MCP comparten `app-secrets.json`. Las credenciales
  de los proveedores de IA usan `ai-secrets.json`.
- Proyectos: `~/.oleafly/projects/<id>/`, carpetas normales con `.git`.
- Registro de la app: `~/.oleafly/app.log`.

## Puntos de extensión principales

- Añadir un proveedor de IA → actualiza `crates/oleafly-agent/src/provider.rs` y luego replica sus metadatos de visualización en `packages/ai-core/src/providers.ts`. La prueba de paridad del catálogo mantiene alineadas las dos listas.
- Añadir un comando de Tauri → decláralo en `src-tauri/src/*.rs`, regístralo en `src-tauri/src/lib.rs` y envuélvelo en `src/lib/tauri.ts`.
- Añadir un motor de documento → implementa `DocumentEngine` en `src-tauri/src/document_engine.rs`, expón capacidades veraces, añade una ruta de descarga de sidecar fijado por suma de verificación con su prueba de humo y luego consume el descriptor en los controles de la interfaz.
- Añadir una plantilla de proyecto → coloca una carpeta con un manifiesto `template.json` en `src-tauri/resources/templates/` (los metadatos de plantilla generales para todos los motores siguen siendo trabajo planificado).
- Añadir una herramienta para la IA → `packages/ai-tools/src/tools.ts`. Los servicios de la app que necesite pasan por `AiToolsHost` en `src/lib/ai-tools.ts`.
- Añadir una pestaña de la barra lateral, un comando de la paleta de comandos o de la omnibarra, o un conjunto de herramientas de IA → regístralo en `src/contributions/` (consulta [Arquitectura del frontend](/docs/engineering/architecture/#the-contribution-registry)).

## Sincronización y aspectos internos de GitHub

El flujo de dispositivo de OAuth se ejecuta del lado del servidor en Rust (`src-tauri/src/github.rs`) porque los endpoints de OAuth no admiten CORS. Las llamadas a la API (api.github.com) se hacen desde el frontend.

## Estilo de código

- TypeScript: sigue lo que ya hay. Sin comentarios salvo que se pidan. Respeta `noUnusedLocals`/`noUnusedParameters`.
- Rust: idiomático, comandos pequeños, cadenas de error amigables.
- Interfaz: Tailwind v4 + tokens de Geist. Reutiliza las primitivas `Button`, `Tooltip` y `Select`.

## Lanzamientos

El empaquetado apunta a macOS con Apple Silicon, Windows x64, Linux x64 y Linux ARM64. Cada compilación descarga y comprueba sus sidecars de compilador y el recurso incluido de servidores de lenguaje. Las compilaciones de lanzamiento admiten la firma y notarización de Apple en macOS y Azure Artifact Signing en Windows. Consulta
[lanzamientos](/docs/engineering/releasing/) y [la instalación](/docs/install/) para usuarios.
