デスクトップアプリ（Electrobun）設計書

最終更新: 2026-10-01（Electrobun 2.0.2への更新を反映）

1. 概要

MorningStatusApp デスクトップアプリ（Windows／macOS）のアーキテクチャ設計書。Next.js standalone サーバーを Electrobun でラップし、単一のネイティブアプリとして配布する仕組みを扱う。

この領域のドキュメントはこれまで docs/notes/DEVELOPMENT_NOTES.md の断片的な知見や README の変更履歴に散在しており、設計の全体像をまとめた文書が存在しなかった。Windows/macOS でディレクトリ構成が異なる点（§3）のような前提知識が実装者間で共有されず、バグ（#1535）を誘発したことを受けて本書を新設した（#73）。

ビルド・インストールの実行手順（コマンド）は デスクトップアプリのビルド手順 に分離しており、本書はアーキテクチャ・実装仕様（Why・How が本質的に変わらない部分）に特化する。

2. ビルドフロー概要

1. DESKTOP_MODE=1 bun run next build で Next.js standalone サーバー（.next/standalone/）を生成
2. bunx electrobun build --env=stable で Electrobun アプリ（プラットフォーム別バイナリ）とインストーラを生成する。Hutch（Electrobun 2系のビルドツールチェーン）が build.scripts.preBuild フックで desktop/scripts/stage-nextjs.ts を自動実行し、build.copy 設定に従って 1 の standalone サーバー一式をパッケージ（.tar.zst）に同梱したうえで、インストーラ（Windows: MorningStatusApp-Setup.exe、macOS: DMG）まで生成する

具体的なコマンド・スクリプト（setup/build-macos.sh・setup/build-installer.ps1）は デスクトップアプリのビルド手順 を参照。

2.1 Next.js standalone の同梱方式（build.copy とステージング）

electrobun.config.ts の build.copy は desktop/ 配下の相対パスしか参照できず、.. を含むパスを拒否する（Hutch のバリデーションによる制約）。Next.js の standalone 出力（.next/standalone/）はリポジトリルートに生成され desktop/ の外にあるため、build.copy から直接参照できない。

このため、build.scripts.preBuild フックで desktop/scripts/stage-nextjs.ts を実行し、一度 desktop/.next-standalone-staging/（gitignore 対象）にステージングしてから build.copy: { ".next-standalone-staging": "nextjs/standalone" } で拾う二段構えにしている。

備考: Next.js の standalone 出力には @prisma/client 等へのシンボリックリンクが含まれる。Windows では fs.cpSync がこのシンボリックリンクをそのまま複製しようとすると EIO（“another process has locked a portion of the file”）で失敗するため、stage-nextjs.ts では dereference: true を指定してリンク先の実体を複製している。

