OrgとNixによる文芸的設定集

3.1.1.1.1. nixpkgs#

nixpkgs.url = "git+https://github.com/nixos/nixpkgs?shallow=1&ref=nixos-unstable-small";

3.1.1.1.2. nixpkgs-stable#

nixpkgs-stable.url = "git+https://github.com/nixos/nixpkgs?shallow=1&ref=nixos-26.05";

3.1.1.1.3. nixpkgs-cuda#

nixpkgs-cuda.url = "git+https://github.com/nixos-cuda/nixpkgs?shallow=1&ref=nixos-unstable-cuda";

3.1.1.2.1. flake-parts#

flake-parts = {
  url = "github:hercules-ci/flake-parts";
  inputs.nixpkgs-lib.follows = "nixpkgs";
};

3.1.1.3.1. flake-utils#

flake-utils.url = "github:numtide/flake-utils";

3.1.1.4.1. darwin#

darwin = {
  url = "github:nix-darwin/nix-darwin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.2. home-manager#

home-manager = {
  url = "github:nix-community/home-manager";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.3. nixos-wsl#

nixos-wsl = {
  url = "github:nix-community/nixos-wsl";
  inputs.flake-compat.follows = "";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.4. nix-on-droid#

nix-on-droid = {
  url = "github:nix-community/nix-on-droid";
  inputs.home-manager.follows = "home-manager";
  inputs.nix-formatter-pack.follows = "";
  inputs.nixpkgs-docs.follows = "nixpkgs";
  inputs.nixpkgs-for-bootstrap.follows = "nixpkgs";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.nmd.follows = "";
};

3.1.1.4.5. disko#

disko = {
  url = "github:nix-community/disko";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.4.6. impermanence#

impermanence.url = "github:nix-community/impermanence";

3.1.1.4.7. lanzaboote#

lanzaboote = {
  url = "github:nix-community/lanzaboote";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.pre-commit.follows = "git-hooks";
};

3.1.1.4.8. nixos-facter-modules#

nixos-facter-modules.url = "github:numtide/nixos-facter-modules";

3.1.1.5.1. comin#

comin = {
  url = "github:nlewo/comin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.2. microvm#

microvm = {
  url = "github:astro/microvm.nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.3. sops-nix#

sops-nix = {
  url = "github:Mic92/sops-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.4. tsnsrv#

tsnsrv = {
  url = "github:boinkor-net/tsnsrv";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.5.5. niks3#

niks3 = {
  url = "github:Mic92/niks3";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.treefmt-nix.follows = "treefmt-nix";
};

3.1.1.6.1. git-hooks#

git-hooks = {
  url = "github:cachix/git-hooks.nix";
  inputs.flake-compat.follows = "";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.6.2. treefmt-nix#

treefmt-nix = {
  url = "github:numtide/treefmt-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.7.1. nix-colors#

nix-colors = {
  url = "github:misterio77/nix-colors";
  inputs.nixpkgs-lib.follows = "nixpkgs";
};

3.1.1.7.2. nix-wallpaper#

nix-wallpaper = {
  url = "github:natsukium/nix-wallpaper/custom-logo";
  inputs.flake-utils.follows = "flake-utils";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.pre-commit-hooks.follows = "git-hooks";
};

3.1.1.8.1. brew-nix#

brew-api = {
  url = "github:BatteredBunny/brew-api";
  flake = false;
};
brew-nix = {
  url = "github:BatteredBunny/brew-nix";
  inputs.brew-api.follows = "brew-api";
  inputs.nix-darwin.follows = "darwin";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.2. edgepkgs#

edgepkgs = {
  url = "github:natsukium/edgepkgs";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.3. emacs-overlay#

emacs-overlay = {
  url = "github:nix-community/emacs-overlay";
  inputs.nixpkgs-stable.follows = "nixpkgs-stable";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.4. felis#

felis = {
  url = "git+https://git.natsukium.com/natsukium/felis";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.flake-parts.follows = "flake-parts";
  inputs.treefmt-nix.follows = "treefmt-nix";
  inputs.git-hooks.follows = "git-hooks";
};

3.1.1.8.5. firefox-addons#

firefox-addons = {
  url = "gitlab:rycee/nur-expressions?dir=pkgs/firefox-addons";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.6. hermes-agent#

hermes-agent = {
  url = "github:natsukium/hermes-agent/fix/nix-read-only-eval";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.7. mcp-servers#

mcp-servers = {
  url = "github:natsukium/mcp-servers-nix";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.8. org-clickup#

org-clickup = {
  url = "git+https://git.natsukium.com/natsukium/org-clickup";
  flake = false;
};

3.1.1.8.9. nur-packages#

nur-packages = {
  url = "github:natsukium/nur-packages";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.10. paneru#

paneru = {
  url = "github:karinushka/paneru";
  inputs.flake-parts.follows = "flake-parts";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.nix-darwin.follows = "darwin";
};

3.1.1.8.11. simple-wol-manager#

simple-wol-manager = {
  url = "git+https://git.natsukium.com/natsukium/simple-wol-manager";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.12. spoor#

spoor = {
  url = "git+https://git.natsukium.com/natsukium/spoor";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.flake-parts.follows = "flake-parts";
};

3.1.1.8.13. vicinae#

vicinae = {
  url = "github:vicinaehq/vicinae";
  inputs.nixpkgs.follows = "nixpkgs";
};

3.1.1.8.14. zen-browser#

zen-browser = {
  url = "github:0xc000022070/zen-browser-flake";
  inputs.nixpkgs.follows = "nixpkgs";
  inputs.home-manager.follows = "home-manager";
};

3.1.2.1.1. cache.nixos-cuda.org#

3.1.2.1.2. natsukium.cachix.org#

3.1.3.5.1. セットアップ#

1. WSLのインストール
   

   --no-distribution を指定すると、デフォルトのUbuntuディストリビューションのインストールを回避できます。NixOSをインポートした後に削除することになるためです。

   powershell

   wsl --install --no-distribution
   

2. NixOS-WSLのインポート
   

   最新のNixOS-WSLリリースイメージをダウンロードしてインポートします。

   powershell

     | Select-Object -ExpandProperty assets ` |
     | Where-Object { $_.name -eq "nixos.wsl" } ` |
     | ForEach-Object { Invoke-WebRequest -Uri $_.browser_download_url -OutFile $_.name } |
   Invoke-RestMethod -Uri https://api.github.com/repos/nix-community/nixos-wsl/releases/latest `
   

   powershell

   ./nixos.wsl
   

3. 設定の適用
   

   NixOS-WSLの初回起動後、このflakeの設定をGitHubから直接適用します。初回実行時にローカルへのクローンは不要です。

   powershell

   wsl -d NixOS
   

   bash

   sudo nixos-rebuild switch --flake github:natsukium/dotfiles#arusha
   

4. Windows側のCLIツール
   

   Windows 24H2には sudo コマンドが組み込まれているため、別途UACプロンプトを表示せずに winget をインラインで昇格できます。

3.2.1.3.1. Python313パッケージセット#

python313 = prev.python313.override {
  packageOverrides = pyfinal: pyprev: {
    <<rapidocr-onnxruntime>>
    <<lxml-html-clean>>
  };
};

1. rapidocr-onnxruntime
   

   テストスイートの実行中にセグメンテーションフォールトが発生します。根本原因はまだ調査中です。

   このパッケージは推移的な依存関係として取り込まれています。実際の使用でランタイム機能が正しく動作することは確認済みのため、テストスイートの無効化は安全な回避策です。

   <<rapidocr-onnxruntime>>

   rapidocr-onnxruntime = pyprev.rapidocr-onnxruntime.overridePythonAttrs (_: {
     doCheck = false;
   });
   

2. lxml-html-clean
   

   libxml2 2.14の破壊的変更により、特定のDOM操作における空白文字やエンティティエンコーディングの処理方法が変更されたためテストが失敗します。実際のHTMLクリーニング機能は正しく動作しているにもかかわらず、テストのアサーションが失敗します。

   アップストリームでは fedora-python/lxml_html_clean#24で追跡されています。テストスイートがlibxml2 2.14互換に更新されたらこのオーバーライドを削除します。

   <<lxml-html-clean>>

   lxml-html-clean = pyprev.lxml-html-clean.overridePythonAttrs (_: {
     doCheck = false;
   });
   

3.2.1.3.2. Handy#

handy = prev.handy.overrideAttrs (oldAttrs: {
  patches = (oldAttrs.patches or [ ]) ++ [ ./handy-retry-without-reasoning.patch ];
});

3.2.1.5.1. gh-dash#

gh-dash =
  (final.writeShellApplication {
    name = "gh-dash";
    text = ''
      LANG=C.UTF-8 ${final.lib.getExe prev.gh-dash} "$@"
    '';
  }).overrideAttrs
    { pname = "gh-dash"; };

3.2.1.5.2. mkShim#

inherit (final.callPackage ../pkgs/mkShim { }) mkShim commandLineToolsShim;

3.3.2.1.1. オプション#

options.my.nix = {
  enable = lib.mkEnableOption "Nix configuration";

  enableFlakes = lib.mkOption {
    default = true;
    example = false;
    description = "Whether to enable flakes.";
    type = lib.types.bool;
  };
};

3.3.2.1.2. 設定#

config = lib.mkIf cfg.enable (
  lib.mkMerge [
    <<nix-flakes>>
    {
      <<nix-store-optimisation>>

      <<nix-warn-dirty>>

      <<nix-substituters>>

      <<nix-sandbox>>

      <<nix-trusted-users>>

      <<nix-gc>>

      <<nix-extra-options>>
    }
  ]
);

1. Flakes
   

   FlakeはNixプロジェクト管理のデファクトスタンダードであり、このリポジトリ全体で使用されています。

   チャンネルは無効化されています。チャンネルはマシン間で再現が困難な可変状態（=/nix/var/nix/profiles/per-user/*/channels=）を導入するためです。ただし、=nix-shell= などのレガシーコマンドは壊れません。NixOSとnix-darwinはデフォルトでflakeのinputから=NIX_PATH= を自動設定するため（nixpkgs.flake.setNixPath参照）、このdotfilesリポジトリで管理されるすべてのマシンで <nixpkgs> の参照が引き続き機能します。

   <<nix-flakes>>

   (lib.mkIf cfg.enableFlakes {
     nix = {
       settings.experimental-features = [
         "flakes"
         "nix-command"
       ];
       channel.enable = false;
     };
   })
   

2. ストアの最適化
   

   2つの補完的な重複排除メカニズムが有効化されています：

   • nix.optimise.automatic は定期的に nix-store --optimise を実行し、 ストア内の同一ファイルをハードリンクします。
   • nix.settings.auto-optimise-store は新しいパスが追加される際にビルド時に重複排除します。

   auto-optimise-store はLinux専用です。macOSで有効にするとストアが破損し、=error: cannot link 'nix/store.tmp-link' to 'nix/store.links/…': File exists= でビルドが失敗します。NixOS/nix#7273を参照してください。

   <<nix-store-optimisation>>

   nix.optimise.automatic = true;
   nix.settings.auto-optimise-store = pkgs.stdenv.hostPlatform.isLinux;
   

3. ガベージコレクション
   

   定期的に nix-collect-garbage を実行してディスク容量を回収します。7日以上前の世代は自動的に削除されます。それ以上古いビルドを保持しても価値は薄く、flakeのロックファイルからいつでも再ビルドできるためです。

   <<nix-gc>>

   nix.gc = {
     automatic = true;
     options = "--delete-older-than 7d";
   };
   

4. Dirty警告
   

   flake評価時の「Git tree is dirty」警告を抑制します。この警告はコミットされていない変更があるとビルドのたびに表示されますが、開発中はそれが通常の状態です。

   <<nix-warn-dirty>>

   nix.settings.warn-dirty = false;
   

5. バイナリキャッシュ
   

   I configure three binary caches. nix-cache.natsukium.com is my self-hosted niks3 cache (on manyara, backed by Cloudflare R2); CI pushes this dotfiles repository's pre-built artifacts to it. natsukium is my Cachix cache, which my other repositories still push to — only dotfiles has moved to niks3, so for now niks3 is dotfiles-only and Cachix covers everything else, though I may broaden niks3's scope later. nixos-cuda covers CUDA packages, which kilimanjaro needs because it builds with cudaSupport; without it, every bump to a package in that closure turns into a local rebuild. These builds came from nix-community until November 2025, when the CUDA team moved to its own Hydra.

   <<nix-substituters>>

   nix.settings = {
     substituters = [
       "https://nix-cache.natsukium.com"
       "https://natsukium.cachix.org"
       "https://cache.nixos-cuda.org"
     ];
   
     trusted-public-keys = [
       "niks3-1:SoIFTPtiPoCW3/OzUkIBKlLG5znMZfbihlr11XAOles="
       "natsukium.cachix.org-1:STD7ru7/5+KJX21m2yuDlgV6PnZP/v5VZWAJ8DZdMlI="
       "cache.nixos-cuda.org:74DUi4Ye579gUqzH4ziL9IyiJBlDpMRn9MBN8oNan9M="
     ];
   };
   

6. サンドボックス
   

   Darwinではサンドボックスを "relaxed" に設定し、予期しないビルド失敗を回避しています。=sandbox = true= では、サンドボックスの制約により一部のパッケージがmacOSでビルドに失敗します。テストスイートがローカルサーバーを起動する際のlocalhost通信に関連していると考えられますが、正確なメカニズムは完全には解明されていません。nixpkgsはサンドボックス内でlocalhostアクセスを許可する __darwinAllowLocalNetworking を提供しており、同じ種類の問題に対処できる可能性があります。="relaxed"= は通常のderivationをサンドボックス化したまま、=__noChroot = true= を持つderivationがサンドボックスを迂回できるようにし、これらの失敗を防ぎます。

   <<nix-sandbox>>

   nix.settings.sandbox = if pkgs.stdenv.hostPlatform.isDarwin then "relaxed" else true;
   

7. 信頼されたユーザー
   

   macOSでは、管理者ユーザーは wheel ではなく=admin= グループに属します（=wheel= には root のみが含まれます）。=@admin= がないと、DarwinでプライマリユーザーがNixデーモンから信頼されません。

   <<nix-trusted-users>>

   nix.settings.trusted-users = [
     "root"
     "@wheel"
   ]
   ++ lib.optional pkgs.stdenv.hostPlatform.isDarwin "@admin";
   

8. 追加オプション
   

   3600秒（1時間）出力がないビルドを終了します。一部の重いビルド（例: Chromium、カーネルのコンパイル、CUDAベースのディープラーニングライブラリ）は長時間無出力になることがあるため、本当にハングしたビルドを検出しつつ誤検知を避けるためにタイムアウトは余裕を持って設定されています。

   <<nix-extra-options>>

   nix.extraOptions = ''
     max-silent-time = 3600
   '';
   

3.3.2.3.1. Protocol#

3.3.2.3.2. オプション#

options.my.nix.distributedBuilds = {
  enable = lib.mkEnableOption "distributed builds";

  connectTimeout = lib.mkOption {
    type = lib.types.ints.positive;
    default = 5;
    description = "SSH ConnectTimeout in seconds for reaching build machines.";
  };

  machines = lib.mkOption {
    type = lib.types.attrsOf (
      lib.types.submodule {
        options = {
          publicKey = lib.mkOption { type = lib.types.str; };
          systems = lib.mkOption { type = lib.types.listOf lib.types.str; };
          maxJobs = lib.mkOption { type = lib.types.ints.positive; };
          supportedFeatures = lib.mkOption {
            type = lib.types.listOf lib.types.str;
            default = [ ];
          };
          excludeHosts = lib.mkOption {
            type = lib.types.listOf lib.types.str;
            default = [ ];
          };
        };
      }
    );
    description = "Build machines the fleet can offload to.";
    default = {
      tarangire = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEJJYgE/dmYLXYBrVnPicd0qsaUeqcBtXB8H9LHkJ2j4";
        systems = [
          "x86_64-linux"
          "i686-linux"
        ];
        maxJobs = tarangire.config.nix.settings.max-jobs;
        supportedFeatures = tarangire.config.nix.settings.system-features;
      };
      kilimanjaro = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILhpfAalh6A5xDSE+HOdNE29ZgIjlP7tdlhHs82boSwp";
        systems = [
          "x86_64-linux"
          "i686-linux"
        ];
        maxJobs = kilimanjaro.config.nix.settings.max-jobs;
        supportedFeatures = kilimanjaro.config.nix.settings.system-features;
      };
      serengeti = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDWwhfhDSZ+M2XDwP2MlC/zFfVpk3WjUxV/JWFgGzgNW";
        systems = [ "aarch64-linux" ];
        maxJobs = serengeti.config.nix.settings.max-jobs;
        supportedFeatures = serengeti.config.nix.settings.system-features;
      };
      mikumi = {
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPfWOWKBFuDV08g6xP9MMY78CERI02CNG+5dy8CXQmXs";
        systems = [
          "aarch64-darwin"
          "x86_64-darwin"
        ];
        maxJobs = mikumi.config.nix.settings.max-jobs;
        supportedFeatures = [
          "apple-virt"
          "benchmark"
          "big-parallel"
          "nixos-test"
        ];
        excludeHosts = [ "work" ];
      };
    };
  };
};

3.3.2.3.3. 設定#

config = lib.mkIf cfg.enable {
  nix = {
    distributedBuilds = true;

    extraOptions = ''
      builders-use-substitutes = true
    '';

    buildMachines = lib.pipe cfg.machines [
      (lib.filterAttrs (
        name: machine:
        name != config.networking.hostName && !(lib.elem config.networking.hostName machine.excludeHosts)
      ))
      (lib.mapAttrsToList (
        hostName: machine: {
          inherit hostName protocol;
          inherit (machine) systems maxJobs supportedFeatures;
          sshUser = "natsukium";
          speedFactor = 1;
          mandatoryFeatures = [ ];
        }
      ))
    ];
  };

  programs.ssh.knownHosts = lib.mapAttrs (_: machine: { inherit (machine) publicKey; }) cfg.machines;

  programs.ssh.extraConfig = ''
    Host ${lib.concatStringsSep " " (lib.attrNames cfg.machines)}
      ConnectTimeout ${toString cfg.connectTimeout}
  '';
};

3.3.3.1.1. オプション#

options.my.services.tailscale = {
  enable = lib.mkEnableOption "Tailscale VPN";

  <<configureResolver-option>>
};

1. configureResolver
   

   デスクトップシステムではサスペンド/レジューム後にDNS解決の失敗が発生することがあります。システムがレジュームすると、外部ドメインの解決（例: github.com）が失敗する一方、Tailnetのホスト名は引き続き動作します。これはネットワーク遷移時のTailscaleのDNS状態管理に関する既知の問題です。

   configureResolver を有効にするとsystemd-resolvedがアクティベートされ、サスペンド/レジューム後のDNS解決の問題が軽減されます。これで問題が完全に解消されるわけではありませんが（アップストリームのバグは未解決）、最も信頼性の高いMagicDNS体験を提供します。

   ヘッドレスサーバーでは、このオプションは通常不要です。サーバーはサスペンドしないため、レジュームに関連するこのDNSバグに遭遇することがないためです。

   アップストリームの議論は tailscale/tailscale#4254を参照してください。

   <<configureResolver-option>>

   configureResolver = lib.mkOption {
     type = lib.types.bool;
     default = false;
     description = ''
       Enable systemd-resolved for Tailscale DNS.
       Recommended for desktop systems to mitigate DNS failures after suspend/resume.
       https://github.com/tailscale/tailscale/issues/4254
     '';
   };
   

3.3.3.1.2. 設定#

config = lib.mkIf cfg.enable (
  lib.mkMerge [
    {
      <<tailscale-service>>

      <<tailscale-networking>>

      <<tailscale-secrets>>
    }
    <<tailscale-resolver>>
  ]
);

1. サービス設定
   

   Tailscaleサービスのコア設定

   useRoutingFeatures = "server" はこのマシンをサブネットルーターまたはイグジットノードとして機能させます。この設定のすべてのマシンは他のデバイスのイグジットノードとして機能でき、旅行中や制限されたネットワーク上での柔軟性を提供します。

   authKeyFile はTailscale認証キーを含むSOPS管理のシークレットを指します。認証キーを使用することで無人認証が可能になり、cominなどのツールを使った自動デプロイやGitOpsワークフローに不可欠です。

   --ssh はTailscale SSHを有効にし、SSHキーの管理やポート22のパブリックインターネットへの公開なしにTailscaleネットワーク経由でSSHアクセスを可能にします。

   <<tailscale-service>>

   services.tailscale = {
     enable = true;
     useRoutingFeatures = "server";
     authKeyFile = config.sops.secrets.tailscale-authkey.path;
     extraUpFlags = [ "--ssh" ];
   };
   

2. ネットワーク
   

   Tailscale統合のためのファイアウォールとDNS設定です。

   tailscale0 インターフェースは信頼されています。このインターフェース上のすべてのトラフィックはTailscaleによって認証されるためです。これにより、追加のファイアウォールルールなしにサービスをtailnetのみに公開できます。

   100.100.100.100 はTailscaleのMagicDNSリゾルバーで、tailnetホスト名（例: hostname.tail4108.ts.net=）の解決を可能にします。=8.8.8.8 はtailnet以外のクエリのフォールバックを提供しますが、実際にはMagicDNSがアップストリームリゾルバーへの転送を処理します。

   検索ドメインはtailnetドメインに設定されており、短いホスト名（例: ssh manyara.tail4108.ts.net の代わりに =ssh manyara=）が使えます。

   <<tailscale-networking>>

   networking = {
     firewall = {
       trustedInterfaces = [ "tailscale0" ];
       allowedUDPPorts = [ config.services.tailscale.port ];
     };
     nameservers = [
       "100.100.100.100"
       "8.8.8.8"
     ];
     search = [ "tail4108.ts.net" ];
   };
   

3. シークレット
   

   Tailscale認証キーのSOPSシークレット宣言です。実際のキーはリポジトリのシークレットファイルに暗号化されて保存され、アクティベーション時に復号されます。

   <<tailscale-secrets>>

   sops.secrets.tailscale-authkey = { };
   

4. リゾルバー
   

   条件付きのsystemd-resolved設定です。=configureResolver= がtrueの場合にのみ有効になり、通常はサスペンド/レジュームするデスクトップシステムで使用されます。

   <<tailscale-resolver>>

   (lib.mkIf cfg.configureResolver {
     services.resolved.enable = cfg.configureResolver;
   })
   

3.3.5.1.1. 対話シェルの初期化#

interactiveShellInit = ''
  <<fish-keybindings>>

  <<fish-done-config>>

  <<fish-pinentry>>

  <<fish-extra-abbrs>>
'';

1. キーバインド
   

   Ctrl+S に =zi=（zoxideのインタラクティブモード）をバインドし、ファジーなディレクトリジャンプに使用します。

   <<fish-keybindings>>

   bind \cs zi
   

2. Pinentry
   

   SSH経由で接続している場合、GPGのpinentryをcurses（ターミナル）バリアントに切り替えます。デフォルトのグラフィカルなpinentryはX11/Waylandフォワーディングなしではリモートセッションで表示できないため、SSH経由でのコミット署名やシークレット復号にTUIのフォールバックが必要です。Gentoo Wiki: GnuPG - Changing pinentry for SSH loginsを参照してください。

   <<fish-pinentry>>

   # set environment variable for pinentry
   if test "$SSH_CONNECTION" != ""
     set -x PINENTRY_USER_DATA "USE_CURSES"
   end
   

3. 追加の略語
   

   位置認識型の略語で、fishの高度な機能（=–position anywhere=、=–regex=、=–function=）を使用しています。これらはhome-managerの shellAbbrs オプションでは利用できません。

   <<fish-extra-abbrs>>

   # extra abbrs
   abbr -a L --position anywhere --set-cursor "% | less"
   abbr -a !! --position anywhere --function _abbr_last_history_item
   abbr -a extract_tar_gz --position command --regex ".+\.tar\.gz" --function _abbr_extract_tar_gz
   abbr -a dotdot --regex '^\.\.+$' --function _abbr_multicd
   

3.3.5.1.2. 略語#

shellAbbrs = {
  <<fish-abbr-general>>

  <<fish-abbr-nix>>
};

1. 一般
   
   <<fish-abbr-general>>

   # spellchecker:off
   l = "ls";
   

2. Nixリモートビルド
   

   Nixのビルドターゲットシステムを指定する略語で、主にnixpkgsで作業する際に使用されます。各略語は --system <triple> に展開され、ターゲットシステムが現在のホストと異なる場合は条件付きで -j0 が追加されます。=-j0= はローカルジョブ数の上限をゼロに設定し、すべてのビルドをリモートビルダーに委任させます（分散ビルド参照）。これにより、Nixがホスト上でビルドを試みてアーキテクチャの不一致で失敗することを防ぎます。

   <<fish-abbr-nix>>

   # spellchecker:on
   "--sxl" = {
     position = "anywhere";
     expansion =
       "--system x86_64-linux"
       + pkgs.lib.optionalString (
         pkgs.stdenv.hostPlatform.isDarwin || pkgs.stdenv.hostPlatform.isAarch64
       ) " -j0";
   };
   "--sal" = {
     position = "anywhere";
     expansion =
       "--system aarch64-linux"
       + pkgs.lib.optionalString (
         pkgs.stdenv.hostPlatform.isDarwin || pkgs.stdenv.hostPlatform.isx86_64
       ) " -j0";
   };
   "--sxd" = {
     position = "anywhere";
     expansion =
       "--system x86_64-darwin" + pkgs.lib.optionalString pkgs.stdenv.hostPlatform.isLinux " -j0";
   };
   "--sad" = {
     position = "anywhere";
     expansion =
       "--system aarch64-darwin" + pkgs.lib.optionalString pkgs.stdenv.hostPlatform.isLinux " -j0";
   };
   

3.3.5.1.3. 関数#

functions = {
  _abbr_last_history_item = "echo $history[1]";
  _abbr_extract_tar_gz = "echo tar avfx $argv";
  _abbr_multicd = "echo cd (string repeat -n (math (string length -- $argv[1]) - 1) ../)";
};

1. any-nix-shell
   

   any-nix-shell keeps fish as the interactive shell inside nix shell and nix develop environments; without it, entering a Nix shell drops into bash and loses fish's interactive features.

   any-nix-shell fish only emits two function definitions (nix and nix-shell), but generating them shells out to /bin/sh plus three which lookups — ~24ms on every interactive startup if sourced eagerly. Running it once at build time and splitting the output into fish's autoload directory moves that cost off the hot path (fish parses each function on first call), and uses any-nix-shell's real wrappers rather than a hardcoded copy, so its nix run version gate and --pure handling stay in sync with the upstream package.

   <<fish-any-nix-shell>>

   # Generate any-nix-shell's fish wrappers at build time. Each call extracts one
   # function definition into its own file for fish's autoload directory, so the
   # wrappers stay in sync with the package rather than being hardcoded.
   anyNixShellFunction =
     name:
     pkgs.runCommand "any-nix-shell-${name}.fish" { nativeBuildInputs = [ pkgs.any-nix-shell ]; } ''
       any-nix-shell fish | awk -v want=${name} '
         $1 == "function" { current = $2; depth = 0 }
         current == want {
           print
           if ($1 ~ /^(function|begin|if|for|while|switch)$/) depth++
           else if ($1 == "end" && --depth == 0) current = ""
         }
       ' > $out
     '';
   

3.3.5.1.4. プラグイン#

plugins = [
  {
    name = "done";
    src = pkgs.fishPlugins.done.src;
  }
  {
    name = "fzf-fish";
    src = pkgs.fishPlugins.fzf-fish.src;
  }
];

# set done's variable
set -U __done_min_cmd_duration 15000

3.3.5.2.1. 履歴#

historyFile = "$XDG_CONFIG_HOME/bash/history";

3.3.5.2.2. 補完#

enableCompletion = false;

3.3.5.2.3. エイリアス#

shellAliases = {
  l = "ls -CF";
  grep = "grep --color=auto";
  fgrep = "fgrep --color=auto";
  egrep = "egrep --color=auto";
};

3.3.5.2.4. 初期化#

+ lib.optionalString (!config.programs.kitty.enable) ''
  <<bash-tmux-autostart>>
initExtra = ''
  <<bash-terminal-settings>>
''
'';

1. ターミナル設定
   

   stty stop undef disables Ctrl+S from sending XOFF, freeing it for use as a keybinding in fish and other TUI applications. Without it, Ctrl+S freezes the terminal until Ctrl+Q is pressed.

   <<bash-terminal-settings>>

   stty stop undef  # Ctrl-s
   

2. TMUXの自動アタッチ
   

   bashが対話的シェルの場合にtmuxセッションを自動的に開始またはアタッチしますが、kittyがターミナルエミュレーターの場合のみ除外されます。kittyには独自のタブ/ウィンドウ管理（分割、レイアウト、タブ）があり、tmuxの多重化と競合します。kitty内でtmuxを実行すると冗長なネストが生じます。よりシンプルなターミナル（例: =xterm=、=alacritty=、またはLinuxコンソール）を使用する場合、tmuxはそれ以外では欠けるセッション永続性とウィンドウ管理を提供します。

   <<bash-tmux-autostart>>

   # TMUX (from ArchWiki)
     # if no session is started, start a new session
   if type tmux > /dev/null 2>&1; then
     test -z $TMUX && tmux
   
     # when quitting tmux, try to attach
     while test -z $TMUX; do
       tmux attach || break
     done
   fi
   

3.3.5.4.1. External Completer#

options.ext.programs.nushell.externalCompleter = {
  enable = lib.mkOption {
    type = lib.types.bool;
    default = config.programs.nushell.enable;
  };
  enableFishCompleter = lib.mkOption {
    type = lib.types.bool;
    default = true;
  };
};

        | $"value(char tab)description(char newline)" + $in |
        | from tsv --flexible --no-infer |
(lib.mkIf completerCfg.enable {
  programs.nushell.extraConfig = lib.mkIf completerCfg.enableFishCompleter ''
    let fish_completer = {|spans|
        ${lib.getExe pkgs.fish} --command $'complete "--do-complete=($spans | str join " ")"'
    }

        | default {} |
        | insert enable { true } |
        | insert completer { $fish_completer } |
    $env.config = ($env.config? | default {})
    $env.config.completions = ($env.config.completions? | default {})
    $env.config.completions.external = (
        $env.config.completions.external?
    )
  '';
})

3.3.5.5.1. プロンプトフォーマット#

"$schema" = "https://starship.rs/config-schema.json"

format = "$shell$all$line_break$character"

3.3.5.5.2. シェルインジケーター#

[shell]
fish_indicator = "󰈺"
powershell_indicator = "󰨊"
disabled = false

3.3.5.5.3. リモートコンテナの検出#

[custom.remote-container]
when = """ test "$REMOTE_CONTAINERS" """
symbol = "🐋"
format = " in $symbol "

3.3.5.5.4. 無効化されたモジュール#

[gcloud]
disabled = true

3.3.5.5.5. 非同期プロンプトモジュール#

  # use my own script to ensure the execution order
(lib.mkIf cfg.enableFishAsyncPrompt {
  programs.starship.enableFishIntegration = lib.mkForce false;

  programs.fish.interactiveShellInit = ''
    if test "$TERM" != dumb
        ${lib.getExe config.programs.starship.package} init fish | source
        source ${./async_prompt.fish}
    end
  '';
})

1. 非同期プロンプトスクリプト
   
   modules/features/starship/async_prompt.fish

   # cherry picked from https://gist.github.com/duament/bac0181935953b97ca71640727c9c029
   status is-interactive
   or exit 0
   
   if test -n "$XDG_RUNTIME_DIR"
       set -g __starship_async_tmpdir "$XDG_RUNTIME_DIR"/fish-async-prompt
   else
       set -g __starship_async_tmpdir /tmp/fish-async-prompt
   end
   mkdir -p "$__starship_async_tmpdir"
   set -g __starship_async_signal SIGUSR1
   
   # Starship
   set -g VIRTUAL_ENV_DISABLE_PROMPT 1
   builtin functions -e fish_mode_prompt
   set -gx STARSHIP_SHELL fish
   set -gx STARSHIP_SESSION_KEY (random 10000000000000 9999999999999999)
   
   # Prompt
   function fish_prompt
       printf '\e[0J' # Clear from cursor to end of screen
       if test -e "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
           cat "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
       else
           __starship_async_simple_prompt
       end
   end
   
   # Async task
   function __starship_async_fire --on-event fish_prompt
       switch "$fish_key_bindings"
           case fish_hybrid_key_bindings fish_vi_key_bindings
               set STARSHIP_KEYMAP "$fish_bind_mode"
           case '*'
               set STARSHIP_KEYMAP insert
       end
       set STARSHIP_CMD_PIPESTATUS $pipestatus
       set STARSHIP_CMD_STATUS $status
       set STARSHIP_DURATION "$CMD_DURATION"
       set STARSHIP_JOBS (count (jobs -p))
   
       set -l tmpfile "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
       fish -c '
   starship prompt --terminal-width="'$COLUMNS'" --status='$STARSHIP_CMD_STATUS' --pipestatus="'$STARSHIP_CMD_PIPESTATUS'" --keymap='$STARSHIP_KEYMAP' --cmd-duration='$STARSHIP_DURATION' --jobs='$STARSHIP_JOBS' > '$tmpfile'
   kill -s "'$__starship_async_signal'" '$fish_pid &
       disown
   end
   
   function __starship_async_simple_prompt
       set_color brgreen
       echo -n '❯'
       set_color normal
       echo ' '
   end
   
   function __starship_async_repaint_prompt --on-signal "$__starship_async_signal"
       commandline -f repaint
   end
   
   function __starship_async_cleanup --on-event fish_exit
       rm -f "$__starship_async_tmpdir"/"$fish_pid"_fish_prompt
   end
   
   # https://github.com/acomagu/fish-async-prompt
   # https://github.com/fish-shell/fish-shell/issues/8223
   

3.3.6.1.1. コア設定#

settings = {
  <<git-user-identity>>
  <<git-github-user>>
  <<git-editor>>
  <<git-color>>
  <<git-default-branch>>
  <<git-push-safety>>
};

1. User Identity
   
   <<git-user-identity>>

   user = {
     name = "natsukium";
     email = "[email protected]";
   };
   

2. GitHub Identity
   

   I read GitHub issues and notifications in Emacs through forge, whose API layer ghub takes the account name from github.user to find the matching ~/.authinfo.age entry. Without it a pull aborts with "Cannot determine username" before any request goes out, and the notification list keeps showing whatever the last successful fetch stored. The token that goes with it is described in the forge section below.

   <<git-github-user>>

   github.user = "natsukium";
   

3. エディター
   

   core.editor = "vim" はgit操作のフォールバックエディターとして設定されています。=EDITOR= 環境変数はホーム設定で nvim に設定されていますが、一部のコンテキスト（最小限の環境での=git commit= など）ではセッションの環境変数を引き継がない場合があります。gitconfigで明示的に設定することで一貫した動作を保証します。

   <<git-editor>>

   core.editor = "vim";
   

4. カラー
   

   すべてのgitサブコマンドでターミナルのカラーサポートを自動検出します。

   <<git-color>>

   color = {
     status = "auto";
     diff = "auto";
     branch = "auto";
     interactive = "auto";
     grep = "auto";
   };
   

5. デフォルトブランチ
   
   <<git-default-branch>>

   init.defaultBranch = "main";
   

6. 強制プッシュの安全対策
   

   push.useForceIfIncludes は強制プッシュの安全チェックを有効にします。gitはローカルブランチがリモートの現在のtipを含んでいるか確認してから強制プッシュを許可します。これにより、最後のfetch以降に他の人がプッシュしたコミットを誤って上書きすることを防ぎます。=–force-with-lease= だけでは、リモートrefがバックグラウンドで更新された場合（例: lazygitの定期的なfetchやバックグラウンドの=git fetch=）に検出できません。

   <<git-push-safety>>

   push.useForceIfIncludes = true;
   

3.3.6.1.2. コミット署名#

signing = {
  format = "ssh";
  key = "~/.ssh/id_ed25519.pub";
  signByDefault = true;
};

3.3.6.1.3. グローバルIgnore#

ignores = [
  <<git-ignores-os>>
  <<git-ignores-dev>>
  <<git-ignores-workflow>>
  <<git-ignores-private>>
];

1. OSアーティファクト
   

   macOS Finderのメタデータファイルです。LinuxとmacOSの両方で使用されるクロスプラットフォームなdotfilesリポジトリのため、グローバルignoreに含めています。

   <<git-ignores-os>>

   ".DS_Store"
   

2. 開発環境
   

   ローカルに留めるべき開発ツールが生成するアーティファクトです：

   • .aider* はaiderの会話履歴と設定ファイルにマッチします。 セッション固有のコンテキストを含むため、リポジトリに漏れるべきではありません。
   • .direnv=、.envrc=: direnvの状態と設定。各プロジェクトが独自の .envrc を定義できますが、このリポジトリではflakeベースのdevshellを使用するため、 .envrc ファイルは自動生成されコミットすべきではありません。
   • .ipynb_checkpoints: Jupyter Notebookの自動保存ファイル。
   • .pre-commit-config.yaml: コミットではなくdevshell環境でプロジェクトごとに管理し、 ツールバージョンの異なるコントリビューター間のバージョン競合を避けます。
   • .vscode/: 開発者ごとに異なるエディター固有の設定。
   • __pycache__/: Pythonバイトコードキャッシュ。実行ごとに再生成されます。

   <<git-ignores-dev>>

   ".aider*"
   ".direnv"
   ".envrc"
   ".ipynb_checkpoints"
   ".pre-commit-config.yaml"
   ".vscode/"
   "__pycache__/"
   

3. ワークフロー
   
   • .worktree: git worktreeワークフローで使用されるマーカーファイル。

   <<git-ignores-workflow>>

   ".worktree"
   

4. プライベートノート
   

   .private/ は個人的なメモ、LLMコンテキストファイル、その他の共有すべきでないローカル専用のドキュメントのためのディレクトリです。

   <<git-ignores-private>>

   ".private/"
   

3.3.6.1.4. Scalar#

options.programs.git.scalar = {
  enable = lib.mkEnableOption "scalar";

  repo = lib.mkOption {
    type = lib.types.listOf lib.types.str;
    default = [ ];
    example = [ "${config.home.homeDirectory}/NixOS/nixpkgs" ];
  };
};

scalar = {
  enable = true;
  repo = [ "${config.programs.git.settings.ghq.root}/github.com/natsukium/nixpkgs" ];
};

(lib.mkIf scalarCfg.enable {
  programs.git = {
    settings = {
      scalar.repo = scalarCfg.repo;
      maintenance.repo = scalarCfg.repo;
    };
    includes = map (repo: {
      condition = "gitdir:${repo}/";
      contents = {
        core = {
          multipackindex = true;
          preloadindex = true;
          untrackedcache = true;
          autocrlf = false;
          safecrlf = false;
          fsmonitor = true;
        };
        am.keepcr = true;
        credential = {
          "https://dev.azure.com".usehttppath = true;
          validate = false;
        };
        gc.auto = 0;
        gui.gcwarning = false;
        index = {
          threads = true;
          version = 4;
        };
        merge = {
          stat = false;
          renames = true;
        };
        pack = {
          usebitmaps = false;
          usesparse = true;
        };
        receive.autogc = false;
        feature = {
          manyfiles = false;
          experimental = false;
        };
        fetch = {
          unpacklimit = 1;
          writecommitgraph = false;
          showforcedupdates = false;
        };
        status.aheadbehind = false;
        commitgraph.generationversion = 1;
        log.excludedecoration = "refs/prefetch/*";
        maintenance = {
          auto = false;
          strategy = "incremental";
        };
      };
    }) scalarCfg.repo;
  };
})

3.3.6.1.5. GitHub CLI#

programs.gh.enable = true;

3.3.6.1.6. Delta#

programs.delta = {
  enable = true;
  enableGitIntegration = true;
};

3.3.6.1.7. Difftastic#

programs.difftastic = {
  enable = true;
};

3.3.6.1.8. Lazygit#

programs.lazygit = {
  enable = true;
  settings = {
    <<lazygit-gui>>

    <<lazygit-git>>
  };
};

1. GUI
   

   視認性向上のため、lazygitのインターフェースでNerd Fontアイコンを有効にします。

   <<lazygit-gui>>

   gui = {
     showIcons = true;
   };
   

2. Git連携
   

   overrideGpg = true は、lazygitにGPG/SSH署名用のサブプロセスを生成する代わりにGitコマンドをインラインで実行するよう指示します。デフォルトでは、lazygitはユーザーが対話的にパスフレーズを入力できるようサブプロセスに委譲します。しかし、このサブプロセスモードではlazygitが内部でインタラクティブリベースを制御できなくなります。リベース中に複数の署名プロンプトが発生し、lazygitがそれを処理できないため、HEAD以外のコミットのリワード、並べ替え、編集が完全に無効化されます。=overrideGpg = true= を設定すると、lazygitは署名エージェント（ssh-agent、macOS Keychain）がパスフレーズをキャッシュしていると想定するため、対話的プロンプトが不要になり、すべてのリベース操作が正常に動作します。

   ページャー設定により、deltaとdifftasticの両方がlazygitの差分ビューに統合されます。Deltaはシンタックスハイライト付きの行差分を提供し（lazygitが独自にページングを行うため --dark --paging=never を指定）、difftasticは構造的比較のための外部diffコマンドとして利用できます。

   <<lazygit-git>>

   git = {
     overrideGpg = true;
     pagers = [
       {
         colorArg = "always";
         pager = "delta --dark --paging=never";
       }
       {
         externalDiffCommand = "difft --color=always";
       }
     ];
   };
   

3.3.6.1.9. Fishの略語#

programs.fish.shellAbbrs = {
  <<git-abbr-push>>
  <<git-abbr-pull>>
  <<git-abbr-commit>>
  <<git-abbr-status>>
  <<git-abbr-stash>>
  <<git-abbr-switch>>
};

1. Push
   

   lease付きの強制プッシュです。まだfetchされていないリモートの変更の上書きを防ぐため、=–force= よりも安全です。

   <<git-abbr-push>>

   gpf = "git push --force-with-lease";
   

2. Pull
   

   gpm はリモートのデフォルトブランチからpullします。=main= や master をハードコードするのではなく、=git remote show= で動的に検出します。これにより=master= や他のブランチ命名規約を使用するリポジトリにも対応できます。

   gpu はupstreamからpullします。フォークワークフローでオリジナルのリポジトリと同期するために使用されます。

   <<git-abbr-pull>>

   gpm = "git pull (git remote show origin | sed -n '/HEAD branch/s/.*: //p')";
   gpu = "git pull upstream";
   

3. Commit
   

   gci はコミットを作成します。末尾のスペースにより -m "message" を直接追加できます。

   gca は直前のコミットを修正します。インタラクティブrebaseのワークフローで頻繁に使用されます。

   <<git-abbr-commit>>

   gci = "git commit ";
   gca = "git commit --amend";
   

4. Status
   
   <<git-abbr-status>>

   gs = "git status";
   

5. Stash
   
   <<git-abbr-stash>>

   gst = "git stash";
   gstp = "git stash pop";
   

6. Switch
   
   <<git-abbr-switch>>

   gsw = "git switch";
   gswc = "git switch -c";
   

3.3.7.1.1. nix-darwin module#

{
  config,
  lib,
  pkgs,
  ...
}:
let
  cfg = config.services.forgejo-runner;
  settingsFormat = pkgs.formats.yaml { };

  <<forgejo-runner-instance-submodule>>

  enabledInstances = lib.filterAttrs (_: i: i.enable) cfg.instances;
in
{
  <<forgejo-runner-darwin-options>>

  <<forgejo-runner-darwin-config>>
}

1. Instance options
   

   An instance carries its registration details and the tools its jobs need on PATH. Exactly one of token or tokenFile supplies the token, matching the NixOS module. Host-executed jobs inherit only the daemon's environment, so every tool a workflow expects must be listed in hostPackages.

   <<forgejo-runner-instance-submodule>>

   instanceModule =
     { name, ... }:
     {
       options = {
         enable = lib.mkEnableOption "this runner instance";
   
         name = lib.mkOption {
           type = lib.types.str;
           default = name;
           defaultText = lib.literalExpression "the attribute name";
           description = "Name the runner registers under.";
         };
   
         url = lib.mkOption {
           type = lib.types.str;
           example = "https://git.example.com";
           description = "Address of the Forgejo instance the runner registers with.";
         };
   
         token = lib.mkOption {
           type = lib.types.nullOr lib.types.str;
           default = null;
           description = ''
             Registration token as a plaintext string. Mutually exclusive with
             {option}`tokenFile`. Prefer {option}`tokenFile`: a token set here ends
             up in the world-readable launchd plist and the Nix store.
           '';
         };
   
         tokenFile = lib.mkOption {
           type = lib.types.nullOr (lib.types.either lib.types.str lib.types.path);
           default = null;
           description = ''
             Path to an environment file holding the registration token as
             `TOKEN=...`. Mutually exclusive with {option}`token`. The token is read
             on first registration and whenever it or {option}`labels` change;
             otherwise the persisted {file}`.runner` credential in {option}`stateDir`
             is used.
           '';
         };
   
         labels = lib.mkOption {
           type = lib.types.listOf lib.types.str;
           example = [ "macos:host" ];
           description = "Labels the runner advertises.";
         };
   
         settings = lib.mkOption {
           type = settingsFormat.type;
           default = { };
           description = ''
             Runner configuration written to {file}`config.yaml` and passed to the
             daemon with `--config`.
           '';
         };
   
         hostPackages = lib.mkOption {
           type = lib.types.listOf lib.types.package;
           default = with pkgs; [
             bash
             coreutils
             curl
             gawk
             gitMinimal
             gnused
             nodejs
             wget
           ];
           defaultText = lib.literalExpression ''
             with pkgs; [ bash coreutils curl gawk gitMinimal gnused nodejs wget ]
           '';
           description = ''
             Packages put on PATH for host-executed jobs. Host jobs inherit only
             the daemon's PATH, so every tool a workflow expects must be listed.
           '';
         };
   
         stateDir = lib.mkOption {
           type = lib.types.str;
           default = "/var/lib/forgejo-runner/${name}";
           defaultText = lib.literalExpression ''"/var/lib/forgejo-runner/<name>"'';
           description = "Directory holding the runner credential and working files.";
         };
       };
     };
   

2. Module options
   

   The daemons run as a dedicated unprivileged user, not root: a root daemon is a trusted-user client of the nix daemon, whose post-build-hook push path the multi-user daemon ignores — so nothing reaches my binary cache. An untrusted user takes the store-scan push path that actually uploads. I may revisit making it a trusted user once the post-build-hook path works for me.

   <<forgejo-runner-darwin-options>>

   options.services.forgejo-runner = {
     package = lib.mkPackageOption pkgs "forgejo-runner" { };
   
     user = lib.mkOption {
       type = lib.types.str;
       default = "_forgejo-runner";
       description = "Dedicated unprivileged user the runner daemons execute as.";
     };
   
     group = lib.mkOption {
       type = lib.types.str;
       default = "_forgejo-runner";
       description = "Primary group for the runner user.";
     };
   
     uid = lib.mkOption {
       type = lib.types.int;
       default = 530;
       description = "UID for the runner user (free system-range id on the host).";
     };
   
     gid = lib.mkOption {
       type = lib.types.int;
       default = 530;
       description = "GID for the runner group.";
     };
   
     instances = lib.mkOption {
       type = lib.types.attrsOf (lib.types.submodule instanceModule);
       default = { };
       description = "Runner instances; each enabled one becomes a launchd daemon.";
     };
   };
   

3. 設定
   
   <<forgejo-runner-darwin-config>>

   config = lib.mkIf (enabledInstances != { }) {
     assertions = lib.mapAttrsToList (_: instance: {
       assertion = (instance.token == null) != (instance.tokenFile == null);
       message = "services.forgejo-runner.instances.${instance.name}: set exactly one of token or tokenFile.";
     }) enabledInstances;
   
     <<forgejo-runner-daemons>>
   
     <<forgejo-runner-user>>
   
     <<forgejo-runner-ownership>>
   };
   

   1. Launchd daemons
      

      One launchd job per enabled instance. launchd has no EnvironmentFile, so a tokenFile instance sources it in-script while an inline token rides on EnvironmentVariables; either way the script sees $TOKEN. I prepend coreutils to PATH so the script's own sha256sum=/=cut resolve even if a host trims hostPackages. Two launchd quirks shape each:

      • WorkingDirectory cannot be the state directory: launchd chdir()s into it before exec, so on first boot the spawn aborts with EX_CONFIG (78) before the script can create it. The script sets its own cwd instead.
      • The logs live in the user-owned state directory, not /var/log: launchd opens them as UserName, and an unprivileged daemon cannot create a root-owned file under /var/log, so it would fail to spawn — silently, before any log line.

      <<forgejo-runner-daemons>>

      launchd.daemons = lib.mapAttrs' (
        _: instance:
        let
          configFile = settingsFormat.generate "config.yaml" instance.settings;
        in
        lib.nameValuePair "forgejo-runner-${instance.name}" {
          script = ''
            set -eu
            mkdir -p ${lib.escapeShellArg instance.stateDir}
            cd ${lib.escapeShellArg instance.stateDir}
            ${lib.optionalString (instance.tokenFile != null) ''
              set -a
              . ${lib.escapeShellArg (toString instance.tokenFile)}
              set +a
            ''}
            labels=${lib.escapeShellArg (lib.concatStringsSep "," instance.labels)}
            state="$(printf '%s' "$TOKEN" | sha256sum | cut -d' ' -f1) $labels"
      
            if [ ! -f .runner ] || [ "$(cat .registration-state 2>/dev/null)" != "$state" ]; then
              rm -f .runner
              ${lib.getExe cfg.package} register \
                --no-interactive \
                --instance ${lib.escapeShellArg instance.url} \
                --token "$TOKEN" \
                --name ${lib.escapeShellArg instance.name} \
                --labels "$labels" \
                --config ${configFile}
              printf '%s' "$state" > .registration-state
            fi
      
            exec ${lib.getExe cfg.package} daemon --config ${configFile}
          '';
          serviceConfig = {
            UserName = cfg.user;
            GroupName = cfg.group;
            KeepAlive = true;
            RunAtLoad = true;
            ProcessType = "Background";
            EnvironmentVariables = {
              HOME = instance.stateDir;
              PATH = "${
                lib.makeBinPath ([ pkgs.coreutils ] ++ instance.hostPackages)
              }:/usr/bin:/bin:/usr/sbin:/sbin";
            }
            // lib.optionalAttrs (instance.token != null) { TOKEN = instance.token; };
            StandardOutPath = "${instance.stateDir}/forgejo-runner.log";
            StandardErrorPath = "${instance.stateDir}/forgejo-runner.err.log";
          };
        }
      ) enabledInstances;
      

   2. Runner user
      

      nix-darwin only manages accounts listed in users.knownUsers / users.knownGroups, so I add the entries.

      I leave createHome off: it runs createhomedir, which resolves the /var firmlink and records the home as /private/var/…, then nix-darwin string-compares that against the configured home and aborts activation on the mismatch. The daemon uses its state directory as HOME anyway, created and owned below.

      <<forgejo-runner-user>>

      users.users.${cfg.user} = {
        uid = cfg.uid;
        gid = cfg.gid;
        isHidden = true;
        description = "Forgejo Actions runner";
      };
      users.groups.${cfg.group}.gid = cfg.gid;
      users.knownUsers = [ cfg.user ];
      users.knownGroups = [ cfg.group ];
      

   3. State ownership
      

      Each state directory must exist and belong to the runner user before its daemon starts. With createHome off nothing else creates it, so activation makes and chowns it mkBefore the launchd step that loads the daemons.

      <<forgejo-runner-ownership>>

      system.activationScripts.launchd.text = lib.mkBefore (
        lib.concatMapStringsSep "\n" (instance: ''
          mkdir -p ${lib.escapeShellArg instance.stateDir}
          chown -R ${lib.escapeShellArg cfg.user}:${lib.escapeShellArg cfg.group} ${lib.escapeShellArg instance.stateDir}
        '') (lib.attrValues enabledInstances)
      );