nix-profile-manager

エージェント向け Nix プロファイルマネージャー

概要

このスキルを使用すると、エージェントはユーザーが指定したディレクトリ内のローカル Nix プロファイルを管理できます。システム全体のパッケージ管理や sudo アクセスを必要とせず、ツールを動的にインストールできます。

クイックスタート：ローカルプロファイルの設定

ユーザーはエージェントが管理するディレクトリを PATH 内に指定し、エージェントがその場所を認識できるように、AGENT_PROFILE 環境変数にこのディレクトリを設定する必要があります。

その後、エージェントは次のコマンドを実行するだけです。

nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

--profile フラグは、Nix にプロファイルのメタデータをその場所に保存するよう指示します。 Nix がプロファイル内に作成する bin ディレクトリを PATH に含める必要があります。

注：古いバージョンの Nix では、add サブコマンドは install という名前でした。「add」が存在しないというエラーが表示された場合は、この点に注意してください。

基本概念

プロファイル

プロファイルとは、次のものを含むディレクトリです。

• manifest.json - インストール済みパッケージとそのフレーク参照の一覧
• bin、lib、share など - Nix ストア内のバイナリ、ライブラリ、ドキュメントへのシンボリックリンクを含むフォルダー

nix profile add を実行すると、Nix はマニフェストを更新し、シンボリックリンクを再作成します。

フレーク

フレークとは、次の特徴を持つ標準化された Nix パッケージコレクションです。

• 入力と出力を定義する flake.nix ファイル
• flake.lock による決定論的なバージョン管理
• 複数の出力スキーム（パッケージ、オーバーレイ、モジュールなど）

一般的なフレーク：

• nixpkgs - 標準パッケージライブラリ（デフォルトのレジストリ）。通常は github:NixOS/nixpkgs/nixpkgs-unstable のエイリアスです
• GitHub のカスタムフレーク（例：github:user/repo）

パッケージとフレーク

• パッケージ：単一のツール（例：git、python311）
• フレーク：パッケージのコレクション。<flake>#<package> としてアクセスします

重要：nixpkgs などのフレークでは、パッケージが入れ子になっている場合があります。例：<flake>#<scope>.<package>

基本的なコマンド

パッケージを検索する

# Search in nixpkgs flake:
nix search nixpkgs git

# Search in specific (fully qualified) flake
nix search "github:user/repo[/branch]" <package-name>

# Or get a more detailed JSON output
nix search nixpkgs python3 --json | jq '.[].pname'

プロファイルを管理する

# Add package
nix profile add --profile <profile_path> "<flake>#<package>"

# List installed packages
nix profile list --profile <profile_path>

# Remove by index or element number
nix profile remove --profile <path>/profile 0

# Upgrade packages
nix profile upgrade --profile <profile_path> <package_name>
nix profile upgrade --profile <profile_path> --all  # All packages installed in this profile

レジストリを管理する

# List available flake aliases
nix registry list

# Add custom registry entry (user-level)
nix registry add myflake github:user/repo/branch

一般的なワークフロー

# Determine profile path:
echo $AGENT_PROFILE  # If not defined, ask the user which profile to use!!

# Search for the package
nix search nixpkgs git

# Add it
nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

# Just use it!
tool-cmd ...

重要な詳細

• プロファイルパス内の bin サブフォルダーを PATH に含める必要があります：リンクされたバイナリを利用できるように、プロファイルを含むディレクトリを $PATH に含めてください
• フレーク参照は不変です：nixpkgs#git は現在の nixpkgs バージョンに解決されます。特定の参照に固定するには、github:user/repo/ref#package を使用してください
• プロファイルのロック：一度にプロファイルを変更できるエージェントは 1 つだけです。ロックは自動では行われません
• ストアリンクの有効期限はありません：フレークが変更されても Nix ストアのパスは有効なままです。必要に応じて、プロファイルは以前のパッケージパスを保持します

トラブルシューティング

パッケージが見つからない場合：

• フレーク名が正しいことを確認してください。nix registry list で利用可能なエイリアスを確認できます
• nix search <flake> <partial-name> で検索し、正確なパッケージ名を確認してください

インストール後にコマンドが PATH にない場合：

• プロファイルディレクトリが $PATH に含まれていることを確認してください：echo $PATH
• $AGENT_PROFILE が作成されていることを確認してください：ls -la $AGENT_PROFILE（必要に応じてパスを調整してください）

アクセスが拒否された場合：

• ローカルプロファイルでは sudo は必要ありません。権限の問題が発生した場合は、ユーザーに報告してください

参考資料

• references/flakes.md - フレークの概念と GitHub の参照に関する詳しい説明
• references/package-search.md - 高度なパッケージ検索手法
• references/profile-internals.md - プロファイルの構造とマニフェストの形式
• references/registry.md - カスタムレジストリの設定と固定

エージェントへの実装ガイド

エージェントにプロファイル管理を実装する場合：

1. 環境変数またはパラメーターとしてプロファイルパスを受け取る - 例：AGENT_PROFILE または関数の引数
2. インストール前に必ず検索する - パッケージが存在し、名前が正確であることを確認する
3. 解析には --json 出力を使用する - テキスト出力よりも信頼性が高い
4. エラーを適切に処理する - すべてのフレークに存在するとは限りません
5. プロファイルの変更を通知する - 何がインストールされたかユーザーが追跡できるようにする