flake.nix

{
  description = "commy plugin — substrate-agnostic agent communications";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";

    # Reached only by `devShells.maintainer`. Nix fetches flake inputs per
    # output, so `nix develop` and `nix develop .#ci` — everything a
    # contributor and CI touch — never fetch, evaluate or build this. No
    # `inputs.nixpkgs.follows`: beads needs Go 1.26 and this flake's nixpkgs
    # carries 1.25.
    beads.url = "github:gastownhall/beads/v1.1.2";
  };

  outputs =
    { nixpkgs, beads, ... }:
    let
      systems = [
        "x86_64-linux"
        "aarch64-linux"
        "x86_64-darwin"
        "aarch64-darwin"
      ];
      forAllSystems =
        f:
        nixpkgs.lib.genAttrs systems (
          system:
          f {
            inherit system;
            pkgs = nixpkgs.legacyPackages.${system};
          }
        );

      # Single source of truth for the plugin version — read from its pyproject
      # so the flake and the package never drift.
      pluginVersion =
        (builtins.fromTOML (builtins.readFile ./clients/hermes/pyproject.toml)).project.version;

      # The Hermes platform plugin (clients/hermes), built straight from the
      # monorepo subdir as a pyproject package that exposes the
      # `hermes_agent.plugins` entry point. Consumers add it to
      # `services.hermes-agent.extraPythonPackages`; Hermes then discovers it via
      # importlib.metadata and `hermes plugins enable commy-platform` activates
      # it. `gateway` / `BasePlatformAdapter` come from the host Hermes at
      # runtime, so there are no runtime deps and the Nix build neither imports
      # nor tests the module — the repo gate (clients/hermes/scripts/test.sh)
      # does that against a real `hermes-agent`.
      commyHermesPlugin =
        pythonPackages:
        pythonPackages.buildPythonPackage {
          pname = "commy-hermes";
          version = pluginVersion;
          pyproject = true;
          src = nixpkgs.lib.cleanSourceWith {
            src = ./clients/hermes;
            filter =
              path: _type:
              let
                base = baseNameOf path;
              in
              !(
                builtins.elem base [
                  ".venv"
                  "dist"
                  "build"
                  "__pycache__"
                  ".pytest_cache"
                  ".ruff_cache"
                ]
                || nixpkgs.lib.hasSuffix ".pyc" base
              );
          };
          build-system = [ pythonPackages.setuptools ];
          doCheck = false;
        };
    in
    {
      packages = forAllSystems (
        { pkgs, ... }:
        rec {
          commy-hermes = commyHermesPlugin pkgs.python3Packages;
          default = commy-hermes;
        }
      );

      # Adds `commy-hermes` to every Python package set, so a consumer can build
      # it against the same Python as their `hermes-agent` (version-matched) and
      # pass it to `services.hermes-agent.extraPythonPackages`.
      overlays.default = _final: prev: {
        pythonPackagesExtensions = (prev.pythonPackagesExtensions or [ ]) ++ [
          (pyfinal: _pyprev: { commy-hermes = commyHermesPlugin pyfinal; })
        ];
      };

      devShells = forAllSystems (
        { pkgs, system }:
        let
          # Tooling the gate needs: bun runs the TS gate, uv drives the
          # clients/hermes Python gate (//#test:hermes → scripts/test.sh).
          # Shared by both shells so `bun run check`, the pre-commit hook,
          # and CI resolve identical tools rather than a global PATH install.
          gateTools = [
            pkgs.bun
            pkgs.uv
          ];
        in
        {
          default = pkgs.mkShell {
            packages = gateTools ++ [ pkgs.typescript-language-server ];
          };
          # Lean gate shell for CI: exactly gateTools, no interactive extras
          # (no language server). CI runs
          # `nix develop .#ci --command bun run check`, so it carries only what
          # the gate needs.
          ci = pkgs.mkShell {
            packages = gateTools;
          };
          # The default shell plus `bd`, the client for the maintainers' issue
          # tracker. That tracker is not part of this repository — external
          # contributors don't need it and file GitHub issues instead (see
          # AGENTS.md) — so `bd` lives here rather than in `default`, and
          # entering this shell is opt-in. Select it locally with an untracked
          # `.envrc.local` containing `use flake .#maintainer`.
          maintainer = pkgs.mkShell {
            packages = gateTools ++ [
              pkgs.typescript-language-server
              beads.packages.${system}.bd
            ];
          };
        }
      );
    };
}