# Contribuindo com o Oleafly

Obrigado por querer tornar o Oleafly melhor! Este guia leva você de um clone recente a um build de desenvolvimento funcionando e cobre como revisamos e integramos mudanças.

Obrigado por querer tornar o Oleafly melhor! Este guia leva você de um clone
recente a um build de desenvolvimento funcionando e cobre como revisamos e
integramos mudanças.

## Formas de contribuir

- Reportar um bug: abra um [relatório de bug](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Solicitar uma funcionalidade: abra uma [solicitação de funcionalidade](https://github.com/Oleafly/Oleafly/issues/new/choose).
- Reportar uma vulnerabilidade de forma privada seguindo o [SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md).
- Enviar um pull request: veja abaixo.

Para qualquer coisa maior que uma pequena correção, abra uma issue primeiro,
para que possamos concordar com a abordagem antes de você investir tempo.

## Pré-requisitos

| Ferramenta | Versão | Observações |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | 22.13+ | Exigido pelo pnpm 11 |
| [pnpm](https://pnpm.io) | 11.9+ | Ative o Corepack ou instale a versão declarada em `package.json` |
| [Rust](https://rustup.rs) | stable (1.77+) | inclui o `cargo` |
| Dependências de plataforma | - | Veja os [pré-requisitos do Tauri v2](https://v2.tauri.app/start/prerequisites/) para o seu sistema operacional (no Linux: `libwebkit2gtk-4.1-dev`, `librsvg2-dev`, `patchelf`, …) |

## Primeiros passos

```bash
git clone https://github.com/Oleafly/Oleafly.git
cd Oleafly
pnpm install

# Find your target with `rustc -vV | grep host`.
bash scripts/fetch-tectonic.sh aarch64-apple-darwin   # or your host triple
bash scripts/fetch-typst.sh aarch64-apple-darwin

# Run the app in dev mode (hot-reloads the frontend, rebuilds Rust on change):
pnpm tauri dev
```

> Os binários de Tectonic, Biber e Typst são **ignorados pelo git** de propósito:
> nunca os commite. O script de busca os coloca em `src-tauri/binaries/`, que é
> onde `bundle.externalBin` espera encontrá-los.

### Construindo um bundle de produção localmente

```bash
pnpm tauri build
```

Os instaladores ficam em `src-tauri/target/release/bundle/`.

## Estrutura do projeto

```
src/                 React + TypeScript app shell
  components/         UI (editor, pdf, ai, layout, files, …)
  lib/               framework-agnostic helpers (ai-providers, github, …)
  store/             Zustand state slices
packages/            @oleafly/* engine packages, consumed as TypeScript source
src-tauri/src/       Rust backend (Tauri commands)
  commands.rs        Tauri command handlers and compile entry points
  latex_engine.rs    Tectonic and latexmk selection
  mcp/               local MCP server, routing, and native tools
  project.rs         project/file CRUD (path-sandboxed - see `resolve`)
  git.rs             git integration
  github.rs          GitHub OAuth device flow
  paths.rs           path helpers + project-id validation
docs/                user-facing documentation
scripts/             sidecar fetchers, language servers, release checks, icon generation
```

## Testes

```bash
pnpm test                    # frontend unit tests (Vitest)
cd src-tauri && cargo test --lib   # Rust backend tests
```

A lógica de backend que toca o sistema de arquivos, o git ou caminhos do
usuário **deve** ter um teste. Os auxiliares de sandbox de caminhos
(`resolve_within`, `validate_project_id`) e os parsers de log/URL são cobertos
em módulos `#[cfg(test)]`: estenda-os quando mudar esse código. No frontend, a
máscara de LaTeX que decide o que o verificador ortográfico/gramatical vê é pura
e testada em unidade em
`src/components/editor/cm/latex-mask.test.ts`: adicione um caso ali quando mudar
o que conta como prosa.

## Estilo de código

- **TypeScript**: o frontend deve passar na verificação de tipos e no build:
  `pnpm build`, e passar pelo gate de lint do Biome: `pnpm lint` (corrija
  automaticamente o que é seguro com `pnpm lint:fix`). O gate **bloqueia** em
  erros de correção. Um backlog existente de acessibilidade/estilo é reportado
  como avisos não bloqueantes (veja `biome.json`). Prefira não adicionar novos
  avisos.
- **Rust**: o backend deve estar limpo no `cargo fmt` e no `cargo clippy`. Ambos
  são **bloqueantes** no CI (o `clippy` roda com `-D warnings`). Rode
  `cargo fmt` e `cargo clippy --all-targets --fix` antes de enviar.
- Siga o código ao redor: densidade de comentários, nomes e idiomatismos.

## Pull requests

1. Faça um fork e crie um branch a partir de `main`
   (`git checkout -b fix/short-description`).
2. Mantenha a mudança focada. Coloque refatorações não relacionadas em um PR
   próprio.
3. Certifique-se de que `pnpm lint`, `pnpm build` e `cargo test --lib` passam
   localmente.
4. Preencha o modelo de PR: vincule a issue, descreva a mudança e indique como
   você a testou.
5. O CI deve estar verde (o build do frontend e os testes de Rust são
   verificações obrigatórias).

Fazemos merge com squash, então um título de PR limpo vira a mensagem de commit.
O estilo conventional-commit é apreciado, mas não exigido (por exemplo,
`fix: reject absolute paths in resolve`).

## Releases (mantenedores)

Releases são criadas enviando uma tag de versão. O [workflow
`Release`](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml)
compila instaladores para macOS Apple Silicon, Windows x64, Linux x64 e Linux
ARM64, e os anexa a um rascunho para revisão. A publicação exige uma segunda
execução protegida do workflow para a mesma tag.

```bash
# Bump the version everywhere it's declared (package.json, Cargo.toml,
# Cargo.lock, tauri.conf.json) in one shot, so the tag can't drift:
./scripts/bump-version.sh 0.3.6

git commit -am "chore: release v0.2.0"
git tag v0.2.0 && git push origin v0.2.0
```

Ao contribuir, você concorda que suas contribuições são licenciadas sob a
[Licença GNU Affero General Public License v3.0 ou
posterior](https://github.com/Oleafly/Oleafly/blob/main/LICENSE) do projeto.