17. Tauri V2 デスクトップ開発ガイド

1. 概要

BluePeriodのデスクトップ版（Tauri V2）における開発規約、設計パターン、および固有の制約について説明します。

2. アーキテクチャ構成

デスクトップ版は、Next.jsをWebViewで表示しつつ、バックエンド処理をRust (Tauriコア) とサイドカーとしてのNode.js (Hono API) に分散させるハイブリッド構成をとっています。

2.1. Hono / MCP サイドカー

役割: Web版と共通のAPIロジック（src/server/api）や MCP サーバーをデスクトップでも実行可能にします。
起動: プロダクションビルドではRust（lib.rs / server.rs）が、同梱された bun バイナリを使用して自動起動します。
プロセス管理: ゾンビプロセス防止のため、PID ではなく CommandChild (Tauri Shell 独自ハンドル) を ServerState で保持し、child.kill() で停止します。
検知: 環境変数 BLUEPERIOD_DESKTOP=1 を付与して起動します。
検知用関数: src/lib/platform/detect.ts の isDesktop() を使用してください。

2.2. Rust IPC

役割: ブラウザのCORS制限等を回避し、ネイティブ機能を利用するためのブリッジです。
実装ディレクトリ: tauri-app/src-tauri/src/commands/
呼び出し方法 (JS/TS):
- 重要: Tauri V2 ではコア機能は window.__TAURI__.core.invoke で呼び出します。
- 非同期コマンド: async な Rust コマンド（State等を受け取るもの）は、JS 側へ値を返さない場合でも必ず Result<T, E> を返す必要があります。
```
// 例: バージョン取得
const version = await window.__TAURI__.core.invoke('get_app_version');
```

3. 実装済みコマンド一覧

モジュール	コマンド名	概要
`server`	`start_hono_server`	Honoサーバーの起動
`server`	`stop_hono_server`	Honoサーバーの停止（プロセスツリーごと）
`server`	`is_hono_server_running`	サーバーの稼働状態確認
`server`	`start_mcp_server`	MCPサーバーの起動
`server`	`stop_mcp_server`	MCPサーバーの停止
`llm`	`call_local_llm`	ローカルLLM(Ollama/LM Studio)へのCORSフリー通信
`fs`	`read_file`	ファイル読み込み（セキュリティチェック付き）
`fs`	`write_file`	ファイル書き込み（セキュリティチェック付き）
`system`	`get_app_version`	アプリケーションのバージョン取得
`system`	`show_notification`	OS標準通知の送出

4. ビルドとリソース管理

4.1. リソースマッピング (`tauri.conf.json`)

プラットフォーム間でのパス整合性を保ち、Windows のパス長制限 (MAX_PATH) を回避するため、resources はマップ構文を使用し、展開先を standalone/ 配下に集約します。

"resources": {
  "../../next-app/.next/standalone": "standalone",
  "../../next-app/.next/static": "standalone/.next/static",
  "../../next-app/public": "standalone/public"
}

4.2. ランタイム環境変数の供給（.env同梱方式）

Desktop版プロダクションビルドでは、Next.js standaloneの server.js をBun Sidecarで実行します。この際、サーバーサイドコード（Supabaseクライアント初期化等）が process.env から環境変数を参照するため、実行時に値が利用可能である必要があります。

仕組み:

ビルド時、postbuild-standalone.ts がビルド環境の環境変数から .env ファイルを生成
.env は standalone/next-app/.env に配置（standaloneリソースに自動的に同梱される）
Bun Sidecarが bun server.js 実行時にworking_dirの .env を自動読み込み → process.env に反映

含める変数（すべて公開情報、シークレットは含めない）:

変数	性質
`NEXT_PUBLIC_SUPABASE_URL`	公開URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	公開鍵（RLS保護）
`NEXT_PUBLIC_APP_URL`	公開URL（OGタグ等）
`NEXT_PUBLIC_STRIPE_PRO_PRICE_ID`	公開価格ID

含めない変数: SUPABASE_SERVICE_ROLE_KEY / STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET — Desktop版ではStripeルートをガードし、ブラウザでWeb版にリダイレクトする設計。

ローカルでの検証手順:

next build 実行後に postbuild-standalone.ts を単体実行して .env が正しく生成されることを確認できます。

# 1. next build を実行（standalone出力の生成）
cd next-app
bun run build

# 2. postbuild スクリプトを単体実行
bun ../tauri-app/scripts/postbuild-standalone.ts

# 3. 生成された .env を確認
cat .next/standalone/next-app/.env
# → NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
#   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
#   のように公開鍵が含まれていることを確認

# 4. Bun の .env 自動読み込みを検証（standaloneディレクトリで実行）
cd .next/standalone/next-app
bun -e "console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)"
# → URL が表示されれば .env 読み込み成功

注意: この検証には next-app/.env.local に環境変数が設定されている必要があります。

GitHub Actions での要件: ビルド時に環境変数が利用可能である必要があるため、release.yml の env: セクションで ${{ secrets.* }} として渡す。必要なSecretsは NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY / NEXT_PUBLIC_APP_URL。

4.3. 本番環境での WebView 制御

Next.js standalone サーバーが起動する前に WebView がロードされるのを防ぐため、setup() 内でサーバー起動を待機した後、window.location.href をプログラムから http://localhost:3703 へリダイレクトする二段階起動を採用しています。

5. セキュリティ規約

デスクトップ版では、OSのネイティブ権限を持つため、以下のルールを厳守してください。

5.1. CSP (Content Security Policy)

tauri.conf.json で定義されています。
接続許可: localhost および 127.0.0.1 への通信は許可されています（ローカルLLM用）。
制限: 意図しない外部ドメインへの接続は許可せず、原則として self と localhost に限定します。

5.2. パス・URLバリデーション

ディレクトリトラバーサル防止: write_file / read_file 等、パスを引数にとるコマンドでは必ず .. を含む遡り操作をRust側でバリデートしてください。
ドメイン制限: call_local_llm 等、URLを引数にとるコマンドでは、接続先が localhost または 127.0.0.1 であることを確認してください。

Rust/Stdout: bun run tauri dev を実行したターミナルに出力されます。
WebView: ウィンドウ上のコンソール（F12）に出力されます。

6. 関連ドキュメント

doc/system/01_architecture.md (3.5節)
doc/log/reports/2026/03/2026-03-06_2245_report_tauri-v2-phase-2-hono-sidecar.md

Tauri V2 デスクトップ開発ガイド