[[macOS]]アプリ(JINRAI)を配布する仕組みをつくる。 ## 要件 - リリースは[[GitHub]]のCIで行う - Apple Storeへの掲載は不要 - お金は払いたくない - [[Homebrew]]や[[mise]]などでインストールできるとなお良い - バージョンアップはJINRAIのメニューから行えるようにしたい - [[Homebrew]]や[[mise]]でもできるとよい ## JINRAI 配布機構 実装プラン ### Context JINRAI(SwiftPM 製 macOS メニューバー常駐アプリ)にはまだ配布手段がない(GitHub Releases・タグ・リリース CI すべて未整備、README も開発者向けビルド手順のみ)。エンドユーザーが簡単にインストール・アップデートできる仕組みを作る。 確定した方針(ユーザーと合意済み): - **Apple Developer Program は使わない(無料)** → Developer ID 署名・公証なし - **リリースは GitHub Actions**(`v*` タグ push トリガー) - **署名は自己署名証明書 `jinrai-dev` を固定**: .p12 を GitHub Secrets に登録し CI で署名。ad-hoc だと更新毎に署名が変わり TCC 権限(アクセシビリティ・画面収録)が剥がれるため。ローカル開発の `make-app.sh` が既に `jinrai-dev` を検索する実装なので流用できる - **メニューからのアップデートは自前実装**(Sparkle 不使用、依存ゼロ) - **Homebrew は自前 tap 新設**(`tadashi-aikawa/homebrew-tap`、cask。既存 tap リポジトリなし) - mise 対応は見送り ### 実装フェーズ ``` Phase 0: 証明書準備(ユーザー手作業 + Secrets 登録) Phase 1: make-app.sh 拡張 + Info.plist 修正 Phase 2: release.yml(タグ push → GitHub Release) Phase 3: homebrew-tap 新設 + cask 自動更新 Phase 4: 自前アップデータ(Swift 実装 + メニュー統合) Phase 5: README / docs 更新 Phase 6: 検証(v0.0.1 テストリリース) ``` Phase 2 までで「タグを打てば Release ができる」状態になり、Phase 3/4 は独立に進められる。 ### Phase 0: 自己署名証明書の準備(ユーザー手作業) ローカルの `jinrai-dev` 証明書を CI でも使い、全経路(開発・CI リリース・自前更新)で署名を統一する。 1. 未作成なら Keychain Access → 証明書アシスタント → 「証明書を作成…」 - 名前 `jinrai-dev` / 自己署名ルート / タイプ **コード署名** / 有効期限は 3650 日等に延長推奨(作り直すと TCC が剥がれるため) 2. 秘密鍵ごと .p12 で書き出し(パスワード付き)→ `base64 -i jinrai-dev.p12 | pbcopy` 3. jinrai リポジトリの Secrets に登録: | Secret | 内容 | | --- | --- | | `MACOS_CERT_P12_BASE64` | .p12 の base64 | | `MACOS_CERT_PASSWORD` | .p12 のパスワード | | `TAP_GITHUB_TOKEN` | tap 更新用 fine-grained PAT(Phase 3) | keychain パスワードはジョブ内 `openssl rand` 生成で Secret 不要。 ### Phase 1: 下準備 - `Resources/Info.plist`: - `NSScreenCaptureUsageDescription` 追加(現状未設定) - `LSMinimumSystemVersion` を 14.0 → 15.0 に整合(README は macOS 15+) - `scripts/make-app.sh`: - 署名 identity を環境変数 `CODESIGN_IDENTITY`(デフォルト `jinrai-dev`)で上書き可能に - `--timestamp=none` を明示(自己署名はタイムスタンプサーバ不可)。hardened runtime は付けない(公証なしでは利点なし) ### Phase 2: `.github/workflows/release.yml`(新規) - トリガー `push: tags: ["v*"]`、`runs-on: macos-26`(ci.yml と同じ SDK 世代)、`permissions: contents: write` - **証明書 import**: `security create-keychain` → `import -T /usr/bin/codesign` → `set-key-partition-list -S apple-tool:,apple:,codesign:`(無いと codesign がハング)→ `security list-keychains -d user -s` で search list に追加(make-app.sh の `find-identity` が見つけるために必須) - `VERSION=${GITHUB_REF_NAME#v}` → `./scripts/make-app.sh release "$VERSION"` - **署名検証ステップ必須**: `codesign -dv .build/JINRAI.app 2>&1 | grep -q "Authority=jinrai-dev"` — ad-hoc フォールバックでリリースされる事故を fail で防ぐ(ad-hoc だと更新毎に TCC が剥がれる) - **アーカイブは zip(`ditto -c -k --keepParent`)**: 拡張属性・署名メタデータを保持、ダブルクリック展開可、cask 標準対応。`--keepParent` 必須 - `gh release create "$GITHUB_REF_NAME" JINRAI-$VERSION.zip --generate-notes` - **tap 更新**: `TAP_GITHUB_TOKEN`(fine-grained PAT、homebrew-tap のみ・Contents write のみ)で tap を clone → `Casks/jinrai.rb` の version/sha256 を書き換え → commit & push ### Phase 3: `tadashi-aikawa/homebrew-tap`(新規リポジトリ) 構成: `README.md` + `Casks/jinrai.rb` cask の要点: - `url "https://github.com/tadashi-aikawa/jinrai/releases/download/v#{version}/JINRAI-#{version}.zip"` - `app "JINRAI.app"`(/Applications へ移動される)、`depends_on macos: ">= :sequoia"` - **quarantine 対処**: 自前 tap の特権として `postflight` で `xattr -dr com.apple.quarantine` を実行(`--no-quarantine` フラグ頼みは忘れやすい)。念のため caveats にも Gatekeeper 手順を記載 - インストールで `brew install tadashi-aikawa/tap/jinrai` が使えるようになる ### Phase 4: 自前アップデータ 新規ファイル(既存 Features/ パターン踏襲): | ファイル | 役割 | | --- | --- | | `Sources/JinraiCore/SemanticVersion.swift` | バージョン解析・比較(純粋ロジック、テスト対象) | | `Tests/JinraiCoreTests/SemanticVersionTests.swift` | 上記のテスト | | `Sources/Jinrai/Features/Updater/UpdateChecker.swift` | GitHub Releases API(`releases/latest`、認証不要)で最新版判定 | | `Sources/Jinrai/Features/Updater/UpdateInstaller.swift` | DL → 展開 → 置換 → 再起動 | | `Sources/Jinrai/Features/Updater/UpdaterFeature.swift` | UI フロー統括(NSAlert ベース) | 設計の要点: - `0.0.0-development` ではチェックをスキップ(開発 .app の誤上書き防止) - インストールフロー: `URLSession.download` → `ditto -x -k` で展開 → 置換前に `codesign --verify` + designated requirement 比較 → **rename 2 回方式で置換**(実行中 .app の rename は可能。Sparkle 的ヘルパー不要)→ `sh -c 'sleep 0.5; open <path>'` を detach して `NSApp.terminate` - quarantine: `LSFileQuarantineEnabled` 未設定なら URLSession DL には付かないはずだが、防御的に展開後 xattr 除去を無条件実行 - **brew インストール検知時**(`Caskroom/jinrai` 存在チェック)は自前更新をスキップし `brew upgrade --cask jinrai` を案内(brew との version/sha256 乖離を回避)。自前更新は手動インストールユーザー向け - `StatusItem.swift`: バージョン表示直後に「アップデートを確認…」項目 + `onCheckForUpdates` クロージャ(既存 `onReloadConfig` パターン踏襲)。`AppDelegate.swift` で `UpdaterFeature` を結線 - UI: 最新なら「最新版です」、新版ありなら [更新]/[リリースノートを見る]/[キャンセル]、エラー時は Releases ページへ誘導。すべて NSAlert ### Phase 5: ドキュメント `README.md` にインストールセクション追加: 1. Homebrew: `brew install tadashi-aikawa/tap/jinrai` 2. 手動: Releases から zip → 展開 → /Applications 3. **初回起動(Gatekeeper)**: macOS 15+ は右クリック→開くバイパスが廃止済み。ダブルクリック → ブロック → システム設定 → プライバシーとセキュリティ → **「このまま開く」**。代替: `xattr -dr com.apple.quarantine`(brew 経由なら不要) 4. 開発者向け: 証明書作成・Secrets・リリース手順(`git tag vX.Y.Z && git push origin vX.Y.Z`) `docs/docs/setup.md` は旧 Hammerspoon 版の内容なので、ネイティブ版の手順に書き換え(docs/ は未コミットのため扱いは実装時にユーザーと相談)。 ### Phase 6: 検証 1. ローカル: `./scripts/make-app.sh release 9.9.9` → `codesign -dv` で Authority=jinrai-dev 確認 2. keychain import 手順をローカルの一時 keychain で再現し、非対話署名が通ることを確認 3. `ditto` 往復 → `codesign --verify --deep` が通ること 4. `v0.0.1` テストタグ push → release.yml 全行程確認(tap 更新は最初コメントアウトして段階投入) 5. `brew install` → quarantine が外れている(`xattr -l`)・起動確認 → `brew upgrade` 一巡 6. 旧版 0.0.1 を /Applications に置いて起動 → 新版リリース → メニュー更新 → **置換後に TCC 権限(アクセシビリティ・画面収録)が維持されているか確認(最重要)** 7. ブラウザ実ダウンロードで Gatekeeper 手順(「このまま開く」)を実機確認 ### 実装時に検証すべき不確かな macOS 仕様 1. **TCC 維持(最重要)**: 同一自己署名での置き換え後に権限が残るか(macOS 26 実機) 2. URLSession DL への quarantine 付与有無 3. `open` による relaunch のタイミング(`-n` の要否) 4. cask postflight の xattr 除去が brew サンドボックス下で動くか 5. `set-key-partition-list` のオプションがランナー世代で変わらないか ### 変更・新規ファイル一覧 | 種別 | ファイル | | --- | --- | | 新規 | `.github/workflows/release.yml` | | 変更 | `scripts/make-app.sh` / `Resources/Info.plist` | | 新規 | `Sources/JinraiCore/SemanticVersion.swift` + テスト | | 新規 | `Sources/Jinrai/Features/Updater/`(3ファイル) | | 変更 | `Sources/Jinrai/StatusItem.swift` / `AppDelegate.swift` | | 変更 | `README.md`(docs/ は実装時に相談) | | 新規(別リポジトリ) | `tadashi-aikawa/homebrew-tap` → `Casks/jinrai.rb` | ## 完了報告 実装内容 jinrai リポジトリ(未コミットの変更): - .github/workflows/release.yml(新規) — v* タグ push で、自己署名証明書の import → ビルド → 署名検証 → ditto zip 化 → GitHub Release 作成 → tap の cask 自動更新まで実行 - scripts/make-app.sh — CODESIGN_IDENTITY 環境変数対応と --timestamp=none 追加 - Resources/Info.plist — NSScreenCaptureUsageDescription 追加、最小バージョンを 15.0 に整合 - 自前アップデータ(依存ゼロ) — メニューに「アップデートを確認…」を追加。GitHub Releases API で最新版確認 → ダウンロード → 署名検証(現行と同じ jinrai-dev 署名でなければ拒否)→ rename 2回方式で置き換え → 自動再起動。開発ビルド(0.0.0-development)ではスキップ、Homebrew 経由インストール時は brew upgrade --cask jinrai を案内して乖離を回避 - README.md — インストール手順(brew / 手動 / Gatekeeper「このまま開く」手順)とリリース手順を追記 新規リポジトリ: https://github.com/tadashi-aikawa/homebrew-tap を作成・push 済み。brew install tadashi-aikawa/tap/jinrai 用の cask を配置し、quarantine は postflight で自動除去します(cask の version/sha256 は初回リリース時に CI が書き換えます)。 検証で1件バグを発見・修正済み: 署名検証の codesign -dv では Authority 行が出力されず CI が必ず fail する状態だったため、-dvv に修正しました。また codesign -dr - の実出力から、TCC の判定キーが「バンドル ID + 証明書リーフハッシュ」であることを確認でき、同一証明書での更新なら権限が維持される設計の前提が裏付けられました。 リリース前に必要な手作業(あなたの操作) 1. 証明書のエクスポート: Keychain Access で jinrai-dev(既存を確認済み)を秘密鍵ごと .p12 形式で書き出し → base64 -i jinrai-dev.p12 | pbcopy 2. jinrai リポジトリの Secrets 登録: MACOS_CERT_P12_BASE64 / MACOS_CERT_PASSWORD / TAP_GITHUB_TOKEN(fine-grained PAT、対象は homebrew-tap のみ・Contents: Read and write) 3. テストリリース: git tag v0.0.1 && git push origin v0.0.1 でワークフロー全行程を確認 4. 実機検証(最重要): 旧版を起動した状態でメニューから更新し、アクセシビリティ・画面収録の許可が維持されるか確認。ブラウザ実ダウンロードでの Gatekeeper 手順も一度確認を推奨 なお docs/(未コミット)は旧 Hammerspoon 版の内容のままなので今回は触っていません。ネイティブ版向けの書き換えが必要になったら声をかけてください。 ## 手動作業 ### 1. 証明書のエクスポート: Keychain Access で jinrai-dev(既存を確認済み)を秘密鍵ごと .p12 形式で書き出し 1. Keychain Access(キーチェーンアクセス).app を開く(Spotlight で「キーチェーンアクセス」) 2. 左側で「ログイン」キーチェーン → 分類「自分の証明書」を選択 3. jinrai-dev を探し、左の ▶ を開くと秘密鍵がぶら下がっているはず 4. 証明書の行(親)を右クリック → 「"jinrai-dev"を書き出す…」 - 分類「自分の証明書」から書き出すと秘密鍵も一緒に含まれます 5. フォーマットは 「個人情報交換(.p12)」 を選択、保存先は任意(例: ~/Downloads/jinrai-dev.p12) 6. パスワードを設定(これが Secrets の MACOS_CERT_PASSWORD になります) - ローカルの秘密情報配下に `MACOS_CERT_PASSWORD_JINRAI` 7. base64 化してクリップボードへ: - `base64 -i ~/Downloads/jinrai-dev.p12 | pbcopy` 8. [[🦉JINRAI]]の `Secrets and variables` > `Actions` > `Secrets` > `Repository secrets` に - `MACOS_CERT_P12_BASE64` に貼り付け - `MACOS_CERT_PASSWORD` に手順6のパスワード ### 2. jinrai リポジトリの Secrets 登録 [[Fine-grained personal access token (GitHub)|Fine-grained personal access token]] として作成。 ![[2026-07-05-10-18-15.avif]] [[🦉JINRAI]]の `Secrets and variables` > `Actions` > `Secrets` > `Repository secrets` に `TAP_GITHUB_TOKEN` として登録。 ### 3. テストリリース ```console git tag v0.0.1 && git push origin v0.0.1 ``` 成功すると `jinrai.rb` が書き換わる。 https://github.com/tadashi-aikawa/homebrew-tap/blob/main/Casks/jinrai.rb > [!error]- パスワードがおかしい場合 > 以下のようなエラーになる > > ```error > security: SecKeychainItemImport: MAC verification failed during PKCS12 import (wrong password?) > Error: Process completed with exit code 1. > ``` > > パスワードが正しいかの確認は以下。 > > ```console > openssl pkcs12 -in ~/Downloads/jinrai-dev.p12 -info -noout -passin 'pass:<パスワード>' > ``` ### 4. インストールと動作確認 まずは開発版を停止。 ```console pkill -x JINRAI ``` tap指定でインストール。 ```console brew install tadashi-aikawa/tap/jinrai ``` インストール後、[[Raycast]]に表示されることを確認。起動もできた。 ![[2026-07-05-10-47-39.avif]] 他の確認項目。 ```bash # /Applications に配置されているか $ ls -d /Applications/JINRAI.app /Applications/JINRAI.app # quarantine が外れているか(postflight が効いていれば何も表示されないのが正解) $ xattr -l /Applications/JINRAI.app | grep quarantine # 署名が jinrai-dev か $ codesign -dvv /Applications/JINRAI.app 2>&1 | grep Authority Authority=jinrai-dev ``` ### 5. アンインストール ```console brew uninstall --cask jinrai ``` 起動中のプロセスは停止しないけど細かい問題なのでOK。止めたければ以下を実行しておく。 ```console pkill -x JINRAI ``` 再インストールの確認もしておく。 ```console brew install tadashi-aikawa/tap/jinrai ``` ## [[semantic-release]]対応 リリースのたびにリリースノートを作成したりバージョン指定するのは面倒なので。 ### プラン #### Context 現在の jinrai は `v*` タグを手動で push すると release.yml が起動し、ビルド → 署名 → zip → GitHub Release → Homebrew tap 更新まで自動実行される。これを jinrai-spoon と同じ semantic-release 方式に変更し、**GitHub Actions の Release ワークフローを手動実行(workflow_dispatch)するだけ**で、conventional commits からバージョン算出 → タグ作成 → リリースまで全自動になるようにする。 前提の確認結果: - jinrai には `v0.0.1` タグ・リリースが既に存在(remote にもあり)→ semantic-release はこれを起点に次バージョンを算出するので「初回リリースが 1.0.0 になる」問題は起きない - リリースアセット名は `JINRAI-<version>.zip` 固定(`UpdateChecker.swift:68` がこの名前でアセットを探すため変更不可) - コミットは conventional commits 形式(feat/fix/style/docs/ci...)で運用済み #### 変更内容 ##### 1. `release.config.cjs`(新規) jinrai-spoon の `release.config.cjs` をベースにコピー。変更点: - `@semantic-release/exec`: - `prepareCmd: "./scripts/build_release.sh ${nextRelease.version}"` - `successCmd: "./scripts/update_tap.sh ${nextRelease.version}"`(GitHub Release 成功後に tap 更新) - `@semantic-release/github` の assets: `{ path: "dist/JINRAI-*.zip", label: "JINRAI.app" }`(アセットパスはバージョン変数を展開できないため glob で指定) - releaseRules / release-notes の絵文字セクション定義は spoon と同一(breaking → minor の pre-v1 ルールも踏襲、TODO コメントも維持) ##### 2. `scripts/build_release.sh`(新規) spoon の `scripts/build_release.sh` に相当。現行 release.yml のビルド〜zip ステップを移植: 1. 引数バージョンの semver 検証 2. `./scripts/make-app.sh release "$VERSION"`(既存スクリプトをそのまま利用) 3. `codesign -dvv` で `Authority=jinrai-dev` を検証(ad-hoc フォールバック事故防止。現行 release.yml:47-49 と同じ) 4. `ditto -c -k --keepParent .build/JINRAI.app "dist/JINRAI-$VERSION.zip"` 5. zip の存在検証 ##### 3. `scripts/update_tap.sh`(新規) 現行 release.yml の「Update Homebrew tap」ステップ(63-77行)をスクリプト化: - 引数バージョンから `dist/JINRAI-$VERSION.zip` の sha256 を計算 - `TAP_GITHUB_TOKEN` 環境変数で homebrew-tap を clone し、`Casks/jinrai.rb` の version/sha256 を sed で書き換えて commit/push ##### 4. `.github/workflows/release.yml`(書き換え) spoon の release.yml の構成に、jinrai 固有の署名まわりを合成: - トリガ: `workflow_dispatch`(タグ push トリガは廃止) - main ブランチ以外なら中断するガード - `runs-on: macos-26`(Swift ビルドと codesign が必要なため。spoon の ubuntu ではなく現行踏襲) - 証明書 import ステップは現行のまま維持(release.yml:20-38) - `actions/checkout@v6` + `fetch-depth: 0`(semantic-release がタグ履歴を読むため必須) - Node.js 24 + pnpm セットアップ後、spoon と同じ `pnpm dlx --package [email protected] --package [email protected] --package @semantic-release/exec semantic-release` を実行 - env: `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`, `TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}` - `permissions: contents: write` は維持(semantic-release がタグ push・Release 作成に使用) ##### 5. `README.md` のリリース節更新 「タグを push する」手順を「Actions の Release ワークフローを手動実行する」に書き換え。バージョンは conventional commits から自動決定される旨を記載(グローバルの `/release` コマンドが README を参照して実行するため、ここが正確であることが重要)。 #### 変更しないもの - `scripts/make-app.sh` / `Resources/Info.plist` のバージョン埋め込み機構(そのまま build_release.sh から利用) - `ci.yml` - リリースノート生成は `--generate-notes` から semantic-release の conventionalcommits プリセット(絵文字セクション)に変わる #### 検証方法 1. ローカルで `./scripts/build_release.sh 0.0.0-test` を実行し、`dist/JINRAI-0.0.0-test.zip` が生成されることを確認(ローカルは jinrai-dev 証明書がなければ署名検証はスキップ or CI のみで検証するよう分岐 — spoon の ci.yml が `0.0.0-test` でビルド検証しているのと同様) - 注: 署名検証(Authority=jinrai-dev)はローカルに証明書があれば通る。なければこのステップだけ CI 依存 2. `pnpm dlx ... semantic-release --dry-run` をローカルで実行し、release.config.cjs の構文と次バージョン算出を確認(GITHUB_TOKEN 必要) 3. コミット・push 後、GitHub Actions で Release ワークフローを手動実行し、以下を確認: - 新バージョンのタグ・GitHub Release が作成され、`JINRAI-<version>.zip` が添付されている - リリースノートが絵文字セクション付きで生成されている - homebrew-tap の `Casks/jinrai.rb` が更新されている ## アップデートのテスト まずは **新しいバージョンがない状態で** 以下を実行。何も起こらなければOK。 ```console brew upgrade --cask jinrai ``` 次の **新しいバージョンをリリースしてから** 実行。 ```console pkill -x JINRAI brew update brew upgrade --cask jinrai ``` これで更新・再起動すればOK。