vars: move logic from vars-to-sops into single file

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5476

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Description of the change
+
+<!-- Brief summary of the change if not already clear from the title -->
+
+## Checklist
+
+- [ ] Updated Documentation
+- [ ] Added tests
+- [ ] Doesn't affect backwards compatibility - or check the next points
+  - [ ] Add the breaking change and migration details to docs/release-notes.md
+  - !!! Review from another person is required *BEFORE* merge !!!
+- [ ] Add introduction of major feature to docs/release-notes.md

checks/flake-module.nix

@@ -19,28 +19,19 @@ let
   nixosLib = import (self.inputs.nixpkgs + "/nixos/lib") { };
 in
 {
-  imports =
-    let
-      clanCoreModulesDir = ../nixosModules/clanCore;
-      getClanCoreTestModules =
-        let
-          moduleNames = attrNames (builtins.readDir clanCoreModulesDir);
-          testPaths = map (
-            moduleName: clanCoreModulesDir + "/${moduleName}/tests/flake-module.nix"
-          ) moduleNames;
-        in
-        filter pathExists testPaths;
-    in
-    getClanCoreTestModules
-    ++ filter pathExists [
-      ./devshell/flake-module.nix
-      ./flash/flake-module.nix
-      ./installation/flake-module.nix
-      ./update/flake-module.nix
-      ./morph/flake-module.nix
-      ./nixos-documentation/flake-module.nix
-      ./dont-depend-on-repo-root.nix
-    ];
+  imports = filter pathExists [
+    ./devshell/flake-module.nix
+    ./flash/flake-module.nix
+    ./installation/flake-module.nix
+    ./update/flake-module.nix
+    ./morph/flake-module.nix
+    ./nixos-documentation/flake-module.nix
+    ./dont-depend-on-repo-root.nix
+    # clan core submodule tests
+    ../nixosModules/clanCore/machine-id/tests/flake-module.nix
+    ../nixosModules/clanCore/postgresql/tests/flake-module.nix
+    ../nixosModules/clanCore/state-version/tests/flake-module.nix
+  ];
   flake.check = genAttrs [ "x86_64-linux" "aarch64-darwin" ] (
     system:
     let
@@ -120,7 +111,7 @@ in
             ) (self.darwinConfigurations or { })
             // lib.mapAttrs' (n: lib.nameValuePair "package-${n}") (
               if system == "aarch64-darwin" then
-                lib.filterAttrs (n: _: n != "docs" && n != "deploy-docs" && n != "docs-options") packagesToBuild
+                lib.filterAttrs (n: _: n != "docs" && n != "deploy-docs" && n != "option-search") packagesToBuild
               else
                 packagesToBuild
             )

checks/installation/test-helpers.nix

@@ -15,7 +15,6 @@ let
       networking.useNetworkd = true;
       services.openssh.enable = true;
       services.openssh.settings.UseDns = false;
