sync-packages

name	sync-packages
description	パッケージの追加・削除・インストール・セットアップ時に全プラットフォーム（macOS/Linux/Windows）の 整合性を確保する。「〜を追加して」「〜をインストールして」「〜を入れて」「〜をセットアップ」 「〜を削除して」「Brewfile に〜」「dotfiles に〜を追加」等のパッケージ変更リクエストで必ず実行。 CLI ツール、GUI アプリ、言語ランタイム、NPM パッケージ、VS Code 拡張の追加・削除すべてに適用。

Sync Packages

パッケージを追加・削除する際に、全プラットフォーム（macOS, Linux, Windows）間の整合性を確保するスキル。

パッケージを追加・削除する場合は、必ずこのスキルに従って全プラットフォームの整合性を確認・更新すること。

対象ファイル

• config/packages/Brewfile — macOS/Linux CLI ツール + macOS cask (GUI)
• config/packages/apt-packages.txt — Ubuntu/Debian システム依存パッケージ
• scripts/installers/apt.sh — Linux GUI アプリ個別インストーラー（snap/flatpak/.deb）
• install.ps1 — Windows: Scoop / WinGet / NPM / PowerShell モジュール
• install.sh — 全 OS のセットアップエントリーポイント（Obsidian 個別インストール含む）
• src/.config/mise/config.toml — mise 共通設定（node LTS ベース）
• src/.config/mise/config.personal.toml — Personal: AI CLI ツール（NPM）+ node バージョン
• src/.config/mise/config.work.toml — Work: 最小構成（空）
• mise.toml(ルート) — リポジトリローカル開発ツール(terraform / trivy / biome)
• Brewfile(ルート) — CI/最小構成用(config/packages/Brewfile のサブセット)
• src/.vscode/extensions.json — VS Code 拡張機能（全 OS 共通）

パッケージ種別判定フロー

1. CLI ツール → 全プラットフォーム共通セクションへ
2. GUI アプリ → プラットフォーム別セクションへ
3. 言語ランタイム・開発ツール → mise 設定へ
4. NPM グローバルパッケージ → mise config.personal.toml + install.ps1 NPM
5. VS Code 拡張 → extensions.json へ
6. OS 専用 → 該当 OS のファイルのみ

パッケージ種別と配置先

CLI ツール（全プラットフォーム共通）

• macOS/Linux: config/packages/Brewfile に brew "name" で追加
• Windows: install.ps1 の Install-ScoopPackages 内 $packages 配列に追加

サードパーティの brew パッケージは tap が必要:

# Brewfile
tap "owner/repo"
brew "owner/repo/name"  # 説明

Scoop でデフォルト bucket にないパッケージは、Install-ScoopPackages 内で bucket 追加済みか確認:

# install.ps1 - 既存の bucket 追加
scoop bucket add extras 2>$null
scoop bucket add nerd-fonts 2>$null

GUI アプリ（クロスプラットフォーム）

• macOS: Brewfile の if OS.mac? 内に cask "name" で追加
• Linux: apt.sh に install_xxx() 関数を追加
• Windows: install.ps1 の Install-WingetPackages 内 $packages 配列に追加

Linux の GUI アプリは snap/flatpak/.deb のいずれかでインストールする。apt.sh の既存関数パターンを参照:

# apt.sh - 新規 GUI アプリ関数テンプレート
install_xxx() {
  log_info "Installing XXX..."

  local os
  os=$(detect_os)
  if [[ "$os" != "ubuntu" && "$os" != "mint" && "$os" != "linux" ]]; then
    log_warn "XXX installation is only available on Ubuntu/Debian/Mint. Skipping..."
    return 0
  fi

  if command -v xxx &>/dev/null; then
    log_debug "XXX is already installed"
    return 0
  fi

  if [[ "${DRY_RUN:-false}" == "true" ]]; then
    log_info "[DRY-RUN] Would install XXX"
    return 0
  fi

  # snap → flatpak → .deb の優先順位でインストール
  if command -v snap &>/dev/null; then
    log_info "Installing XXX via Snap..."
    sudo snap install xxx
  elif command -v flatpak &>/dev/null; then
    log_info "Installing XXX via Flatpak..."
    flatpak install -y flathub org.example.XXX
  else
    log_warn "Neither snap nor flatpak available. Skipping XXX installation."
    return 0
  fi

  log_success "XXX installed"
}

Linux GUI アプリを追加したら、install.sh の main() 関数内から呼び出しを追加する。Server モードチェック内に配置すること:

# install.sh - main() 内
if [[ "${SERVER_MODE:-false}" != "true" ]]; then
  install_xxx  # ← 追加
fi

WinGet パッケージは Publisher.AppName 形式:

# install.ps1 - Install-WingetPackages 内
$packages = @(
    "Microsoft.VisualStudioCode",
    "Publisher.NewApp"           # ← 追加
)

macOS 専用アプリ

Brewfile の if OS.mac? ブロックに cask で追加。他プラットフォームへの追加は不要。

if OS.mac?
  cask "raycast"
  cask "karabiner-elements"
end

Linux 専用パッケージ

• システム依存パッケージ: apt-packages.txt に1行追加
• GUI アプリ: apt.sh に install_xxx() 関数を追加

Brewfile で Linux 専用の brew パッケージは条件付きで追加:

brew "xsel" if OS.linux?  # clipboard support for Linux

Windows 専用アプリ

