# 開発

Oleafly デスクトップのリポジトリをセットアップし、バージョンが固定されたサイドカーを取得し、アプリを実行して、主な拡張ポイントを理解します。

Oleafly は [Tauri 2](https://tauri.app) のデスクトップアプリです。React と TypeScript のフロントエンドが、Tauri IPC を通じて Rust と通信します。プロジェクトのファイル、コンパイル、シークレット、MCP のルーティング、AI プロバイダへのリクエストは、Rust が担当します。

## リポジトリの構成

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

フロントエンドは pnpm ワークスペースです。再利用できる機能は、注入されるポートの背後にある `packages/*` に置かれ、アプリシェルがそれらをつなぎ合わせます。`packages/` に手を入れる前に、[フロントエンドのアーキテクチャ](/docs/engineering/architecture/)を読んでください。ポートのパターン、コントリビューションレジストリ、エイリアスの配線を説明しています。

## 前提条件

- Node.js 22.13 以降と pnpm 11.9 以降（正確な pnpm のバージョンは `package.json` に宣言されています）
- [rustup](https://rustup.rs) 経由の Rust（stable）
- お使いの OS 向けの [Tauri 2 のシステム依存関係](https://v2.tauri.app/start/prerequisites/)
- セットアップ時は任意: Markdown の PDF コンパイルと文書の書き出しに使う [pandoc](https://pandoc.org/installing.html)（アプリが、固定バージョンのビルドを必要に応じてインストールできます）

## 初回の実行

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

1 つのプラットフォームだけを対象にするには、各シェルの取得スクリプトに、その Rust のターゲットトリプルを渡します。ホストのトリプルは `rustc -vV` で確認できます。言語サーバーのコマンドは、基になるスクリプトにターゲットを渡さない限り、現在のホストを選びます。

## 日々の作業

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

### PR を開く前のチェック

プルリクエストを開く前に、該当するローカルのチェックを実行します。

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

2 つの audit コマンドには、レジストリ/ネットワークへのアクセスが必要です。CI は、コードを変更するたびに、それらの最新の結果を記録します。オフラインのローカル実行では、依存関係のグラフにアドバイザリがないことを保証できません。

ユーザーに見える変更では、実際のアプリとコンパイラに対するエンドツーエンドのスイートも実行します。[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
```

## コンパイルの仕組み

1. フロントエンドは、バックエンドの `project_engine` ディスクリプタとその capability フラグを読み込み、Tauri IPC を通じて `compileProject(projectId, mainDoc, offline)` を呼び出します。
2. Rust は `DocumentEngine` を通じて処理を振り分けます。UI のコードが、ファイル名からエンジンの動作を推測してはいけません。
3. LaTeX は既定で、同梱の Tectonic を使います。プロジェクトは代わりに、`latexmk` 経由で pdfLaTeX、XeLaTeX、LuaLaTeX を選べます。完全なシステムの TeX インストールは、Oleafly が管理する TinyTeX より優先されます。共有の検出処理は、その優先を認める前に、中核となるコンパイラ、`latexmk`、`kpsewhich`、Biber がそろっていることを要求します。
4. Typst は、プロジェクトが `project.json` で固定した正確なバージョンを実行します。同梱のサイドカー、チェックサム検証済みのダウンロード、またはそのバージョンを報告するシステムの `typst` のいずれかです。選択された `.typ` のメイン文書を、人が読める診断と、明示的な PDF の出力パスでコンパイルします。自動コンパイルがオンの場合は、代わりに Rust がプロジェクトごとに 1 つの `typst watch` プロセスを保持します（`src-tauri/src/typst_watch.rs`）。バージョンの解決、固定、対応する Tinymist については、デスクトップのリポジトリの `docs/typst-toolchain.md` で説明しています。
5. Markdown は、`.md`/`.markdown` に対して Pandoc を直接呼び出し、明示的な出力パスと `--pdf-engine=<absolute bundled Tectonic path>` を指定します。Pandoc のマニュアルは、PDF エンジンのフルパスを明示的にサポートしています。これを、暗黙のシステムの `pdflatex` に置き換えてはいけません。パッケージ化された Oleafly が、宣言されていない TeX のインストールに依存してはならないからです。プロセスはプロジェクトのルートを作業ディレクトリとして実行されるため、相対パスの画像、参考文献ファイル、CSL ファイルが、ルートにあるメイン文書でも、入れ子の場所にあるメイン文書でも動作します。

Tauri の[サイドカーのドキュメント](https://v2.tauri.app/develop/sidecar/)は、ターゲットトリプルの接尾辞が付いた `bundle.externalBin` の入力を定義し、実行時には、パッケージ化されたサイドカーを接尾辞なしの名前で公開します。Oleafly の Pandoc アダプターは、Tauri のデスクトップバンドルの構成に合わせて、パッケージ化された Tectonic の実行ファイルを、アプリケーションの実行ファイルの隣から解決します。ユニットテストは、macOS のアプリバンドルと Cargo の debug/release の候補をカバーし、リリースのワークフローは、すべてのターゲットで、ステージされた接尾辞なしの兄弟ファイルを検査します。

Tectonic、Biber、Typst、言語サーバーのダウンロードは、バージョンとチェックサムが固定されています。取得スクリプトは、アーカイブの構造を検証し、レビュー済みの実行ファイルまたはリソースのパスだけを展開します。CI とリリースのビルドも、同じスクリプトを使います。

6. すべてのエンジンが、正規化されたログ/エラーのイベントをストリーミングします。Rust は、コンパイルのメタデータを JSON IPC で返します。PDF 自体は、結果に base64 で埋め込むのではなく、生のバイナリ IPC として別に取得されます。
7. フロントエンドは、pdf.js で PDF のバイト列を描画し、正規化された診断を CodeMirror に渡します。

エンジンのディスクリプタは、コンパイルのポリシーに加えて、整形/ソースのプリフライトのプロファイルと、機能/書き出し/テンプレート種別の集合を表現します。フロントエンドの利用側は、拡張子から推測するのではなく、フェイルクローズドな files ストアのディスクリプタを使います。[ドキュメントエンジンの対応表](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md)を参照してください。

Typst は `supports_synctex=true` と `supports_offline=true` を報告し、`supports_isolated_compile=false` とします。ソースと PDF の同期は、プロジェクトに対応する Tinymist を通じて動作し、Tinymist 0.13.30 以降が必要です。そのため、`typst_toolchain::describe_project` は、Typst 0.11 または 0.12 に固定されたプロジェクトでは `supports_synctex` を `false` に下げます（`typst_sync::supported_for_project`）。オフラインモードは Typst のパッケージのダウンロードをブロックするので、コンパイルは、共有のパッケージキャッシュとプロジェクトの `typst-packages` フォルダだけを使います。分離したコンパイルは LaTeX 専用のままです。TikZ の図の経路は Typst プロジェクトを拒否し、アシスタントの図のツールは、CeTZ のキャンバスや fletcher のダイアグラムといった Typst のスニペットを、代わりに `render_typst_snippet` で描画します。エンジンの動作を追加するのは、バックエンドの capability が実態に合ってからにしてください。拡張子に基づく UI の例外を追加してはいけません。

## 状態の置き場所

- 設定: `~/.oleafly/config.json`（Unix では `0600`）。シークレットではない環境設定は、ここに置かれます。
- シークレット: `~/.oleafly/ai-secrets.json` と `~/.oleafly/app-secrets.json`。所有者だけが読める `~/.oleafly/ai-secrets.key` で暗号化されます。GitHub と MCP は `app-secrets.json` を共有します。AI プロバイダの認証情報は `ai-secrets.json` を使います。
- プロジェクト: `~/.oleafly/projects/<id>/`。`.git` を持つふつうのフォルダです。
- アプリのログ: `~/.oleafly/app.log`。

## 主な拡張ポイント

- AI プロバイダを追加する → `crates/oleafly-agent/src/provider.rs` を更新し、その表示用メタデータを `packages/ai-core/src/providers.ts` に反映します。カタログのパリティテストが、2 つの一覧の一致を保ちます。
- Tauri コマンドを追加する → `src-tauri/src/*.rs` で宣言し、`src-tauri/src/lib.rs` に登録し、`src/lib/tauri.ts` でラップします。
- ドキュメントエンジンを追加する → `src-tauri/src/document_engine.rs` で `DocumentEngine` を実装し、実態に合った capability を公開し、チェックサムを固定したサイドカーの取得/スモークテストの経路を追加してから、UI のコントロールでディスクリプタを利用します。
- プロジェクトのテンプレートを追加する → `template.json` のマニフェストを持つフォルダを `src-tauri/resources/templates/` に置きます（エンジンを問わない汎用のテンプレートメタデータは、今後の作業として残っています）。
- AI 用のツールを追加する → `packages/ai-tools/src/tools.ts`。ツールが必要とするアプリのサービスは、`src/lib/ai-tools.ts` の `AiToolsHost` を通します。
- レールのタブ/パレットまたはオムニバーのコマンド/AI ツールセットを追加する → `src/contributions/` に登録します（[フロントエンドのアーキテクチャ](/docs/engineering/architecture/#the-contribution-registry)を参照）。

## 同期と GitHub の内部

OAuth のデバイスフローは、OAuth のエンドポイントが CORS に対応していないため、Rust 側（`src-tauri/src/github.rs`）で実行されます。API の呼び出し（api.github.com）は、フロントエンドから行われます。

## コーディングスタイル

- TypeScript: 既存のコードに合わせます。頼まれない限り、コメントは書きません。`noUnusedLocals`/`noUnusedParameters` を守ります。
- Rust: 慣用的な書き方で、コマンドは小さく、エラーメッセージは親しみやすくします。
- UI: Tailwind v4 と Geist のトークン。`Button`、`Tooltip`、`Select` のプリミティブを再利用します。

## リリース

パッケージ化の対象は、macOS Apple Silicon、Windows x64、Linux x64、Linux ARM64 です。各ビルドは、コンパイラのサイドカーと、同梱の言語サーバーのリソースを取得して検査します。リリースビルドは、macOS では Apple の署名と公証、Windows では Azure Artifact Signing に対応しています。[リリース](/docs/engineering/releasing/)と、ユーザー向けの[インストール](/docs/install/)を参照してください。
