add-install

name	add-install
description	Use when adding or updating a setup.d installer in this dotfiles repo and the task needs local style, placement, and smoke-check guidance

Add Install

Overview

在這個 repo 新增安裝步驟時，先判斷它應該落在哪個 setup.d 腳本，再比照既有 installer 寫法實作。重點不是把指令貼上去，而是讓它和現有執行順序、Early Skip 與驗證模型一致。

When to Use

• 使用者要把新工具、新 app、或新的官方 installer 加進 setup.d/
• 需要判斷應該新增獨立腳本，還是併入既有分組腳本
• 需要比照這個 repo 的 common-lib、pass/change/fail、Early Skip 與 smoke check 慣例

不要用在：

• 單純修改 files/ 內的 shell alias 或 env 設定，沒有碰 setup.d/
• 已有明確現成腳本，只是做小幅參數調整

Workflow

1. 先找現況：
   • 搜 setup.d/ 是否已有該工具或同類工具
   • 搜 files/.bashrc、files/.profile 是否已經有相關 env/init 片段
   • 讀 setup.d/AGENTS.md，確認 Early Skip 和前置依賴規則
2. 判斷歸位：
   • 若工具屬於既有集合而且同一腳本已管理同類 installer，才考慮併入
   • 若工具有獨立生命週期、獨立官方 installer、或和既有集合耦合低，優先新增獨立 setup.d/<nn>-<name>
3. 套用骨架：
   • 使用 common-lib 載入樣板
   • 只在「全部目標都已就緒」時 Early Skip
   • 缺少必要前置時要 fail，不能假裝 skip 成功
   • 若 installer 會寫入私有 bin/env 檔，安裝前後都要考慮載入該 env 再檢查 command
4. 做最小驗證：
   • bash -n setup.d/<script>
   • 若檔案是新建的，設 executable bit
   • 能低成本驗證時，再確認安裝後的主要 command 可被偵測

Placement Heuristics

• 50-56 類腳本偏向語言工具鏈與 package manager 生態
• 70+ 類腳本偏向獨立工具、桌面 app、或第三方安裝流程
• 有明確官方 curl | sh installer 的單一工具，通常適合獨立腳本，不要硬塞進語言工具集合

Checklist

• 是否先確認 repo 內已有相關 shell/init 設定？
• 是否選了正確的 setup.d 編號與歸類？
• Early Skip 是否只檢查完整成功條件？
• 安裝後是否做了至少一個 smoke check？
• 是否避免改動不相干的 setup 腳本？