feat(nix): install-nix.zsh + README 整備で一発セットアップを実現 (S12 / KISSA-32)

README.md

@@ -1,18 +1,120 @@
 # dotfiles
 
-## Initialize Setup
+`~/.dotfiles` の macOS 開発環境を **Nix（nix-darwin + home-manager + flakes）** で宣言的に再現するための dotfiles。`darwin-rebuild switch` 一発で全パッケージ・全設定が復元される。
 
-1. Install XCode
-```terminal
+詳細手順（ロールバック、新ホスト追加、トラブルシュート）は [`nix/README.md`](nix/README.md) を参照。
+
+## 前提
+
+- macOS (Apple Silicon: `aarch64-darwin` / Intel: `x86_64-darwin`)
+- 既存ホスト構成は `m5mbp` のみ（`nix/flake.nix` で宣言済み）
+- 新ホストを追加する場合は [`nix/README.md` の「別 PC への展開」](nix/README.md#別-pc-への展開) を参照
+
+## セットアップ
+
+以下を上から順に実行すれば完了する。
+
+### 1. Full Disk Access を付与する
+
+Nix インストーラは `/etc` 配下に書き込みを行うため、実行元ターミナル（Terminal.app, iTerm2 等）に **Full Disk Access (FDA)** が必要。macOS 15 では FDA なしでは root でも書き込みが拒否される。
+
+1. **System Settings → Privacy & Security → Full Disk Access** を開く
+2. 自分が使うターミナルアプリを追加して有効化する
+3. ターミナルを**完全に終了**して起動し直す（プロセス再起動で TCC が反映される）
+
+### 2. Xcode Command Line Tools をインストール
+
+```sh
 xcode-select --install
 ```
 
-2. Install Homebrew
-```terminal
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+完了するまで待つ（GUI ダイアログが出る）。
+
+### 3. リポジトリを clone
+
+```sh
+git clone https://github.com/gotomts/dotfiles.git ~/.dotfiles
+```
+
+### 4. Determinate Nix をインストール
+
+```sh
+zsh ~/.dotfiles/nix/scripts/install-nix.zsh
+```
+
+このスクリプトは:
+
+- 既に Nix がインストール済みなら skip する
+- FDA 未付与なら手順 1 に戻るよう促して停止する
+- Determinate Nix の公式インストーラを非対話モードで起動する
+
+インストール成功後、**ターミナルを再起動**するか以下を実行する:
+
+```sh
+source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+```
+
+### 5. ビルド確認（switch 前のドライラン）
+
+```sh
+cd ~/.dotfiles/nix
+nix flake check --no-build
+darwin-rebuild build --flake .#m5mbp
+```
+
+副作用なしに closure がビルドできれば次へ。
+
+### 6. 適用
+
+```sh
+sudo darwin-rebuild switch --flake .#m5mbp
+```
+
+初回は nix-darwin のブートストラップが走るため、終了後に**ターミナルを再起動**する。
+
+> ⚠ `homebrew.onActivation.cleanup = "zap"` 設定により、`nix/modules/darwin/homebrew.nix` に宣言されていない Homebrew パッケージは初回 switch で削除される。手元のパッケージが消えて困るものがあれば、先に `nix/modules/darwin/homebrew.nix` に追加してから switch すること。
+
+## 完了確認
+
+セットアップ後、以下が成立していれば成功:
+
+- [ ] `which zsh` が nix-managed のパスを指す
+- [ ] `starship --version` が応答する
+- [ ] `yazi --version` が応答する
+- [ ] `claude --version` が応答する（Claude Code）
+- [ ] `ls -la ~/.claude/agents ~/.claude/skills` が **dotfiles 配下への symlink** になっている
+- [ ] `rtk --version` が応答する（rtk overlay 経由）
+- [ ] `node --version` / `dart --version` / `grip --version` が応答する（home-manager languages.nix）
+- [ ] `brew list --cask` の出力が `nix/modules/darwin/homebrew.nix` の宣言と一致する
+- [ ] `sudo pmset -g` を NOPASSWD で実行できる（sudoers.nix）
+- [ ] Touch ID で `sudo` できる（pam.nix）
+
+## 通常運用
+
+```sh
+cd ~/.dotfiles/nix
+
+# inputs を最新化
+nix flake update
+
+# ビルド確認
+darwin-rebuild build --flake .#m5mbp
+
+# 適用
+sudo darwin-rebuild switch --flake .#m5mbp
+
+# 直前世代に戻す
+sudo darwin-rebuild switch --rollback
 ```
 