備考（検討したが採用しなかった代替案）: Next.js の distDir を desktop/ 配下（例: desktop/.next-desktop）に変更すれば、standalone 出力を直接 desktop/ 配下に生成でき、ステージング用のコピー処理を大幅に削減できると考え検証した。しかし desktop/ に package.json が存在するため、Next.js のファイルトレーサーが desktop/ をワークスペースの一部とみなし、standalone 出力が desktop/.next-desktop 自身を再帰的に含んでしまう（自己参照）問題が発生した。outputFileTracingExcludes で desktop/** を除外しても、per-route のファイルトレースとは別経路（ワークスペースパッケージ検出によるコピー）で数MB規模の残骸が残り、完全には解消しなかったため見送った。

3. プラットフォーム別ディレクトリ構成の違い

3.1 インストール先と実行時展開先（Windows、Electrobun 2系／Hutch）

Electrobun 2系（Hutch）では、Windows インストーラ（MorningStatusApp-Setup.exe）がインストールする内容と、アプリが実際に実行時に使う内容が異なる二段構成になっている。

1. インストール先（既定 %LOCALAPPDATA%\Programs\MorningStatusApp\。管理者権限なしの場合）: bin/launcher.exe（ブートストラッパー）と、アプリ本体を圧縮した Resources/*.tar.zst のみが置かれる
2. 実行時展開先（%LOCALAPPDATA%\{app.identifier}\{channel}\app\。例: %LOCALAPPDATA%\dev.morning-status-app\stable\app\）: launcher.exe が初回起動時に .tar.zst をここへ自己展開し、以降はこのディレクトリから実行する

desktop/src/bun/index.ts（Resources/app/bun/index.js としてビルドされる Worker 本体）が動作するのは 2. 実行時展開先 の中であり、パス解決ロジック（§3.2）が対象とするのもこちらである。

備考: v1（Inno Setup）ではインストール先＝実行先で、フラットな {app}/bin/・{app}/Resources/ 構成だった。v2 移行時、独自の Inno Setup スクリプトで v1 相当のフラット構成をそのままインストールしたところ、launcher.exe が .tar.zst の自己展開を前提に整合性チェックを行っており、“The installer package is incomplete” エラーで起動に失敗した。Hutch 純正の MorningStatusApp-Setup.exe（electrobun build --env=stable が生成）に切り替えることで解消した。

3.2 実行時ディレクトリ構成

両プラットフォームとも実行バイナリ配置ディレクトリと Resources が同階層にあるという点は共通しているが、ディレクトリ名（bin か MacOS か）が異なるため、パス解決ロジックはプラットフォームごとに個別の検証が必要になる。

実際のパス解決は desktop/src/bun/resolve-paths.ts の resolveBunExecutablePath(resourcesDir, platform) に集約している。index.js の配置ディレクトリ（Resources/app/bun 相当）を起点に、darwin なら ../MacOS/bun、それ以外（Windows）なら ../bin/bun.exe を返す。

備考（Electrobun 2.0.1移行）: electrobun.config.ts の build.copy の同梱先は Resources/ 直下ではなく Resources/app/ 基準になる（実機検証で判明）。resolveBunExecutablePath() が使う resourcesDir（Resources/、bun 実行ファイル解決用）と、Next.js standalone サーバーのパス解決に使う appBundleDir（Resources/app/）は起点が1段異なるため、desktop/src/bun/index.ts では両者を別変数として保持している。

備考: 旧実装（#1535）は、macOS でも Windows と同じ計算式（{resourcesDir}/../bin/bun 相当）で bun 実行ファイルのパスを求めていた。macOS 対応自体は #711 で追加されたが、インストール済 .app での実機起動検証が行われておらず、実在する Contents/MacOS/bun を参照できずに ENOENT で起動失敗していた。プラットフォーム別のパス解決ロジックを resolve-paths.ts に切り出し、darwin の場合のみ ../MacOS/bun を返すように修正して解消した。

4. 起動フロー（インストール済アプリ）

1. launcher.exe（Windows）／MorningStatusApp（macOS）→ Electrobun ランチャーが起動し、bun/index.js（Worker）を起動する
2. Worker が resolveBunExecutablePath() で同梱 bun 実行ファイルのパスを解決する（プラットフォーム別、§3参照）
3. 前回起動時の自プロセス（main.js = このWorker自身）のPID（OS一時ディレクトリの morning-status-app-desktop-main.pid に記録、MAIN_LOCK_FILE）が生存していれば killStaleServer() で強制終了し、ロックファイルを削除したうえで自身のPIDを書き込む。server.js の有無に関わらず常に実行する（#1563）
4. 前回起動時のサーバー PID（OS 一時ディレクトリの morning-status-app-desktop-server.pid に記録、SERVER_LOCK_FILE）が生存していれば killStaleServer() で強制終了し、ロックファイルを削除する（#1561）
5. Resources/app/nextjs/standalone/server.js（§3.2）を検出し、同梱 bun で Next.js サーバーを子プロセス起動、そのプロセス PID をロックファイルに書き込む（writeLockedPid()）
6. waitForServer() がサーバーのポート応答をポーリングする。応答前にサーバープロセスが終了した場合は起動失敗として扱う
7. BrowserWindow で http://localhost:{port}（既定 3001）を表示する
8. WebView2 は初回描画時にスクロールバーを描画しないため、dom-ready イベント後にウィンドウサイズを ±1px 変化させて再描画を強制する

備考: 以前は上記6の待機処理がポートへの応答有無だけを起動成功の判定基準にしており、ウィンドウを閉じても process.on("exit") のクリーンアップを素通りしてサーバー子プロセスが残留することがあった。再ビルド・再インストール後に起動すると、新しいサーバーがポートの bind に失敗し、残留していた旧バージョンのサーバーにそのまま接続してしまい、再ビルドしても画面が更新されないバグがあった（#1561）。PID ロックファイルによる残留プロセスの検出・強制終了（上記4・5）と、起動確認時のプロセス終了検知（上記6）を追加して解消した。

5. プロセス終了時のクリーンアップ

• 正常終了: process.on("exit") および app.on("before-quit", ...)（Electrobun の app export）で、spawn した Next.js サーバー子プロセスを kill() する
• 異常終了（強制終了・クラッシュ等）への対策: 上記フックは異常終了時には発火しないため、サーバー子プロセス（server.js）は §4-4 のロックファイル方式で次回起動時に自己修復する（#1561）。main.js 自身（Electrobun ランタイム本体）についても、launcher.exe の異常終了時には上記フックが発火しないため、同じロックファイル方式（§4-3、MAIN_LOCK_FILE）で次回起動時に自己修復する（#1563）

備考: 以前は main.js 自身を保護する仕組みが無く、launcher.exe（Electrobun ランタイム本体、main.js を実行する bun.exe の親プロセス）が異常終了すると main.js が孤児プロセスとして残留していた。ウィンドウ（WebView2）は launcher.exe ではなく main.js 側が保持しているため、残留した main.js は操作可能な旧ウィンドウごと生存し続けていた。この状態でインストーラの上書きアップグレードを実行すると、ファイルにロックがかかり失敗する場合があった（#1563）。server.js と同じ自己ロックファイル方式を main.js 自身にも適用し解消した。

備考（Electrobun 2.0.2）: 2.0.2 では Windows 向けに、launcher.exe が子プロセスの終了コードを32bitのまま保持して子プロセスの PID・生成時刻をログに出力する変更と、WebView2 コントローラをアプリ終了前にネイティブ UI スレッドでクローズする変更が入った（MorningStatusApp#1662）。どちらも正常終了時のブラウザプロファイル保存と異常終了時の原因調査（PID 再利用の判別）を改善するもので、異常終了時に子プロセスが残ること自体を防ぐものではないため、上記のロックファイル方式（§4-3・§4-4）は引き続き必要である。

6. WebView のキャッシュ制御

デスクトップモードの Next.js レスポンスは next.config.ts の headers() で Cache-Control: no-store を付与し、Next.js の ISR が内部的に設定する Cache-Control（s-maxage／stale-while-revalidate 等）を上書きする。適用条件は以下の2点で、Web 版（Vercel）の ISR キャッシュ設計には影響させない。

• DESKTOP_MODE=1 かつ macOS 限定: WKWebView（macOS）でのディスクキャッシュ不具合は実機調査で再現・検証済だが、WebView2（Windows）では同種の不具合が未確認。Windows は macOS よりインストール・アンインストールの検証回数が大幅に多いにもかかわらず再現報告がないため、根拠のないまま Windows にも同じ対策を適用するのは妥当でないと判断し、process.platform で macOS 限定にガードしている
• _next/static 配下は対象外: source: '/((?!_next/static).*)' により除外する。同ディレクトリはコンテンツハッシュ付きファイル名で無期限キャッシュしてよいため、no-store の対象に含める必要がない

備考: 以前は Web 版と同じ ISR キャッシュヘッダーをそのまま返しており、WKWebView（macOS）が stale-while-revalidate に従って HTML をディスクキャッシュしていた。このキャッシュは .app の再インストールでは消えないため（Electrobun の BrowserView にキャッシュを明示的にクリアする API が無い）、サーバー自体が新バージョンで起動できていても画面には反映されないケースがあった（#1561）。デスクトップモードはローカル単一ユーザー向けで CDN キャッシュの恩恵がなく、常に最新の内容を表示すべきであるため、no-store を強制することで解消した。当初は全ルート・全プラットフォームに適用していたが、_next/static 配下の静的アセットまで無効化対象に巻き込んでいた点と、WebView2（Windows）では不具合が未確認のまま対策を適用していた点を別PRのレビュー（#1562）で指摘され、上記の適用条件に絞り込んだ。

7. 同梱 Bun バイナリのバージョン管理

electrobun パッケージは、システムの bun upgrade とは独立して、自前で固定バージョンの Bun バイナリを同梱する仕組みを持つ。

備考（Electrobun 2.0.1移行）: v1 ではトップレベルの build.bunVersion フィールドで明示指定できたが、v2（Hutch）では zig／rust／go／odin の各ランタイムには version? フィールドでのトップチェーン上書きが用意されている一方、bun・cottontail にはこの上書き手段が存在しない（desktop/.hutch/devkit/api/config/ElectrobunConfig.ts の型定義で確認済）。同梱される Bun バイナリのバージョンは、選択した Electrobun devkit（desktop/package.json の electrobun パッケージバージョン）が決める既定値に従うのみで、プロジェクト側から個別に固定することはできない。

8. バージョン管理（アプリ本体）

アプリのバージョンは目的の異なる3箇所で個別に管理されており、自動同期される仕組みはない。

画面表示用のバージョン（root package.json）と、Electrobun アプリ本体のバージョン（desktop/ 配下）は異なる数値体系で運用されている。

備考（Electrobun 2.0.1移行）: v1 時代は Windows インストーラのバージョンを build-installer.ps1 が root package.json から読み取り、Inno Setup に /DAppVersion として渡していた。v2（Hutch 純正インストーラ）移行後は独自のバージョン受け渡しを行っておらず、インストーラのバージョンは desktop/electrobun.config.ts の app.version に一本化されている。

9. リソース（アイコン）

アイコン素材は desktop/assets/ に配置する。

desktop/assets/
  icons8-コーヒーカップ-100.png  # ソース画像（Icons8）
  icon.ico                        # Windows 用（100px PNG から生成）
  icon.iconset/                   # macOS 用（sharp で各サイズ生成済）
    icon_16x16.png
    icon_16x16@2x.png
    icon_32x32.png
    icon_32x32@2x.png
    icon_128x128.png
    icon_128x128@2x.png
    icon_256x256.png
    icon_256x256@2x.png
    icon_512x512.png

electrobun.config.ts の build.win.icon（assets/icon.ico）／build.mac.icons（assets/icon.iconset）でビルド時に埋め込む。

アイコンを差し替える場合

より高解像度のソース画像（512px 以上推奨）を入手したら、以下のスクリプトで再生成する。

# Windows（Bun）: icon.ico を再生成
bun -e "
const pngPath = 'desktop/assets/<新しい画像>.png';
const icoPath = 'desktop/assets/icon.ico';
const pngData = await Bun.file(pngPath).arrayBuffer();
const pngBytes = new Uint8Array(pngData);
const buf = new ArrayBuffer(6 + 16 + pngBytes.length);
const view = new DataView(buf);
view.setUint16(0, 0, true); view.setUint16(2, 1, true); view.setUint16(4, 1, true);
view.setUint8(6, 0); view.setUint8(7, 0); view.setUint8(8, 0); view.setUint8(9, 0);
view.setUint16(10, 1, true); view.setUint16(12, 32, true);
view.setUint32(14, pngBytes.length, true); view.setUint32(18, 22, true);
new Uint8Array(buf, 22).set(pngBytes);
await Bun.write(icoPath, buf);
"

# macOS: iconset を再生成（macOS 環境で実行）
mkdir -p desktop/assets/icon.iconset
sips -z 16 16   <ソース>.png --out desktop/assets/icon.iconset/icon_16x16.png
sips -z 32 32   <ソース>.png --out desktop/assets/icon.iconset/icon_16x16@2x.png
sips -z 32 32   <ソース>.png --out desktop/assets/icon.iconset/icon_32x32.png
sips -z 64 64   <ソース>.png --out desktop/assets/icon.iconset/icon_32x32@2x.png
sips -z 128 128 <ソース>.png --out desktop/assets/icon.iconset/icon_128x128.png
sips -z 256 256 <ソース>.png --out desktop/assets/icon.iconset/icon_128x128@2x.png
sips -z 256 256 <ソース>.png --out desktop/assets/icon.iconset/icon_256x256.png
sips -z 512 512 <ソース>.png --out desktop/assets/icon.iconset/icon_256x256@2x.png
sips -z 512 512 <ソース>.png --out desktop/assets/icon.iconset/icon_512x512.png
iconutil -c icns desktop/assets/icon.iconset  # .icns も生成される

既知の問題（解消済）

備考: Windows ビルド時、rcedit の依存解決に失敗し launcher.exe／bun.exe へのアイコン埋め込みが警告付きでスキップされる問題があった（Cannot find module '...\node_modules\rcedit\package.json'）。Electrobun が Bun のグローバルキャッシュルートから実行される際、ローカルの node_modules/rcedit を解決できないことが原因（#846）。Electrobun 1.18.1・1.18.4-beta.3 の時点では未解消だったが、Hutch（Electrobun 2.0.1 のビルドツールチェーン）ベースのビルドパイプラインに刷新されたことで rcedit 呼び出し経路自体が変わり、launcher.exe・bun.exe・MorningStatusApp-Setup.exe いずれもアイコン埋め込みが成功することを実機（Windows）で確認した（#1548）。

10. TypeScript型チェック・テストとHutch devkitの依存

desktop/tsconfig.json は ./.hutch/devkit/tsconfig.json を extends する（Electrobun 2系／Hutchアーキテクチャの要件）。desktop/.hutch/ は .gitignore 対象で、bunx electrobun dev/build/prepare のいずれかを実行したときにのみローカルに生成される。bun install だけでは生成されない。

Electrobunを新規導入する場合、または desktop/src 配下にVitestテスト・型チェック対象のコードを追加する場合は、以下を必ずセットで用意すること:

• CI: テスト・型チェックを実行するジョブの前段で、desktop ディレクトリでの bun install と bunx electrobun prepare --env=stable を実行する（.github/workflows/deploy-vercel.yml の test ジョブに実装済）
• ローカルセットアップ: リポジトリクローン直後の環境で desktop/src 配下のテスト・型チェックを実行する前に、同様に bun install（desktop ディレクトリ）と bunx electrobun prepare --env=stable を一度実行する

これを怠ると、desktop/.hutch/ が未生成の環境（新規clone直後・CI）でのみ [TSCONFIG_ERROR] Tsconfig not found が発生する。過去に一度でも上記コマンドを実行したことがあるローカル環境では再現しないため、発見が遅れやすい（MorningStatusApp#1548）。

備考: 同種の「.gitignore 対象の生成物へのtsconfig依存」は、ルートリポジトリの tsconfig.scripts.json（next-env.d.ts 依存、MorningStatusApp#1629）でも発生している。個別事例を横断した一般化・設計原則は開発ノート「実装」カテゴリ#136を参照。

改訂履歴