# Desenvolvimento

Configure o repositório do aplicativo de desktop Oleafly, baixe os sidecars fixados, execute o aplicativo e conheça os principais pontos de extensão.

O Oleafly é um aplicativo de desktop em [Tauri 2](https://tauri.app). O frontend em React e TypeScript conversa com o Rust por IPC do Tauri. O Rust é responsável pelos arquivos de projeto, pela compilação, pelos segredos, pelo roteamento de MCP e pelas requisições a provedores de IA.

## Estrutura do repositório

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

O frontend é um workspace pnpm. As funcionalidades reutilizáveis ficam em `packages/*` atrás de portas injetadas, e o shell do aplicativo conecta tudo. Leia [Arquitetura do frontend](/docs/engineering/architecture/) antes de mexer em `packages/`: o documento cobre o padrão de portas, o registro de contribuições e a ligação dos aliases.

## Pré-requisitos

- Node.js 22.13+ e pnpm 11.9+ (a versão exata do pnpm é declarada no
  `package.json`)
- Rust (stable) por meio do [rustup](https://rustup.rs)
- [Dependências de sistema do Tauri 2](https://v2.tauri.app/start/prerequisites/) para o seu sistema operacional
- Opcional durante a configuração: [pandoc](https://pandoc.org/installing.html) para a compilação de PDF a partir de Markdown e a exportação de documentos (o aplicativo pode instalar a versão fixada dele sob demanda)

## Primeira execução

```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 uma única plataforma, passe a tripla de destino do Rust para cada script shell de download. Use `rustc -vV` para descobrir a tripla do host. O comando de servidores de linguagem seleciona o host atual, a menos que você passe um destino pelo script subjacente dele.

## Dia a dia

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

### Verificações antes de abrir um PR

Execute as verificações locais relevantes antes de abrir um 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
```

Os dois comandos de auditoria exigem acesso a registro/rede. O CI registra os resultados atuais deles a cada mudança de código. Uma execução local offline não pode certificar que o grafo de dependências está livre de avisos de segurança.

Para mudanças visíveis ao usuário, execute também a suíte ponta a ponta contra o aplicativo e o compilador reais. Veja o [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
```

## Como funciona uma compilação

1. O frontend carrega o descritor `project_engine` do backend e as flags de capacidade dele, então chama `compileProject(projectId, mainDoc, offline)` por IPC do Tauri.
2. O Rust faz o despacho por meio de `DocumentEngine`. O código de UI não deve inferir o comportamento do motor a partir de um nome de arquivo.
3. O LaTeX usa o Tectonic embutido por padrão. Um projeto pode, em vez disso, escolher pdfLaTeX, XeLaTeX ou LuaLaTeX por meio do `latexmk`. Uma instalação TeX do sistema completa tem prioridade sobre o TinyTeX gerenciado do Oleafly. O detector compartilhado exige os compiladores principais, o `latexmk`, o `kpsewhich` e o Biber antes de conceder essa prioridade.
4. O Typst executa exatamente a versão que o projeto fixa no `project.json`: o sidecar embutido, um download verificado por checksum ou um `typst` do sistema que informa essa versão. Ele compila o documento principal `.typ` selecionado com diagnósticos legíveis por humanos e um caminho explícito de saída em PDF. Com a Compilação automática ativada, o Rust mantém, em vez disso, um processo `typst watch` por projeto (`src-tauri/src/typst_watch.rs`). O `docs/typst-toolchain.md` do repositório do aplicativo de desktop cobre a resolução, as fixações de versão e o Tinymist correspondente.
5. O Markdown invoca o Pandoc diretamente sobre `.md`/`.markdown`, com um caminho de saída explícito e `--pdf-engine=<absolute bundled Tectonic path>`. O manual do Pandoc apoia explicitamente um caminho completo para o motor de PDF. Não substitua isso por um `pdflatex` implícito do sistema, porque o Oleafly empacotado não deve depender de uma instalação TeX não declarada. O processo executa com a raiz do projeto como diretório de trabalho, de modo que imagens, arquivos de bibliografia e arquivos CSL relativos funcionem tanto para documentos principais na raiz quanto aninhados.

A [documentação de sidecars do Tauri](https://v2.tauri.app/develop/sidecar/) define as entradas de `bundle.externalBin` com sufixos de tripla de destino e expõe o sidecar empacotado sob o nome sem sufixo em tempo de execução. O adaptador Pandoc do Oleafly resolve esse executável Tectonic empacotado ao lado do executável do aplicativo, o que corresponde ao layout de empacotamento de desktop do Tauri. Testes de unidade cobrem os candidatos de app bundle do macOS e de debug/release do Cargo, enquanto o fluxo de trabalho de release inspeciona o irmão sem sufixo preparado em cada destino.

Os downloads de Tectonic, Biber, Typst e servidores de linguagem têm versão e checksum fixados. Os scripts de download deles validam a estrutura do arquivo compactado e extraem apenas os caminhos de executável ou recurso revisados. O CI e os builds de release usam os mesmos scripts.

6. Todos os motores transmitem eventos normalizados de log/erro. O Rust retorna os metadados da compilação por IPC em JSON. O próprio PDF é buscado separadamente como IPC binário bruto, em vez de embutido em base64 no resultado.
7. O frontend renderiza os bytes do PDF com pdf.js e publica diagnósticos normalizados no CodeMirror.

Os descritores de motor modelam a política de compilação, além de perfis de formatação/pré-verificação de fonte e conjuntos de funcionalidades/exportação/tipos de modelo. Os consumidores do frontend usam o descritor fail-closed do store de arquivos, em vez de adivinhar por extensões. Veja a [matriz de motores de documento](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

O Typst informa `supports_synctex=true` e `supports_offline=true`, com `supports_isolated_compile=false`. A sincronização entre fonte e PDF passa pelo Tinymist correspondente ao projeto e exige o Tinymist 0.13.30 ou posterior, então `typst_toolchain::describe_project` rebaixa `supports_synctex` para `false` em um projeto fixado no Typst 0.11 ou 0.12 (`typst_sync::supported_for_project`). O Modo offline bloqueia downloads de pacotes do Typst, então uma compilação passa a usar apenas o cache compartilhado de pacotes e a pasta `typst-packages` do projeto. A compilação isolada continua exclusiva do LaTeX: o caminho de figuras TikZ recusa projetos Typst, e as ferramentas de figuras do assistente renderizam trechos de Typst, como um canvas CeTZ ou um diagrama fletcher, com `render_typst_snippet` em vez disso. Acrescente comportamento de motor somente depois que a capacidade do backend se tornar verdadeira. Não acrescente exceções de UI baseadas em extensão.

## Onde fica o estado

- Configuração: `~/.oleafly/config.json` (`0600` no Unix). Preferências sem segredos
  ficam aqui.
- Segredos: `~/.oleafly/ai-secrets.json` e
  `~/.oleafly/app-secrets.json`, criptografados com o
  `~/.oleafly/ai-secrets.key`, legível somente pelo dono. O GitHub e o MCP
  compartilham o `app-secrets.json`. Credenciais de provedores de IA usam o
  `ai-secrets.json`.
- Projetos: `~/.oleafly/projects/<id>/`, pastas comuns com `.git`.
- Log do aplicativo: `~/.oleafly/app.log`.

## Principais pontos de extensão

- Adicionar um provedor de IA → atualize `crates/oleafly-agent/src/provider.rs` e depois espelhe os metadados de exibição dele em `packages/ai-core/src/providers.ts`. O teste de paridade de catálogos mantém as duas listas alinhadas.
- Adicionar um comando Tauri → declare em `src-tauri/src/*.rs`, registre em `src-tauri/src/lib.rs` e encapsule em `src/lib/tauri.ts`.
- Adicionar um motor de documento → implemente `DocumentEngine` em `src-tauri/src/document_engine.rs`, exponha capacidades verdadeiras, acrescente um caminho de download/smoke test de sidecar com checksum fixado e então consuma o descritor nos controles de UI.
- Adicionar um modelo de projeto → coloque uma pasta com um manifesto `template.json` em `src-tauri/resources/templates/` (metadados gerais de modelo por motor continuam um trabalho planejado).
- Adicionar uma ferramenta para a IA → `packages/ai-tools/src/tools.ts`. Serviços do aplicativo de que ela precisa passam por `AiToolsHost` em `src/lib/ai-tools.ts`.
- Adicionar uma aba da rail / comando da paleta ou do omnibar / conjunto de ferramentas de IA → registre em `src/contributions/` (veja [Arquitetura do frontend](/docs/engineering/architecture/#the-contribution-registry)).

## Detalhes internos de sincronização e do GitHub

O fluxo de dispositivo OAuth executa no lado do servidor, em Rust (`src-tauri/src/github.rs`), porque os endpoints OAuth não têm CORS habilitado. As chamadas de API (api.github.com) acontecem a partir do frontend.

## Estilo de código

- TypeScript: siga o que já existe. Sem comentários, a menos que solicitado. Respeite `noUnusedLocals`/`noUnusedParameters`.
- Rust: idiomático, comandos pequenos, mensagens de erro amigáveis.
- UI: Tailwind v4 + tokens Geist. Reutilize os primitivos `Button`, `Tooltip` e `Select`.

## Lançamento de versões

O empacotamento visa macOS Apple Silicon, Windows x64, Linux x64 e Linux ARM64. Cada build baixa e verifica os sidecars de compilador e o recurso de servidores de linguagem embutido. Builds de release suportam assinatura da Apple e notarização no macOS e Azure Artifact Signing no Windows. Veja [lançamento de versões](/docs/engineering/releasing/) e [instalação para o usuário](/docs/install/).