install.ps1 の該当関数（Scoop or WinGet）に追加。

言語ランタイム・開発ツール

• グローバル共通(node LTS 等) → src/.config/mise/config.toml
• Personal 用ツール(AI CLI 等) → src/.config/mise/config.personal.toml
• Work 用ツール → src/.config/mise/config.work.toml
• リポジトリローカル(terraform 等) → mise.toml(ルート)

mise はプラットフォーム差を吸収するため、OS 固有の対応は不要。

注意: ルートの mise.toml はリポジトリ開発用。グローバルツールの追加先は src/.config/mise/ 配下の設定ファイル。

NPM グローバルパッケージ

• macOS/Linux: src/.config/mise/config.personal.toml に追加
• Windows: install.ps1 の Install-NpmPackages 内 $npmPackages 配列に追加

# src/.config/mise/config.personal.toml
[tools]
"npm:@scope/package-name" = "latest"

# install.ps1 - Install-NpmPackages 内
$npmPackages = @(
    "vercel",
    "@google/gemini-cli",
    "@new/package"          # ← 追加
)

フォントパッケージ

プラットフォームごとに名前・インストール方法が異なる:

• macOS: Brewfile に cask "font-hackgen-nerd"
• Windows: Scoop に "Hack-NF"（nerd-fonts bucket が必要）
• Linux: apt-packages.txt に fonts-noto-cjk

HackGen フォントは Windows では手動インストールが必要（Scoop に未登録）。

PowerShell モジュール（Windows 専用）

install.ps1 の Install-PowerShellModules 関数内に追加:

Install-Module -Name ModuleName -Scope CurrentUser -Force -AllowClobber

VS Code 拡張機能

src/.vscode/extensions.json の recommendations 配列に追加:

{
  "recommendations": [
    "publisher.extension-id"
  ]
}

macOS/Linux は scripts/installers/vscode.sh、Windows は install.ps1 の Install-VSCodeExtensions がこのファイルを読む。

Work/Personal モード

Personal パッケージ（--work フラグで除外される）の配置ルール:

• macOS Brewfile: if OS.mac? && ENV['WORK_MODE'] != 'true' ブロック
• Linux apt.sh: 各 install_xxx() 関数内で WORK_MODE チェック
• Windows Scoop: if (-not $Work) { $packages += "..." } ブロック
• Windows WinGet: if (-not $Work) { $packages += "..." } ブロック
• mise: config.personal.toml（Work 時は config.work.toml が使用される）

Personal パッケージ例: orbstack / spotify / discord / podman-desktop / AI CLI ツール。

Server モード

--server フラグで GUI アプリをスキップ。以下が除外対象:

• Linux: albert / 1password / vscode / ghostty / wezterm / spotify / discord / obsidian / podman-desktop
• 日本語フォント・入力メソッド
• VS Code 拡張機能

GUI アプリを追加する場合は、install.sh の SERVER_MODE チェック内に配置すること。 apt.sh で SERVER_MODE をチェックしている箇所: install_apt_packages（日本語環境）, install_podman（Podman Desktop）。

手順

パッケージ追加の場合

1. 種別を判定: CLI / GUI / 言語ランタイム / NPM / VS Code 拡張 / OS 専用
2. 上記マッピングに従い、該当する全ファイルにパッケージを追加
3. 各ファイルの既存パターンに従う:
   • Brewfile: セクションコメントに合わせて適切な位置に挿入し、インラインコメントで用途を記述
   • install.ps1: 該当関数内の $packages 配列に追加
   • apt.sh: 既存の install_xxx() 関数パターンに従って関数を追加
   • mise: 正しい設定ファイルに [tools] セクションで追加
   • extensions.json: recommendations 配列に追加
4. 前提条件を確認: Homebrew tap や Scoop bucket が必要か
5. Personal パッケージの場合: Work モード除外ブロックに配置
6. GUI アプリの場合: Server モード除外を考慮
7. ルート Brewfile への追加が必要か確認（CI/最小構成で必要なパッケージのみ）

パッケージ削除の場合

1. 全対象ファイルから該当パッケージのエントリを削除
2. apt.sh の場合は関数本体と install.sh からの呼び出しの両方を削除
3. extensions.json から VS Code 拡張を削除（該当する場合）
4. mise 設定から削除（該当する場合）
5. 不要になった tap / bucket があれば削除

チェック項目

• CLI ツールが Brewfile と install.ps1 Scoop の両方に存在するか
• GUI アプリが macOS (cask) / Linux (apt.sh) / Windows (WinGet) の全てに対応しているか
• Personal パッケージが全プラットフォームで Work モード除外されているか
• 各ファイルのコメントスタイル・セクション構造が既存パターンと一致しているか
• install.sh の main() から新規関数が呼び出されているか（Linux GUI アプリの場合）
• VS Code 拡張が必要なツールの場合、extensions.json に追加されているか
• Homebrew tap / Scoop bucket が必要な場合、追加されているか
• mise の正しい設定ファイルに追加されているか（ルート mise.toml ではなく src/.config/mise/ 配下）
• Server モード対応が必要な GUI アプリの場合、SERVER_MODE チェックが入っているか
• フォントの場合、プラットフォームごとの名前の違いを考慮しているか

検証

just lint

すべてのチェックが Passed になるまで修正を繰り返す。

変更後は sync-install-docs スキルも実行してドキュメントの整合性を確認すること。