hyperhive/nix/docs/default.nix

{
  pkgs,
  lib,
  self,
  nixosSystem,
}:
# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
# module trees, emitted as CommonMark (`host.md` + `agent.md`). The
# HTML + CSS for `/options/` is rendered downstream by the website
# repo, which owns the presentation and shares one stylesheet with the
# prose `/docs/` tree. Full pipeline + subtree-pick / output-tree
# rationale: docs/gotchas.md::Nix options reference.
let
  # Content-addressed narrow source covering only the nix/ directory.
  # `builtins.unsafeDiscardStringContext` strips `self`'s store-path
  # context so `builtins.path` hashes only the nix/ file content, not
  # the full flake source (Rust, frontend, markdown, …).  Result: the
  # docs drvs only change when a .nix file changes, not on every
  # commit — the muede-pc2 remote builder can reuse its cached result
  # for any commit that doesn't touch nix/.
  nixSrc = builtins.path {
    path = builtins.unsafeDiscardStringContext (toString self + "/nix");
    name = "hyperhive-nix-src";
  };

  # Stub overlay that satisfies pkgs.hyperhive-* references in module
  # option defaults without depending on self's Rust / frontend builds.
  # nixosOptionsDoc renders `defaultText` for these options anyway; the
  # stubs just prevent attribute-missing eval errors.
  docsStubOverlay = _final: _prev: {
    hyperhive = pkgs.emptyFile;
    hyperhive-frontend = pkgs.emptyDirectory;
    hyperhive-assets = pkgs.emptyDirectory;
    hyperhive-docs = pkgs.emptyDirectory;
  };

  # Stub host system: every hyperhive subsystem `mkForce false` so
  # heavy build inputs (matrix container, forge, etc.) stay out of
  # the eval — only option *declarations* matter for the doc walk.
  # Import hive-c0re.nix from the content-addressed nixSrc with stub
  # package args so the eval doesn't depend on self's Rust builds.
  hostEval = nixosSystem {
    system = pkgs.stdenv.hostPlatform.system;
    modules = [
      (import "${nixSrc}/modules/hive-c0re.nix" {
        hyperhivePackage = _system: pkgs.emptyFile;
        hyperhiveFrontend = _system: pkgs.emptyFile;
        hyperhiveAssets = _system: pkgs.emptyDirectory;
        hyperhiveFlake = "";
        hyperhiveDocs = "";
        agentBaseToplevel = pkgs.emptyFile;
        managerToplevel = pkgs.emptyFile;
      })
      (
        { lib, ... }:
        {
          nixpkgs.overlays = [ docsStubOverlay ];
          fileSystems."/" = {
            device = "/dev/null";
            fsType = "tmpfs";
          };
          boot.loader.grub.enable = false;
          system.stateVersion = "25.11";
          services.hyperhive.enable = lib.mkForce false;
          services.hyperhive.matrix.enable = lib.mkForce false;
        }
      )
    ];
  };

  # Agent module eval from the content-addressed nixSrc.  Relative
  # imports inside agent-base.nix (e.g. ./harness-base.nix) resolve
  # correctly against the nixSrc directory tree.
  agentEval = nixosSystem {
    system = pkgs.stdenv.hostPlatform.system;
    modules = [
      "${nixSrc}/templates/agent-base.nix"
      { nixpkgs.overlays = [ docsStubOverlay ]; }
    ];
  };

  # Rewrite option declaration paths from nix-store absolute paths to
  # forge URLs so rendered docs link back to source.
  # nixSrc is a content-addressed copy of nix/; strip its store prefix
  # and prepend nix/ to recover the repo-relative path.
  forgeRoot = "https://forge.darkest.space/hyperhive/hyperhive/src/branch/main";
  nixSrcPrefix = builtins.unsafeDiscardStringContext (toString nixSrc + "/");
  transformOptions =
    opt:
    opt
    // {
      declarations = map (
        decl:
        let
          declStr = toString decl;
          relPath =
            if lib.hasPrefix nixSrcPrefix declStr then
              "nix/" + lib.removePrefix nixSrcPrefix declStr
            else
              baseNameOf declStr;
        in
        {
          url = "${forgeRoot}/${relPath}";
          name = relPath;
        }
      ) opt.declarations;
    };

  # Filter to a set of top-level subtree roots — keeps the rendered docs
  # focused on hyperhive's surface instead of NixOS's 10k+ default
  # options. Root choice matters: see docs/gotchas.md::Nix options
  # reference for the services.hyperhive consolidation history.
  pickSubtrees =
    options: roots:
    let
      pick =
        path:
        if lib.hasAttrByPath path options then
          lib.setAttrByPath path (lib.getAttrFromPath path options)
        else
          { };
    in
    lib.foldl' lib.recursiveUpdate { } (map pick roots);

  hostOptions = pickSubtrees hostEval.options [
    [
      "services"
      "hyperhive"
    ]
  ];

  agentOptions = pickSubtrees agentEval.options [
    [ "hyperhive" ]
  ];

  hostDoc = pkgs.nixosOptionsDoc {
    options = hostOptions;
    inherit transformOptions;
  };

  agentDoc = pkgs.nixosOptionsDoc {
    options = agentOptions;
    inherit transformOptions;
  };

  # CommonMark `.md` is the source of truth and the only output. HTML
  # rendering + theming lives in the website repo (it owns the
  # presentation + shares one stylesheet across `/options/` and
  # `/docs/`); this flake just emits the option reference as markdown.
  mkMarkdownPage =
    name: title: doc:
    pkgs.runCommand "hyperhive-${name}.md" { } ''
      {
        echo "# ${title}"
        echo
        echo "<!-- Auto-generated from the hyperhive flake."
        echo "     Source: nix/docs/default.nix · regenerate with"
        echo "     \`nix build .#${name}\` -->"
        echo
        cat ${doc.optionsCommonMark}
      } > $out
    '';

  # Bundle landing page — a short markdown index pointing at the two
  # reference pages.
  indexMD = pkgs.writeText "hyperhive-options-index.md" ''
    # hyperhive — nix options reference

    Auto-generated from the hyperhive flake. Two reading paths:

    - [host options](host.md) — options exposed by
      `hyperhive.nixosModules.default` to operator host configurations
      (`services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*`).
    - [per-agent options](agent.md) — options declared in
      `nix/templates/harness-base.nix`, visible from every `agent.nix`
      (`hyperhive.model`, `hyperhive.allowedRecipients`,
      `hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
      `hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).

    Regenerate with `nix build .#docs` (bundle), `.#docs-host`, or
    `.#docs-agent`. Consumed by the website repo to render `/options/`.
  '';

  hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
  agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
in
{
  host = hostMD;
  agent = agentMD;

  # Bundle of the option reference as markdown. The website renders
  # these `.md` to themed HTML for `/options/`; standalone consumers
  # get the CommonMark source directly.
  bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
    mkdir -p $out
    cp ${indexMD} $out/index.md
    cp ${hostMD} $out/host.md
    cp ${agentMD} $out/agent.md
  '';
}