-      services.openssh.settings.PasswordAuthentication = false;
       system.nixos.variant_id = "installer";
       environment.systemPackages = [
         pkgs.nixos-facter

devFlake/flake.lock

@@ -3,10 +3,10 @@
     "clan-core-for-checks": {
       "flake": false,
       "locked": {
-        "lastModified": 1759915474,
-        "narHash": "sha256-ef7awwmx2onWuA83FNE29B3tTZ+tQxEWLD926ckMiF8=",
+        "lastModified": 1760213549,
+        "narHash": "sha256-XosVRUEcdsoEdRtXyz9HrRc4Dt9Ke+viM5OVF7tLK50=",
         "ref": "main",
-        "rev": "81e15cab34f9ae00b6f2df5f2e53ee07cd3a0af3",
+        "rev": "9c8797e77031d8d472d057894f18a53bdc9bbe1e",
         "shallow": true,
         "type": "git",
         "url": "https://git.clan.lol/clan/clan-core"
@@ -105,11 +105,11 @@
     },
     "nixpkgs-dev": {
       "locked": {
-        "lastModified": 1759860509,
-        "narHash": "sha256-c7eJvqAlWLhwNc9raHkQ7mvoFbHLUO/cLMrww1ds4Zg=",
+        "lastModified": 1760161054,
+        "narHash": "sha256-PO3cKHFIQEPI0dr/SzcZwG50cHXfjoIqP2uS5W78OXg=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "b574dcadf3fb578dee8d104b565bd745a5a9edc0",
+        "rev": "e18d8ec6fafaed55561b7a1b54eb1c1ce3ffa2c5",
         "type": "github"
       },
       "original": {
@@ -208,11 +208,11 @@
         "nixpkgs": []
       },
       "locked": {
-        "lastModified": 1758728421,
-        "narHash": "sha256-ySNJ008muQAds2JemiyrWYbwbG+V7S5wg3ZVKGHSFu8=",
+        "lastModified": 1760120816,
+        "narHash": "sha256-gq9rdocpmRZCwLS5vsHozwB6b5nrOBDNc2kkEaTXHfg=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "5eda4ee8121f97b218f7cc73f5172098d458f1d1",
+        "rev": "761ae7aff00907b607125b2f57338b74177697ed",
         "type": "github"
       },
       "original": {

docs/.gitignore

@@ -1,6 +1,6 @@
 /site/reference
 /site/services/official
 /site/static
-/site/options
+/site/option-search
 /site/openapi.json
 !/site/static/extra.css

docs/mkdocs.yml

@@ -180,7 +180,7 @@ nav:
           - services/official/zerotier.md
       - services/community.md
 
-  - Search Clan Options: "/options"
+  - Search Clan Options: "/option-search"
 
 docs_dir: site
 site_dir: out

docs/nix/default.nix

@@ -5,7 +5,7 @@
   clan-lib-openapi,
   roboto,
   fira-code,
-  docs-options,
+  option-search,
   ...
 }:
 let
@@ -51,9 +51,9 @@ pkgs.stdenv.mkDerivation {
     chmod -R +w ./site
     echo "Generated API documentation in './site/reference/' "
 
-    rm -rf ./site/options
-    cp -r ${docs-options} ./site/options
-    chmod -R +w ./site/options
+    rm -rf ./site/option-search
+    cp -r ${option-search} ./site/option-search
+    chmod -R +w ./site/option-search
 
     # Link to fonts
     ln -snf ${roboto}/share/fonts/truetype/Roboto-Regular.ttf ./site/static/

docs/nix/flake-module.nix

@@ -1,8 +1,5 @@
-{ inputs, self, ... }:
+{ inputs, ... }:
 {
-  imports = [
-    ./options/flake-module.nix
-  ];
   perSystem =
     {
       config,
@@ -10,74 +7,7 @@
       pkgs,
       ...
     }:
-    let
-      # Simply evaluated options (JSON)
-      # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; }
-      jsonDocs = pkgs.callPackage ./get-module-docs.nix {
-        inherit (self) clanModules;
-        clan-core = self;
-        inherit pkgs;
-      };
-
-      # clan service options
-      clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService);
-
-      # Simply evaluated options (JSON)
-      renderOptions =
-        pkgs.runCommand "render-options"
-          {
-            # TODO: ruff does not splice properly in nativeBuildInputs
-            depsBuildBuild = [ pkgs.ruff ];
-            nativeBuildInputs = [
-              pkgs.python3
-              pkgs.mypy
-              self'.packages.clan-cli
-            ];
-          }
-          ''
-            install -D -m755 ${./render_options}/__init__.py $out/bin/render-options
-            patchShebangs --build $out/bin/render-options
-
-            ruff format --check --diff $out/bin/render-options
-            ruff check --line-length 88 $out/bin/render-options
-            mypy --strict $out/bin/render-options
-          '';
-
-      module-docs =
-        pkgs.runCommand "rendered"
-          {
-            buildInputs = [
-              pkgs.python3
-              self'.packages.clan-cli
-            ];
-          }
-          ''
-            export CLAN_CORE_PATH=${
-              inputs.nixpkgs.lib.fileset.toSource {
-                root = ../..;
-                fileset = ../../clanModules;
-              }
-            }
-            export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
-
-            # A file that contains the links to all clanModule docs
-            export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService}
-            export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json
-            export CLAN_OPTIONS_PATH=${self'.legacyPackages.clan-options}/share/doc/nixos/options.json
-
-            mkdir $out
-
-            # The python script will place mkDocs files in the output directory
-            exec python3 ${renderOptions}/bin/render-options
-          '';
-    in
     {
-      legacyPackages = {
-        inherit
-          jsonDocs
-          clanModulesViaService
-          ;
-      };
       devShells.docs = self'.packages.docs.overrideAttrs (_old: {
         nativeBuildInputs = [
           # Run: htmlproofer --disable-external
@@ -96,15 +26,14 @@
         docs = pkgs.python3.pkgs.callPackage ./default.nix {
           inherit (self'.packages)
             clan-cli-docs
-            docs-options
+            option-search
             inventory-api-docs
             clan-lib-openapi
+            module-docs
             ;
           inherit (inputs) nixpkgs;
-          inherit module-docs;
         };
         deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; };
-        inherit module-docs;
       };
       checks.docs-integrity =
         pkgs.runCommand "docs-integrity"

docs/release-notes.md

@@ -0,0 +1,9 @@
+# clan-core release notes 25.11
+
+<!-- This is not rendered yet -->
+
+## New features
+
+## Breaking Changes
+
+## Misc

docs/site/guides/services/community.md

@@ -288,7 +288,7 @@ of their type.
 In the inventory we the assign machines to a type, e.g. by using tags
 
 ```nix title="flake.nix"
-instnaces.machine-type = {
+instances.machine-type = {
   module.input = "self";
   module.name = "@pinpox/machine-type";
   roles.desktop.tags.desktop = { };

docs/site/index.md

@@ -122,7 +122,7 @@ hide:
 
     command line interface
 
--   [Clan Options](/options)
+-   [Clan Options](./reference/options/clan.md)
 
     ---
 

docs/site/reference/index.md

@@ -4,10 +4,10 @@ This section of the site provides an overview of available options and commands
 
 ---
 
-- [Clan Configuration Option](/options) - for defining a Clan
 - Learn how to use the [Clan CLI](../reference/cli/index.md)
 - Explore available [services](../services/definition.md)
 - [NixOS Configuration Options](../reference/clan.core/index.md) - Additional options avilable on a NixOS machine.
+- [Search Clan Option](/option-search) - for defining a Clan
 
 ---
 

flake.lock

@@ -181,11 +181,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1758728421,
-        "narHash": "sha256-ySNJ008muQAds2JemiyrWYbwbG+V7S5wg3ZVKGHSFu8=",
+        "lastModified": 1760120816,
+        "narHash": "sha256-gq9rdocpmRZCwLS5vsHozwB6b5nrOBDNc2kkEaTXHfg=",
         "owner": "numtide",
         "repo": "treefmt-nix",
-        "rev": "5eda4ee8121f97b218f7cc73f5172098d458f1d1",
+        "rev": "761ae7aff00907b607125b2f57338b74177697ed",
         "type": "github"
       },
       "original": {

lib/clanTest/virtual-fs.nix

@@ -0,0 +1,51 @@
+{ lib }:
+let
+  sanitizePath =
+    rootPath: path:
+    let
+      storePrefix = builtins.unsafeDiscardStringContext ("${rootPath}");
+      pathStr = lib.removePrefix "/" (
+        lib.removePrefix storePrefix (builtins.unsafeDiscardStringContext (toString path))
+      );
+    in
+    pathStr;
+
+  mkFunctions = rootPath: passthru: virtual_fs: {
+    # Some functions to override lib functions
+    pathExists =
+      path:
+      let
+        pathStr = sanitizePath rootPath path;
+        isPassthru = builtins.any (exclude: (builtins.match exclude pathStr) != null) passthru;
+      in
+      if isPassthru then
+        builtins.pathExists path
+      else
+        let
+          res = virtual_fs ? ${pathStr};
+        in
+        lib.trace "pathExists: '${pathStr}' -> '${lib.generators.toPretty { } res}'" res;
+    readDir =
+      path:
+      let
+        pathStr = sanitizePath rootPath path;
+        base = (pathStr + "/");
+        res = lib.mapAttrs' (name: fileInfo: {
+          name = lib.removePrefix base name;
+          value = fileInfo.type;
+        }) (lib.filterAttrs (n: _: lib.hasPrefix base n) virtual_fs);
+        isPassthru = builtins.any (exclude: (builtins.match exclude pathStr) != null) passthru;
+      in
+      if isPassthru then
+        builtins.readDir path
+      else
+        lib.trace "readDir: '${pathStr}' -> '${lib.generators.toPretty { } res}'" res;
+  };
+in
+{
+  virtual_fs,
+  rootPath,
+  # Patterns
+  passthru ? [ ],
+}:
+mkFunctions rootPath passthru virtual_fs

lib/default.nix

@@ -36,6 +36,10 @@ lib.fix (
 
       # TODO: Flatten our lib functions like this:
       resolveModule = clanLib.callLib ./resolve-module { };
+
+      fs = {
+        inherit (builtins) pathExists readDir;
+      };
     };
   in
   f

lib/modules/clan/module.nix

@@ -133,12 +133,13 @@ in
       }
     )
     {
-      # TODO: Figure out why this causes infinite recursion
-      inventory.machines = lib.optionalAttrs (builtins.pathExists "${directory}/machines") (
-        builtins.mapAttrs (_n: _v: { }) (
-          lib.filterAttrs (_: t: t == "directory") (builtins.readDir "${directory}/machines")
-        )
-      );
+      # Note: we use clanLib.fs here, so that we can override it in tests
+      inventory = lib.optionalAttrs (clanLib.fs.pathExists "${directory}/machines") ({
+        imports = lib.mapAttrsToList (name: _t: {
+          _file = "${directory}/machines/${name}";
+          machines.${name} = { };
+        }) ((lib.filterAttrs (_: t: t == "directory") (clanLib.fs.readDir "${directory}/machines")));
+      });
     }
     {
       inventory.machines = lib.mapAttrs (_n: _: { }) config.machines;

lib/modules/dir_test.nix

@@ -0,0 +1,108 @@
+{
+  lib ? import <nixpkgs/lib>,
+}:
+let
+  clanLibOrig = (import ./.. { inherit lib; }).__unfix__;
+  clanLibWithFs =
+    { virtual_fs }:
+    lib.fix (
+      lib.extends (
+        final: _:
+        let
+          clan-core = {
+            clanLib = final;
+            modules.clan.default = lib.modules.importApply ./clan { inherit clan-core; };
+
+            # Note: Can add other things to "clan-core"
+            # ... Not needed for this test
+          };
+        in
+        {
+          clan = import ../clan {
+            inherit lib clan-core;
+          };
+
+          # Override clanLib.fs for unit-testing against a virtual filesystem
+          fs = import ../clanTest/virtual-fs.nix { inherit lib; } {
+            inherit rootPath virtual_fs;
+            # Example of a passthru
+            # passthru = [
+            #   ".*inventory\.json$"
+            # ];
+          };
+        }
+      ) clanLibOrig
+    );
+
+  rootPath = ./.;
+in
+{
+  test_autoload_directories =
+    let
+      vclan =
+        (clanLibWithFs {
+          virtual_fs = {
+            "machines" = {
+              type = "directory";
+            };
+            "machines/foo-machine" = {
+              type = "directory";
+            };
+            "machines/bar-machine" = {
+              type = "directory";
+            };
+          };
+        }).clan
+          { config.directory = rootPath; };
+    in
+    {
+      inherit vclan;
+      expr = {
+        machines = lib.attrNames vclan.config.inventory.machines;
+        definedInMachinesDir = map (
+          p: lib.hasInfix "/machines/" p
+        ) vclan.options.inventory.valueMeta.configuration.options.machines.files;
+      };
+      expected = {
+        machines = [
+          "bar-machine"
+          "foo-machine"
+        ];
+        definedInMachinesDir = [
+          true # /machines/foo-machine
+          true # /machines/bar-machine
+          false # <clan-core>/module.nix defines "machines" without members
+        ];
+      };
+    };
+
+  # Could probably be unified with the previous test
+  # This is here for the sake to show that 'virtual_fs' is a test parameter
+  test_files_are_not_machines =
+    let
+      vclan =
+        (clanLibWithFs {
+          virtual_fs = {
+            "machines" = {
+              type = "directory";
+            };
+            "machines/foo.nix" = {
+              type = "file";
+            };
+            "machines/bar.nix" = {
+              type = "file";
+            };
+          };
+        }).clan
+          { config.directory = rootPath; };
+    in
+    {
+      inherit vclan;
+      expr = {
+        machines = lib.attrNames vclan.config.inventory.machines;
+      };
+      expected = {
+        machines = [ ];
+      };
+    };
+}

lib/modules/tests.nix

@@ -12,6 +12,7 @@ let
 in
 #######
 {
+  autoloading = import ./dir_test.nix { inherit lib; };
   test_missing_self =
     let
       eval = clan {

nixosModules/clanCore/facts/compat.nix

@@ -164,13 +164,25 @@
   config = lib.mkIf (config.clan.core.secrets != { }) {
     clan.core.facts.services = lib.mapAttrs' (
       name: service:
-      lib.warn "clan.core.secrets.${name} is deprecated, use clan.core.facts.services.${name} instead" (
-        lib.nameValuePair name ({
-          secret = service.secrets;
-          public = service.facts;
-          generator = service.generator;
-        })
-      )
+      lib.warn
+        ''
+          ###############################################################################
+          #                                                                             #
+          # clan.core.secrets.${name} clan.core.facts.services.${name} is deprecated    #
+          # in favor of "vars"                                                          #
+          #                                                                             #
+          # Refer to https://docs.clan.lol/guides/migrations/migration-facts-vars/      #
+          # for migration instructions.                                                 #
+          #                                                                             #
+          ###############################################################################
+        ''
+        (
+          lib.nameValuePair name ({
+            secret = service.secrets;
+            public = service.facts;
+            generator = service.generator;
+          })
+        )
     ) config.clan.core.secrets;
   };
 }

nixosModules/clanCore/facts/default.nix

@@ -6,7 +6,17 @@
 }:
 {
   config.warnings = lib.optionals (config.clan.core.facts.services != { }) [
-    "Facts are deprecated, please migrate them to vars instead, see: https://docs.clan.lol/guides/migrations/migration-facts-vars/"
+    ''
+      ###############################################################################
+      #                                                                             #
+      # Facts are deprecated please migrate any usages to vars instead              #
+      #                                                                             #
+      #                                                                             #
+      # Refer to https://docs.clan.lol/guides/migrations/migration-facts-vars/      #
+      # for migration instructions.                                                 #
+      #                                                                             #
+      ###############################################################################
+    ''
   ];
 
   options.clan.core.facts = {

nixosModules/clanCore/vars/secret/sops/collectFiles.nix

@@ -1,37 +0,0 @@
-# collectFiles helper function
-{
-  lib ? import <nixpkgs/lib>,
-}:
-let
-  inherit (lib)
-    filterAttrs
-    flatten
-    mapAttrsToList
-    ;
-in
-generators:
-let
-  relevantFiles =
-    generator:
-    filterAttrs (
-      _name: f: f.secret && f.deploy && (f.neededFor == "users" || f.neededFor == "services")
-    ) generator.files;
-  allFiles = flatten (
-    mapAttrsToList (
-      gen_name: generator:
-      mapAttrsToList (fname: file: {
-        name = fname;
-        generator = gen_name;
-        neededForUsers = file.neededFor == "users";
-        inherit (generator) share;
-        inherit (file)
-          owner
-          group
-          mode
-          restartUnits
-          ;
-      }) (relevantFiles generator)
-    ) generators
-  );
-in
-allFiles

nixosModules/clanCore/vars/secret/sops/default.nix

@@ -7,19 +7,9 @@
 }:
 let
 
-  collectFiles = import ./collectFiles.nix { inherit lib; };
+  mapGeneratorsToSopsSecrets = import ./generators-to-sops.nix { inherit lib; };
 
   machineName = config.clan.core.settings.machine.name;
-
-  secretPath =
-    secret:
-    if secret.share then
-      config.clan.core.settings.directory + "/vars/shared/${secret.generator}/${secret.name}/secret"
-    else
-      config.clan.core.settings.directory
-      + "/vars/per-machine/${machineName}/${secret.generator}/${secret.name}/secret";
-
-  vars = collectFiles config.clan.core.vars.generators;
 in
 {
   config.clan.core.vars.settings = lib.mkIf (config.clan.core.vars.settings.secretStore == "sops") {
@@ -39,28 +29,13 @@ in
   };
 
   config.sops = lib.mkIf (config.clan.core.vars.settings.secretStore == "sops") {
-
-    secrets = lib.listToAttrs (
-      map (secret: {
-        name = "vars/${secret.generator}/${secret.name}";
-        value = {
-          inherit (secret)
-            owner
-            group
-            mode
-            neededForUsers
-            ;
-          sopsFile = builtins.path {
-            name = "${secret.generator}_${secret.name}";
-            path = secretPath secret;
-          };
-          format = "binary";
-        }
-        // (lib.optionalAttrs (_class == "nixos") {
-          inherit (secret) restartUnits;
-        });
-      }) (builtins.filter (x: builtins.pathExists (secretPath x)) vars)
-    );
+    #
+    secrets = mapGeneratorsToSopsSecrets {
+      inherit machineName;
+      directory = config.clan.core.settings.directory;
+      class = _class;
+      generators = config.clan.core.vars.generators;
+    };
 
     # To get proper error messages about missing secrets we need a dummy secret file that is always present
     defaultSopsFile = lib.mkIf config.sops.validateSopsFiles (

nixosModules/clanCore/vars/secret/sops/generators-to-sops.nix

@@ -0,0 +1,77 @@
+# This file maps generators to sops.secrets
+# TODO(@davHau): add tests
+{
+  lib ? import <nixpkgs/lib>,
+  # Can be mocked for testing
+  pathExists ? builtins.pathExists,
+}:
+let
+  inherit (lib)
+    filterAttrs
+    mapAttrsToList
+    ;
+
+  relevantFiles = filterAttrs (
+    _name: f: f.secret && f.deploy && (f.neededFor == "users" || f.neededFor == "services")
+  );
+
+  extractSecretDefinitions =
+    generators:
+    builtins.concatLists (
+      mapAttrsToList (
+        gen_name: generator:
+        mapAttrsToList (fname: file: {
+          name = fname;
+          generator = gen_name;
+          neededForUsers = file.neededFor == "users";
+          inherit (generator) share;
+          inherit (file)
+            owner
+            group
+            mode
+            restartUnits
+            ;
+        }) (relevantFiles generator.files)
+      ) generators
+    );
+
+  mapGeneratorsToSopsSecrets =
+    {
+      machineName,
+      directory,
+      class,
+      generators,
+    }:
+    assert lib.assertMsg (class == "nixos" || class == "darwin")
+      "Error trying to map 'var.generators' to 'sops.secrets': class must be 'nixos' or 'darwin', got: ${class}";
+    let
+      getSecretPath =
+        secret:
+        let
+          scope = if secret.share then "shared" else "per-machine/${machineName}";
+        in
+        "${directory}/vars/${scope}/${secret.generator}/${secret.name}/secret";
+    in
+    lib.listToAttrs (
+      map (secret: {
+        name = "vars/${secret.generator}/${secret.name}";
+        value = {
+          inherit (secret)
+            owner
+            group
+            mode
+            neededForUsers
+            ;
+          sopsFile = builtins.path {
+            name = "${secret.generator}_${secret.name}";
+            path = getSecretPath secret;
+          };
+          format = "binary";
+        }
+        // (lib.optionalAttrs (class == "nixos") {
+          inherit (secret) restartUnits;
+        });
+      }) (builtins.filter (x: pathExists (getSecretPath x)) (extractSecretDefinitions generators))
+    );
+in
+mapGeneratorsToSopsSecrets

pkgs/clan-app/shell.nix

@@ -113,15 +113,27 @@ mkShell {
     # todo darwin support needs some work
     (lib.optionalString stdenv.hostPlatform.isLinux ''
       # configure playwright for storybook snapshot testing
-      export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+      # we only want webkit as that matches what the app is rendered with
+
       export PLAYWRIGHT_BROWSERS_PATH=${
         playwright-driver.browsers.override {
           withFfmpeg = false;
           withFirefox = false;
+          withWebkit = true;
           withChromium = false;
-          withChromiumHeadlessShell = true;
+          withChromiumHeadlessShell = false;
         }
       }
-      export PLAYWRIGHT_HOST_PLATFORM_OVERRIDE="ubuntu-24.04"
+
+      # stop playwright from trying to validate it has downloaded the necessary browsers
+      # we are providing them manually via nix
+
+      export PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS=true
+
+      # playwright browser drivers are versioned e.g. webkit-2191
+      # this helps us avoid having to update the playwright js dependency everytime we update nixpkgs and vice versa
+      # see vitest.config.js for corresponding launch configuration
+
+      export PLAYWRIGHT_WEBKIT_EXECUTABLE=$(find -L "$PLAYWRIGHT_BROWSERS_PATH" -type f -name "pw_run.sh")
     '');
 }

pkgs/clan-app/ui/package-lock.json

@@ -53,7 +53,7 @@
         "jsdom": "^26.1.0",
         "knip": "^5.61.2",
         "markdown-to-jsx": "^7.7.10",
-        "playwright": "~1.53.2",
+        "playwright": "~1.55.1",
         "postcss": "^8.4.38",
         "postcss-url": "^10.1.3",
         "prettier": "^3.2.5",
@@ -6956,13 +6956,13 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.53.2",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.53.2.tgz",
-      "integrity": "sha512-6K/qQxVFuVQhRQhFsVZ9fGeatxirtrpPgxzBYWyZLEXJzqYwuL4fuNmfOfD5et1tJE4GScKyPNeLhZeRwuTU3A==",
+      "version": "1.55.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.55.1.tgz",
+      "integrity": "sha512-cJW4Xd/G3v5ovXtJJ52MAOclqeac9S/aGGgRzLabuF8TnIb6xHvMzKIa6JmrRzUkeXJgfL1MhukP0NK6l39h3A==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.53.2"
+        "playwright-core": "1.55.1"
       },
       "bin": {
         "playwright": "cli.js"
@@ -6975,9 +6975,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.53.2",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.53.2.tgz",
-      "integrity": "sha512-ox/OytMy+2w1jcYEYlOo1Hhp8hZkLCximMTUTMBXjGUA1KoFfiSZ+DU+3a739jsPY0yoKH2TFy9S2fsJas8yAw==",
+      "version": "1.55.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.55.1.tgz",
+      "integrity": "sha512-Z6Mh9mkwX+zxSlHqdr5AOcJnfp+xUWLCt9uKV18fhzA8eyxUd8NUWzAjxUh55RZKSYwDGX0cfaySdhZJGMoJ+w==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {

pkgs/clan-app/ui/package.json

@@ -48,7 +48,7 @@
     "jsdom": "^26.1.0",
     "knip": "^5.61.2",
     "markdown-to-jsx": "^7.7.10",
-    "playwright": "~1.53.2",
+    "playwright": "~1.55.1",
     "postcss": "^8.4.38",
     "postcss-url": "^10.1.3",
     "prettier": "^3.2.5",

pkgs/clan-app/ui/src/components/Button/Button.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from "@kachurun/storybook-solid";
 import { Button, ButtonProps } from "./Button";
 import { Component } from "solid-js";
-import { expect, fn, waitFor } from "storybook/test";
+import { expect, fn, waitFor, within } from "storybook/test";
 import { StoryContext } from "@kachurun/storybook-solid-vite";
 
 const getCursorStyle = (el: Element) => window.getComputedStyle(el).cursor;
@@ -216,17 +216,11 @@ const timeout = process.env.NODE_ENV === "test" ? 500 : 2000;
 export const Primary: Story = {
   args: {
     hierarchy: "primary",
-    onAction: fn(async () => {
-      // wait 500 ms to simulate an action
-      await new Promise((resolve) => setTimeout(resolve, timeout));
-      // randomly fail to check that the loading state still returns to normal
-      if (Math.random() > 0.5) {
-        throw new Error("Action failure");
-      }
-    }),
+    onClick: fn(),
   },
 
-  play: async ({ canvas, step, userEvent, args }: StoryContext) => {
+  play: async ({ canvasElement, step, userEvent, args }: StoryContext) => {
+    const canvas = within(canvasElement);
     const buttons = await canvas.findAllByRole("button");
 
     for (const button of buttons) {
@@ -238,14 +232,6 @@ export const Primary: Story = {
       }
 
       await step(`Click on ${testID}`, async () => {
-        // check for the loader
-        const loaders = button.getElementsByClassName("loader");
-        await expect(loaders.length).toEqual(1);
-
-        // assert its width is 0 before we click
-        const [loader] = loaders;
-        await expect(loader.clientWidth).toEqual(0);
-
         // move the mouse over the button
         await userEvent.hover(button);
 
@@ -255,33 +241,8 @@ export const Primary: Story = {
         // click the button
         await userEvent.click(button);
 
-        // check the button has changed
-        await waitFor(
-          async () => {
-            // the action handler should have been called
-            await expect(args.onAction).toHaveBeenCalled();
-            // the button should have a loading class
-            await expect(button).toHaveClass("loading");
-            // the loader should be visible
-            await expect(loader.clientWidth).toBeGreaterThan(0);
-            // the pointer should have changed to wait
-            await expect(getCursorStyle(button)).toEqual("wait");
-          },
-          { timeout: timeout + 500 },
-        );
-
-        // wait for the action handler to finish
-        await waitFor(
-          async () => {
-            // the loading class should be removed
-            await expect(button).not.toHaveClass("loading");
-            // the loader should be hidden
-            await expect(loader.clientWidth).toEqual(0);
-            // the pointer should be normal
-            await expect(getCursorStyle(button)).toEqual("pointer");
-          },
-          { timeout: timeout + 500 },
-        );
+        // the click handler should have been called
+        await expect(args.onClick).toHaveBeenCalled();
       });
     }
   },

pkgs/clan-app/ui/src/components/Button/Button.tsx

@@ -57,6 +57,7 @@ export const Button = (props: ButtonProps) => {
 
   return (
     <KobalteButton
+      role="button"
       class={cx(
         styles.button, // default button class
         local.size != "default" && styles[local.size],

pkgs/clan-app/ui/src/components/Sidebar/Sidebar.stories.tsx

@@ -160,47 +160,47 @@ const mockFetcher = <K extends OperationNames>(
     },
   }) satisfies ApiCall<K>;
 
-export const Default: Story = {
-  args: {},
-  decorators: [
-    (Story: StoryObj) => {
-      const queryClient = new QueryClient({
-        defaultOptions: {
-          queries: {
-            retry: false,
-            staleTime: Infinity,
-          },
-        },
-      });
-
-      Object.entries(queryData).forEach(([clanURI, clan]) => {
-        queryClient.setQueryData(
-          ["clans", encodeBase64(clanURI), "details"],
-          clan.details,
-        );
-
-        const machines = clan.machines || {};
-
-        queryClient.setQueryData(
-          ["clans", encodeBase64(clanURI), "machines"],
-          machines,
-        );
-
-        Object.entries(machines).forEach(([name, machine]) => {
-          queryClient.setQueryData(
-            ["clans", encodeBase64(clanURI), "machine", name, "state"],
-            machine.state,
-          );
-        });
-      });
-
-      return (
-        <ApiClientProvider client={{ fetch: mockFetcher }}>
-          <QueryClientProvider client={queryClient}>
-            <Story />
-          </QueryClientProvider>
-        </ApiClientProvider>
-      );
-    },
-  ],
-};
+// export const Default: Story = {
+//   args: {},
+//   decorators: [
+//     (Story: StoryObj) => {
+//       const queryClient = new QueryClient({
+//         defaultOptions: {
+//           queries: {
+//             retry: false,
+//             staleTime: Infinity,
+//           },
+//         },
+//       });
+//
+//       Object.entries(queryData).forEach(([clanURI, clan]) => {
+//         queryClient.setQueryData(
+//           ["clans", encodeBase64(clanURI), "details"],
+//           clan.details,
+//         );
+//
+//         const machines = clan.machines || {};
+//
+//         queryClient.setQueryData(
+//           ["clans", encodeBase64(clanURI), "machines"],
+//           machines,
+//         );
+//
+//         Object.entries(machines).forEach(([name, machine]) => {
+//           queryClient.setQueryData(
+//             ["clans", encodeBase64(clanURI), "machine", name, "state"],
+//             machine.state,
+//           );
+//         });
+//       });
+//
+//       return (
+//         <ApiClientProvider client={{ fetch: mockFetcher }}>
+//           <QueryClientProvider client={queryClient}>
+//             <Story />
+//           </QueryClientProvider>
+//         </ApiClientProvider>
+//       );
+//     },
+//   ],
+// };

pkgs/clan-app/ui/src/modals/ClanSettingsModal/ClanSettingsModal.stories.tsx

@@ -11,28 +11,35 @@ export default meta;
 
 type Story = StoryObj<ClanSettingsModalProps>;
 
-export const Default: Story = {
-  args: {
-    onClose: fn(),
-    model: {
-      uri: "/home/foo/my-clan",
+const props: ClanSettingsModalProps = {
+  onClose: fn(),
+  model: {
+    uri: "/home/foo/my-clan",
+    details: {
       name: "Sol",
       description: null,
       icon: null,
-      fieldsSchema: {
-        name: {
-          readonly: true,
-          reason: null,
-        },
-        description: {
-          readonly: false,
-          reason: null,
-        },
-        icon: {
-          readonly: false,
-          reason: null,
-        },
+    },
+    fieldsSchema: {
+      name: {
+        readonly: true,
+        reason: null,
+        readonly_members: [],
+      },
+      description: {
+        readonly: false,
+        reason: null,
+        readonly_members: [],
+      },
+      icon: {
+        readonly: false,
+        reason: null,
+        readonly_members: [],
       },
     },
   },
 };
+
+export const Default: Story = {
+  args: props,
+};

pkgs/clan-app/ui/src/modals/ClanSettingsModal/ClanSettingsModal.tsx

@@ -22,9 +22,9 @@ import { Alert } from "@/src/components/Alert/Alert";
 import { removeClanURI } from "@/src/stores/clan";
 
 const schema = v.object({
-  name: v.pipe(v.optional(v.string())),
-  description: v.nullish(v.string()),
-  icon: v.pipe(v.nullish(v.string())),
+  name: v.string(),
+  description: v.optional(v.string()),
+  icon: v.optional(v.string()),
 });
 
 export interface ClanSettingsModalProps {

pkgs/clan-app/ui/src/scene/cubes.stories.tsx

@@ -1,15 +0,0 @@
-import { Meta, StoryObj } from "@kachurun/storybook-solid";
-import { CubeScene } from "./cubes";
-
-const meta: Meta = {
-  title: "scene/cubes",
-  component: CubeScene,
-};
-
-export default meta;
-
-type Story = StoryObj;
-
-export const Default: Story = {
-  args: {},
-};

pkgs/clan-app/ui/src/workflows/InstallMachine/steps/createInstaller.tsx

@@ -304,11 +304,10 @@ const FlashProgress = () => {
   const [store, set] = getStepStore<InstallStoreType>(stepSignal);
 
   onMount(async () => {
-    const result = await store.flash.progress.result;
-    if (result.status == "success") {
-      console.log("Flashing Success");
+    const result = await store.flash?.progress?.result;
+    if (result?.status == "success") {
+      stepSignal.next();
     }
-    stepSignal.next();
   });
 
   const handleCancel = async () => {

pkgs/clan-app/ui/src/workflows/Service/Service.stories.tsx

@@ -165,23 +165,23 @@ export default meta;
 
 type Story = StoryObj<typeof ServiceWorkflow>;
 
-export const Default: Story = {
-  args: {},
-};
-
-export const SelectRoleMembers: Story = {
-  render: () => (
-    <ServiceWorkflow
-      handleSubmit={(instance) => {
-        console.log("Submitted instance:", instance);
-      }}
-      onClose={() => {
-        console.log("Closed");
-      }}
-      initialStep="select:members"
-      initialStore={{
-        currentRole: "peer",
-      }}
-    />
-  ),
-};
+// export const Default: Story = {
+//   args: {},
+// };
+//
+// export const SelectRoleMembers: Story = {
+//   render: () => (
+//     <ServiceWorkflow
+//       handleSubmit={(instance) => {
+//         console.log("Submitted instance:", instance);
+//       }}
+//       onClose={() => {
+//         console.log("Closed");
+//       }}
+//       initialStep="select:members"
+//       initialStore={{
+//         currentRole: "peer",
+//       }}
+//     />
+//   ),
+// };

pkgs/clan-app/ui/tsconfig.json

@@ -9,7 +9,11 @@
     "esModuleInterop": true,
     "jsx": "preserve",
     "jsxImportSource": "solid-js",
-    "types": ["vite/client", "vite-plugin-solid-svg/types-component-solid"],
+    "types": [
+      "vite/client",
+      "vite-plugin-solid-svg/types-component-solid",
+      "@vitest/browser/providers/playwright"
+    ],
     "noEmit": true,
     "resolveJsonModule": true,
     "allowJs": true,

pkgs/clan-app/ui/vitest.config.ts

@@ -40,7 +40,14 @@ export default mergeConfig(
               enabled: true,
               headless: true,
               provider: "playwright",
-              instances: [{ browser: "chromium" }],
+              instances: [
+                {
+                  browser: "webkit",
+                  launch: {
+                    executablePath: process.env.PLAYWRIGHT_WEBKIT_EXECUTABLE,
+                  },
+                },
+              ],
             },
             // This setup file applies Storybook project annotations for Vitest
             // More info at: https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations

pkgs/clan-cli/clan_cli/tests/test_flake_with_core_dynamic_machines/flake.nix

@@ -1,24 +0,0 @@
-{
-  # Use this path to our repo root e.g. for UI test
-  # inputs.clan-core.url = "../../../../.";
-
-  # this placeholder is replaced by the path to nixpkgs
-  inputs.clan-core.url = "__CLAN_CORE__";
-
-  outputs =
-    { self, clan-core }:
-    let
-      clan = clan-core.lib.clan {
-        inherit self;
-        meta.name = "test_flake_with_core_dynamic_machines";
-        machines =
-          let
-            machineModules = builtins.readDir (self + "/machines");
-          in
-          builtins.mapAttrs (name: _type: import (self + "/machines/${name}")) machineModules;
-      };
-    in
-    {
-      inherit (clan.config) nixosConfigurations nixosModules clanInternals;
-    };
-}

pkgs/clan-cli/clan_cli/tests/test_vars.py

@@ -166,16 +166,16 @@ def test_generate_public_and_secret_vars(
     assert shared_value.startswith("shared")
     vars_text = stringify_all_vars(machine)
     flake_obj = Flake(str(flake.path))
-    my_generator = Generator("my_generator", machine="my_machine", _flake=flake_obj)
+    my_generator = Generator("my_generator", machines=["my_machine"], _flake=flake_obj)
     shared_generator = Generator(
         "my_shared_generator",
         share=True,
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     dependent_generator = Generator(
         "dependent_generator",
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     in_repo_store = in_repo.FactStore(flake=flake_obj)
@@ -340,12 +340,12 @@ def test_generate_secret_var_sops_with_default_group(
     flake_obj = Flake(str(flake.path))
     first_generator = Generator(
         "first_generator",
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     second_generator = Generator(
         "second_generator",
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     in_repo_store = in_repo.FactStore(flake=flake_obj)
@@ -375,13 +375,13 @@ def test_generate_secret_var_sops_with_default_group(
     first_generator_with_share = Generator(
         "first_generator",
         share=False,
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     second_generator_with_share = Generator(
         "second_generator",
         share=False,
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     assert sops_store.user_has_access("user2", first_generator_with_share, "my_secret")
@@ -432,7 +432,6 @@ def test_generated_shared_secret_sops(
     assert check_vars(machine1.name, machine1.flake)
     cli.run(["vars", "generate", "--flake", str(flake.path), "machine2"])
     assert check_vars(machine2.name, machine2.flake)
-    assert check_vars(machine2.name, machine2.flake)
     m1_sops_store = sops.SecretStore(machine1.flake)
     m2_sops_store = sops.SecretStore(machine2.flake)
     # Create generators with machine context for testing
@@ -513,28 +512,28 @@ def test_generate_secret_var_password_store(
         "my_generator",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     my_generator_shared = Generator(
         "my_generator",
         share=True,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     my_shared_generator = Generator(
         "my_shared_generator",
         share=True,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     my_shared_generator_not_shared = Generator(
         "my_shared_generator",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     assert store.exists(my_generator, "my_secret")
@@ -546,7 +545,7 @@ def test_generate_secret_var_password_store(
         name="my_generator",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     assert store.get(generator, "my_secret").decode() == "hello\n"
@@ -557,7 +556,7 @@ def test_generate_secret_var_password_store(
         "my_generator",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     var_name = "my_secret"
@@ -570,7 +569,7 @@ def test_generate_secret_var_password_store(
         "my_generator2",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     var_name = "my_secret2"
@@ -582,7 +581,7 @@ def test_generate_secret_var_password_store(
         "my_shared_generator",
         share=True,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     var_name = "my_shared_secret"
@@ -629,8 +628,8 @@ def test_generate_secret_for_multiple_machines(
     in_repo_store2 = in_repo.FactStore(flake=flake_obj)
 
     # Create generators for each machine
-    gen1 = Generator("my_generator", machine="machine1", _flake=flake_obj)
-    gen2 = Generator("my_generator", machine="machine2", _flake=flake_obj)
+    gen1 = Generator("my_generator", machines=["machine1"], _flake=flake_obj)
+    gen2 = Generator("my_generator", machines=["machine2"], _flake=flake_obj)
 
     assert in_repo_store1.exists(gen1, "my_value")
     assert in_repo_store2.exists(gen2, "my_value")
@@ -694,12 +693,12 @@ def test_prompt(
 
     # Set up objects for testing the results
     flake_obj = Flake(str(flake.path))
-    my_generator = Generator("my_generator", machine="my_machine", _flake=flake_obj)
+    my_generator = Generator("my_generator", machines=["my_machine"], _flake=flake_obj)
     my_generator_with_details = Generator(
         name="my_generator",
         share=False,
         files=[],
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
 
@@ -784,10 +783,10 @@ def test_shared_vars_regeneration(
     in_repo_store_2 = in_repo.FactStore(machine2.flake)
     # Create generators with machine context for testing
     child_gen_m1 = Generator(
-        "child_generator", share=False, machine="machine1", _flake=machine1.flake
+        "child_generator", share=False, machines=["machine1"], _flake=machine1.flake
     )
     child_gen_m2 = Generator(
-        "child_generator", share=False, machine="machine2", _flake=machine2.flake
+        "child_generator", share=False, machines=["machine2"], _flake=machine2.flake
     )
     # generate for machine 1
     cli.run(["vars", "generate", "--flake", str(flake.path), "machine1"])
@@ -855,13 +854,13 @@ def test_multi_machine_shared_vars(
     generator_m1 = Generator(
         "shared_generator",
         share=True,
-        machine="machine1",
+        machines=["machine1"],
         _flake=machine1.flake,
     )
     generator_m2 = Generator(
         "shared_generator",
         share=True,
-        machine="machine2",
+        machines=["machine2"],
         _flake=machine2.flake,
     )
     # generate for machine 1
@@ -917,7 +916,9 @@ def test_api_set_prompts(
     )
     machine = Machine(name="my_machine", flake=Flake(str(flake.path)))
     store = in_repo.FactStore(machine.flake)
-    my_generator = Generator("my_generator", machine="my_machine", _flake=machine.flake)
+    my_generator = Generator(
+        "my_generator", machines=["my_machine"], _flake=machine.flake
+    )
     assert store.exists(my_generator, "prompt1")
     assert store.get(my_generator, "prompt1").decode() == "input1"
     run_generators(
@@ -1061,10 +1062,10 @@ def test_migration(
     assert "Migrated var my_generator/my_value" in caplog.text
     assert "Migrated secret var my_generator/my_secret" in caplog.text
     flake_obj = Flake(str(flake.path))
-    my_generator = Generator("my_generator", machine="my_machine", _flake=flake_obj)
+    my_generator = Generator("my_generator", machines=["my_machine"], _flake=flake_obj)
     other_generator = Generator(
         "other_generator",
-        machine="my_machine",
+        machines=["my_machine"],
         _flake=flake_obj,
     )
     in_repo_store = in_repo.FactStore(flake=flake_obj)
@@ -1210,7 +1211,7 @@ def test_share_mode_switch_regenerates_secret(
     sops_store = sops.SecretStore(flake=flake_obj)
 
     generator_not_shared = Generator(
-        "my_generator", share=False, machine="my_machine", _flake=flake_obj
+        "my_generator", share=False, machines=["my_machine"], _flake=flake_obj
     )
 
     initial_public = in_repo_store.get(generator_not_shared, "my_value").decode()
@@ -1229,7 +1230,7 @@ def test_share_mode_switch_regenerates_secret(
 
     # Read the new values with shared generator
     generator_shared = Generator(
-        "my_generator", share=True, machine="my_machine", _flake=flake_obj
+        "my_generator", share=True, machines=["my_machine"], _flake=flake_obj
     )
 
     new_public = in_repo_store.get(generator_shared, "my_value").decode()

pkgs/clan-cli/clan_cli/vars/_types.py

@@ -40,12 +40,15 @@ class StoreBase(ABC):
 
     def get_machine(self, generator: "Generator") -> str:
         """Get machine name from generator, asserting it's not None for now."""
-        if generator.machine is None:
-            if generator.share:
-                return "__shared"
+        if generator.share:
+            return "__shared"
+        if not generator.machines:
             msg = f"Generator '{generator.name}' has no machine associated"
             raise ClanError(msg)
-        return generator.machine
+        if len(generator.machines) != 1:
+            msg = f"Generator '{generator.name}' has {len(generator.machines)} machines, expected exactly 1"
+            raise ClanError(msg)
+        return generator.machines[0]
 
     # get a single fact
     @abstractmethod
@@ -147,7 +150,7 @@ class StoreBase(ABC):
         prev_generator = dataclasses.replace(
             generator,
             share=not generator.share,
-            machine=machine if generator.share else None,
+            machines=[] if not generator.share else [machine],
         )
         if self.exists(prev_generator, var.name):
             changed_files += self.delete(prev_generator, var.name)
@@ -165,12 +168,12 @@ class StoreBase(ABC):
         new_file = self._set(generator, var, value, machine)
         action_str = "Migrated" if is_migration else "Updated"
         log_info: Callable
-        if generator.machine is None:
+        if generator.share:
             log_info = log.info
         else:
             from clan_lib.machines.machines import Machine  # noqa: PLC0415
 
-            machine_obj = Machine(name=generator.machine, flake=self.flake)
+            machine_obj = Machine(name=generator.machines[0], flake=self.flake)
             log_info = machine_obj.info
         if self.is_secret_store:
             log.info(f"{action_str} secret var {generator.name}/{var.name}\n")

pkgs/clan-cli/clan_cli/vars/generator.py

@@ -61,14 +61,22 @@ class Generator:
     migrate_fact: str | None = None
     validation_hash: str | None = None
 
-    machine: str | None = None
+    machines: list[str] = field(default_factory=list)
     _flake: "Flake | None" = None
     _public_store: "StoreBase | None" = None
     _secret_store: "StoreBase | None" = None
 
     @property
     def key(self) -> GeneratorKey:
-        return GeneratorKey(machine=self.machine, name=self.name)
+        if self.share:
+            # must be a shared generator
+            machine = None
+        elif len(self.machines) != 1:
+            msg = f"Shared generator {self.name} must have exactly one machine, but has {len(self.machines)}: {', '.join(self.machines)}"
+            raise ClanError(msg)
+        else:
+            machine = self.machines[0]
+        return GeneratorKey(machine=machine, name=self.name)
 
     def __hash__(self) -> int:
         return hash(self.key)
@@ -143,7 +151,7 @@ class Generator:
         files_selector = "config.clan.core.vars.generators.*.files.*.{secret,deploy,owner,group,mode,neededFor}"
         flake.precache(cls.get_machine_selectors(machine_names))
 
-        generators = []
+        generators: list[Generator] = []
         shared_generators_raw: dict[
             str, tuple[str, dict, dict]
         ] = {}  # name -> (machine_name, gen_data, files_data)
@@ -244,15 +252,27 @@ class Generator:
                     migrate_fact=gen_data.get("migrateFact"),
                     validation_hash=gen_data.get("validationHash"),
                     prompts=prompts,
-                    # only set machine for machine-specific generators
-                    # this is essential for the graph algorithms to work correctly
-                    machine=None if share else machine_name,
+                    # shared generators can have multiple machines, machine-specific have one
+                    machines=[machine_name],
                     _flake=flake,
                     _public_store=pub_store,
                     _secret_store=sec_store,
                 )
 
-                generators.append(generator)
+                if share:
+                    # For shared generators, check if we already created it
+                    existing = next(
+                        (g for g in generators if g.name == gen_name and g.share), None
+                    )
+                    if existing:
+                        # Just append the machine to the existing generator
+                        existing.machines.append(machine_name)
+                    else:
+                        # Add the new shared generator
+                        generators.append(generator)
+                else:
+                    # Always add per-machine generators
+                    generators.append(generator)
 
             # TODO: This should be done in a non-mutable way.
             if include_previous_values:

pkgs/clan-cli/clan_cli/vars/graph_test.py

@@ -49,28 +49,28 @@ def test_required_generators() -> None:
     gen_1 = Generator(
         name="gen_1",
         dependencies=[],
-        machine=machine_name,
+        machines=[machine_name],
         _public_store=public_store,
         _secret_store=secret_store,
     )
     gen_2 = Generator(
         name="gen_2",
         dependencies=[gen_1.key],
-        machine=machine_name,
+        machines=[machine_name],
         _public_store=public_store,
         _secret_store=secret_store,
     )
     gen_2a = Generator(
         name="gen_2a",
         dependencies=[gen_2.key],
-        machine=machine_name,
+        machines=[machine_name],
         _public_store=public_store,
         _secret_store=secret_store,
     )
     gen_2b = Generator(
         name="gen_2b",
         dependencies=[gen_2.key],
-        machine=machine_name,
+        machines=[machine_name],
         _public_store=public_store,
         _secret_store=secret_store,
     )
@@ -118,21 +118,22 @@ def test_shared_generator_invalidates_multiple_machines_dependents() -> None:
     shared_gen = Generator(
         name="shared_gen",
         dependencies=[],
-        machine=None,  # Shared generator
+        share=True,  # Mark as shared generator
+        machines=[machine_1, machine_2],  # Shared across both machines
         _public_store=public_store,
         _secret_store=secret_store,
     )
     gen_1 = Generator(
         name="gen_1",
         dependencies=[shared_gen.key],
-        machine=machine_1,
+        machines=[machine_1],
         _public_store=public_store,
         _secret_store=secret_store,
     )
     gen_2 = Generator(
         name="gen_2",
         dependencies=[shared_gen.key],
-        machine=machine_2,
+        machines=[machine_2],
         _public_store=public_store,
         _secret_store=secret_store,
     )

pkgs/clan-cli/clan_lib/machines/hardware.py

@@ -119,6 +119,9 @@ def run_machine_hardware_info_init(
     if opts.debug:
         cmd += ["--debug"]
 
+    # Add nix options to nixos-anywhere
+    cmd.extend(opts.machine.flake.nix_options or [])
+
     cmd += [target_host.target]
     cmd = nix_shell(
         ["nixos-anywhere"],

pkgs/clan-cli/clan_lib/vars/generate.py

@@ -93,21 +93,21 @@ def _ensure_healthy(
     if generators is None:
         generators = Generator.get_machine_generators([machine.name], machine.flake)
 
-    pub_healtcheck_msg = machine.public_vars_store.health_check(
+    public_health_check_msg = machine.public_vars_store.health_check(
         machine.name,
         generators,
     )
-    sec_healtcheck_msg = machine.secret_vars_store.health_check(
+    secret_health_check_msg = machine.secret_vars_store.health_check(
         machine.name,
         generators,
     )
 
-    if pub_healtcheck_msg or sec_healtcheck_msg:
+    if public_health_check_msg or secret_health_check_msg:
         msg = f"Health check failed for machine {machine.name}:\n"
-        if pub_healtcheck_msg:
-            msg += f"Public vars store: {pub_healtcheck_msg}\n"
-        if sec_healtcheck_msg:
-            msg += f"Secret vars store: {sec_healtcheck_msg}"
+        if public_health_check_msg:
+            msg += f"Public vars store: {public_health_check_msg}\n"
+        if secret_health_check_msg:
+            msg += f"Secret vars store: {secret_health_check_msg}"
         raise ClanError(msg)
 
 
@@ -181,10 +181,10 @@ def run_generators(
     flake = machines[0].flake
 
     def get_generator_machine(generator: Generator) -> Machine:
-        if generator.machine is None:
-            # return first machine if generator is not tied to a specific one
+        if generator.share:
+            # return first machine if generator is shared
             return machines[0]
-        return Machine(name=generator.machine, flake=flake)
+        return Machine(name=generator.machines[0], flake=flake)
 
     # preheat the select cache, to reduce repeated calls during execution
     selectors = []

pkgs/docs-from-code/flake-module.nix

@@ -0,0 +1,71 @@
+{ self, inputs, ... }:
+{
+  perSystem =
+    { pkgs, self', ... }:
+    let
+      # Simply evaluated options (JSON)
+      # { clanCore = «derivation JSON»; clanModules = { ${name} = «derivation JSON» }; }
+      jsonDocs = pkgs.callPackage ./get-module-docs.nix {
+        inherit (self) clanModules;
+        clan-core = self;
+        inherit pkgs;
+      };
+
+      # clan service options
+      clanModulesViaService = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesViaService);
+
+      # Simply evaluated options (JSON)
+      renderOptions =
+        pkgs.runCommand "render-options"
+          {
+            # TODO: ruff does not splice properly in nativeBuildInputs
+            depsBuildBuild = [ pkgs.ruff ];
+            nativeBuildInputs = [
+              pkgs.python3
+              pkgs.mypy
+              self'.packages.clan-cli
+            ];
+          }
+          ''
+            install -D -m755 ${./generate}/__init__.py $out/bin/render-options
+            patchShebangs --build $out/bin/render-options
+
+            ruff format --check --diff $out/bin/render-options
+            ruff check --line-length 88 $out/bin/render-options
+            mypy --strict $out/bin/render-options
+          '';
+
+      module-docs =
+        pkgs.runCommand "rendered"
+          {
+            buildInputs = [
+              pkgs.python3
+              self'.packages.clan-cli
+            ];
+          }
+          ''
+            export CLAN_CORE_PATH=${
+              inputs.nixpkgs.lib.fileset.toSource {
+                root = ../..;
+                fileset = ../../clanModules;
+              }
+            }
+            export CLAN_CORE_DOCS=${jsonDocs.clanCore}/share/doc/nixos/options.json
+
+            # A file that contains the links to all clanModule docs
+            export CLAN_MODULES_VIA_SERVICE=${clanModulesViaService}
+            export CLAN_SERVICE_INTERFACE=${self'.legacyPackages.clan-service-module-interface}/share/doc/nixos/options.json
+            export CLAN_OPTIONS_PATH=${self'.legacyPackages.clan-options}/share/doc/nixos/options.json
+
+            mkdir $out
+
+            # The python script will place mkDocs files in the output directory
+            exec python3 ${renderOptions}/bin/render-options
+          '';
+    in
+    {
+      packages = {
+        inherit module-docs;
+      };
+    };
+}

pkgs/flake-module.nix

@@ -2,12 +2,14 @@
 
 {
   imports = [
-    ./clan-cli/flake-module.nix
-    ./clan-vm-manager/flake-module.nix
-    ./installer/flake-module.nix
-    ./icon-update/flake-module.nix
-    ./clan-core-flake/flake-module.nix
     ./clan-app/flake-module.nix
+    ./clan-cli/flake-module.nix
+    ./clan-core-flake/flake-module.nix
+    ./clan-vm-manager/flake-module.nix
+    ./icon-update/flake-module.nix
+    ./installer/flake-module.nix
+    ./option-search/flake-module.nix
+    ./docs-from-code/flake-module.nix
     ./testing/flake-module.nix
   ];
 

pkgs/option-search/flake-module.nix

@@ -24,7 +24,7 @@
 
       serviceModules = self.clan.modules;
 
-      baseHref = "/options/";
+      baseHref = "/option-search/";
 
       getRoles =
         module:
@@ -118,7 +118,7 @@
                       _file = "docs flake-module";
                       imports = [
                         { _module.args = { inherit clanLib; }; }
-                        (import ../../../lib/modules/inventoryClass/roles-interface.nix {
+                        (import ../../lib/modules/inventoryClass/roles-interface.nix {
                           nestedSettingsOption = mkOption {
                             type = types.raw;
                             description = ''
@@ -201,7 +201,7 @@
       # };
 
       packages = {
-        docs-options =
+        option-search =
           if privateInputs ? nuschtos then
             privateInputs.nuschtos.packages.${pkgs.stdenv.hostPlatform.system}.mkMultiSearch {
               inherit baseHref;