-3. Install my dot files:
-```terminal
-zsh -c "$(curl -s https://raw.githubusercontent.com/gotomts/dotfiles/master/setup/setup.zsh)"
-```
+詳細は [`nix/README.md`](nix/README.md) を参照。
+
+## アーキテクチャ
+
+- `nix/flake.nix` — inputs / outputs ルート
+- `nix/hosts/m5mbp/{darwin,home}.nix` — ホスト固有の module 集約
+- `nix/modules/darwin/` — nix-darwin module（homebrew, sudoers, fonts, pam）
+- `nix/modules/home/` — home-manager module（packages, zsh, git, starship, yazi, ssh, claude, languages）
+- `nix/modules/overlays/rtk.nix` — rtk (Rust Token Killer) を `pkgs.rtk` として供給する overlay
+- `nix/scripts/install-nix.zsh` — Determinate Nix インストーラ薄ラッパー（FDA pre-check + idempotent skip）
+- `setup/` / `Brewfile` — Phase B で削除予定のレガシー資産。新規セットアップでは使用しない

nix/README.md

@@ -1,6 +1,8 @@
 # nix/
 
-このディレクトリは `~/.dotfiles` の環境構築を **Nix（nix-darwin + home-manager + flakes）** で一元管理する Phase A の作業対象です。宣言的・再現可能・マルチホスト対応な環境を `darwin-rebuild switch` 一発で復元できる状態を目指します。
+このディレクトリは `~/.dotfiles` の環境構築を **Nix（nix-darwin + home-manager + flakes）** で一元管理する。宣言的・再現可能・マルチホスト対応な環境を `darwin-rebuild switch` 一発で復元する。
+
+新規セットアップ手順は [ルート README](../README.md) を参照。本ドキュメントは詳細・運用・トラブルシュートを扱う。
 
 関連ドキュメント:
 
@@ -20,103 +22,78 @@ nix/
 │       └── home.nix        # home-manager module 集約（mkHost.nix から直接 import）
 ├── lib/
 │   └── mkHost.nix          # ホスト合成ヘルパー
-└── modules/                # S3-S11 で順次追加予定
-    ├── darwin/
-    └── home/
+├── modules/
+│   ├── darwin/             # nix-darwin module (homebrew / sudoers / fonts / pam)
+│   ├── home/               # home-manager module (packages / zsh / git / starship / yazi / ssh / claude / languages)
+│   └── overlays/
+│       └── rtk.nix         # rtk (Rust Token Killer) を pkgs.rtk として供給する overlay
+└── scripts/
+    ├── install-nix.zsh     # Determinate Nix インストーラ薄ラッパー
+    ├── inventory.zsh       # macOS defaults / brew 棚卸スクリプト (S1)
+    └── tests/
+        └── inventory.bats  # inventory.zsh の bats テスト
 ```
 
 ## 前提条件
 
-- **Xcode Command Line Tools** がインストール済みであること
-- **Nix** がインストール済みであること（[Determinate Systems インストーラ](https://github.com/DeterminateSystems/nix-installer) 推奨）
-- **nix-darwin** は flake から自動適用されるため、事前インストール不要
-
-## 初回セットアップ手順
-
-### 1. Xcode Command Line Tools のインストール
-
-```sh
-xcode-select --install
-```
-
-### 2. Nix のインストール（Determinate Systems インストーラ推奨）
+- **macOS** (Apple Silicon: `aarch64-darwin` / Intel: `x86_64-darwin`)
+- **Xcode Command Line Tools** がインストール済み
+- **Full Disk Access (FDA)** が実行元ターミナルに付与済み（`/etc` 書き込みに必須）
+- **Determinate Nix** がインストール済み（`nix/scripts/install-nix.zsh` 経由でインストール）
 
-```sh
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-```
-
-インストール後、ターミナルを再起動するか以下を実行:
-
-```sh
-source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
-```
+nix-darwin / home-manager は flake から自動適用されるため、事前インストール不要。
 
-### 3. flake.lock の生成（初回 or 更新時）
+## 通常運用
 
 ```sh
 cd ~/.dotfiles/nix
-nix flake update
-```
-
-### 4. ビルド確認（switch 前の確認）
 
-副作用なしにビルドが通るか確認する:
+# inputs を最新化
+nix flake update
 
-```sh
-cd ~/.dotfiles/nix
+# ビルド確認 (副作用なし)
 darwin-rebuild build --flake .#m5mbp
-```
 
-### 5. 適用
+# 適用
+sudo darwin-rebuild switch --flake .#m5mbp
 
-```sh
-cd ~/.dotfiles/nix
-darwin-rebuild switch --flake .#m5mbp
+# CI と同じ closure ビルドだけを確認
+nix build .#darwinConfigurations.m5mbp.system --no-link --print-out-paths
 ```
 
-初回実行時は nix-darwin のブートストラップも行われるため、ターミナルの再起動が必要な場合があります。
-
-## 通常の更新手順
-
-```sh
-cd ~/.dotfiles/nix
-
-# input を最新に更新
-nix flake update
+## 別 PC への展開
 
-# ビルド確認
-darwin-rebuild build --flake .#m5mbp
+### 既存ホスト (m5mbp) と同等のセットアップを別 PC で再現する
 
-# 確認できたら適用
-darwin-rebuild switch --flake .#m5mbp
-```
+新しい PC でも `hostname = "m5mbp"` のままなら、[ルート README のセットアップ手順](../README.md#セットアップ)を上から実行するだけで完了する。`install-nix.zsh` が冪等なので、既に Nix がある環境でも安全に再実行できる。
 
-## 別 PC への展開
+### 新しいホストを追加する
 
-### 新しいホストを追加する手順
+別の hostname（例: `m6mbp`）で運用したい場合:
 
-1. `nix/hosts/<new-hostname>/` ディレクトリを作成する
-2. `darwin.nix`・`home.nix` を `m5mbp/` からコピーして編集する
+1. `nix/hosts/m6mbp/` ディレクトリを作成する
+2. `darwin.nix` / `home.nix` を `m5mbp/` からコピーして編集する
 3. `nix/flake.nix` の `outputs` に新しいホストを追加する:
    ```nix
-   darwinConfigurations.<new-hostname> = mkHost {
-     hostname = "<new-hostname>";
+   darwinConfigurations.m6mbp = mkHost {
+     hostname = "m6mbp";
      system = "aarch64-darwin";  # Intel Mac の場合は "x86_64-darwin"
      username = "goto";
    };
    ```
-4. 新しい PC で上記の初回セットアップ手順を実行する:
+4. 新しい PC で初回セットアップ:
    ```sh
+   # ルート README の手順 1-4 を実行 (FDA / CLT / clone / install-nix.zsh)
    cd ~/.dotfiles/nix
-   darwin-rebuild switch --flake .#<new-hostname>
+   darwin-rebuild build --flake .#m6mbp
+   sudo darwin-rebuild switch --flake .#m6mbp
    ```
 
 ## ロールバック
 
-前の世代に戻す:
+直前世代に戻す:
 
 ```sh
-cd ~/.dotfiles/nix
 sudo darwin-rebuild switch --rollback
 ```
 
@@ -130,30 +107,58 @@ darwin-rebuild --list-generations
 sudo darwin-rebuild switch -G <generation-number>
 ```
 
-home-manager のロールバック:
+home-manager 個別のロールバック:
 
 ```sh
 home-manager generations
 home-manager switch --switch-generation <id>
 ```
 
-## flake.lock の更新方針
+## flake.lock の更新運用
 
 - `nix flake update` で全 input を最新に更新できる
 - 特定 input だけ更新する場合: `nix flake lock --update-input nixpkgs`
 - 更新後は必ず `darwin-rebuild build` でビルドを確認してからコミットすること
 - `flake.lock` は必ずコミットすること（再現性確保のため）
+- 更新頻度の方針: **必要時のみ**（依存ライブラリの脆弱性 / nixpkgs に必要なパッケージが入ったタイミング等）。定期更新は CI に依存しない手動運用
 
 ## トラブルシューティング
 
+### Full Disk Access (FDA) 未付与で `install-nix.zsh` が停止する
+
+スクリプトが以下のエラーで停止した場合:
+
+```
+Full Disk Access is NOT granted to the current terminal.
+```
+
+1. **System Settings → Privacy & Security → Full Disk Access** を開く
+2. 自分が使うターミナルアプリ（Terminal.app, iTerm2, etc.）を追加して有効化する
+3. ターミナルを**完全に終了**して起動し直す（プロセス再起動で TCC が反映される）
+4. `zsh ~/.dotfiles/nix/scripts/install-nix.zsh` を再実行
+
+macOS 15 では FDA なしでは root でも `/etc` への書き込みが TCC で拒否されるため、`sudo` をつけても回避できない。Claude Code 経由 (osascript with administrator privileges) でも同様に回避不可。
+
+### Determinate Nix と nix-darwin が競合する
+
+`darwin-rebuild switch` 実行時に以下のエラーで失敗した場合:
+
+```
+error: Determinate detected, aborting activation
+Determinate uses its own daemon to manage the Nix installation that
+conflicts with nix-darwin's native Nix management.
+```
+
+`nix/hosts/<host>/darwin.nix` で `nix.enable = false;` が宣言されているか確認する。S14 (KISSA-46) で対処済みの本番ブロッカー。詳細は `hosts/m5mbp/darwin.nix` のコメントを参照。
+
 ### flake.lock が壊れた / hash 不整合
 
 ```sh
 git restore nix/flake.lock
 nix flake update
 ```
 
-### darwin-rebuild が失敗した場合
+### `darwin-rebuild` がビルドエラーで失敗する
 
 ビルドエラーのログを確認:
 
@@ -176,15 +181,25 @@ cd ~/.dotfiles/nix
 nix run nix-darwin -- switch --flake .#m5mbp
 ```
 
-## 現在の状態（Phase A S2 完了時点）
-
-- [x] S2: flake 雛形 + mkHost ヘルパー
-- [ ] S3: home-manager packages.nix（CLI ツール群）
-- [ ] S4: home-manager zsh.nix
-- [ ] S5: home-manager git / starship / yazi / ssh
-- [ ] S6: home-manager claude.nix
-- [ ] S7: home-manager languages.nix
-- [ ] S8: rtk overlay
-- [ ] S9: nix-darwin homebrew.nix
-- [ ] S10: nix-darwin defaults.nix
-- [ ] S11: nix-darwin sudoers / fonts / pam
+### Homebrew パッケージが消えた
+
+`homebrew.onActivation.cleanup = "zap"` 設定により、`nix/modules/darwin/homebrew.nix` に宣言されていない Homebrew パッケージは初回 switch で削除される。残したいパッケージは `nix/modules/darwin/homebrew.nix` に追加してから switch すること。
+
+## Phase A の進捗
+
+- [x] S1: 棚卸スクリプト + bats テスト (KISSA-21)
+- [x] S2: flake 雛形 + mkHost ヘルパー (KISSA-22)
+- [x] S3: home-manager packages.nix (KISSA-23)
+- [x] S4: home-manager zsh.nix (KISSA-24)
+- [x] S5: home-manager git / starship / yazi / ssh (KISSA-25)
+- [x] S6: home-manager claude.nix - plugin sync activation (KISSA-26)
+- [x] S7: home-manager languages.nix - mise 完全置換 (KISSA-27)
+- [x] S8: rtk overlay (KISSA-28)
+- [x] S9: nix-darwin homebrew.nix - cask + mas + 例外 brew (KISSA-29)
+- [ ] S10: nix-darwin defaults.nix - 棚卸 triage 翻訳 (KISSA-30, 別途着手予定)
+- [x] S11: nix-darwin sudoers / fonts / pam (KISSA-31)
+- [x] S12: 検証 + README + 別 PC 手順 + install-nix.zsh (KISSA-32)
+- [x] S13: CLAUDE.md に Nix 環境セクション追記 (KISSA-33)
+- [x] S14: GitHub Actions nix flake check + closure build (KISSA-46)
+
+Phase B（`setup/setup.zsh` / `Brewfile` の削除等）は別エピックで実施予定。