From de48d3447d511b625cce01f51317f6bf36b8d2de Mon Sep 17 00:00:00 2001
From: a-kenji <aks.kenji@protonmail.com>
Date: Tue, 19 Nov 2024 13:44:03 +0100
Subject: [PATCH] clanModules/importer: Init `importer` inventory module

Initialize the `importer` inventory module.
It is a power user module that allows for convenient, flexible,
structured imports for hosts.

It exposes the `extraModules` functionality of the inventory,
without any added configuration.

Closes: #2356
---
 clanModules/flake-module.nix           |  1 +
 clanModules/importer/README.md         | 27 ++++++++++++++++++++++++++
 clanModules/importer/default.nix       |  4 ++++
 clanModules/importer/roles/default.nix |  1 +
 docs/mkdocs.yml                        |  1 +
 5 files changed, 34 insertions(+)
 create mode 100644 clanModules/importer/README.md
 create mode 100644 clanModules/importer/default.nix
 create mode 100644 clanModules/importer/roles/default.nix

diff --git a/clanModules/flake-module.nix b/clanModules/flake-module.nix
index dcee6a103..e6d4064de 100644
--- a/clanModules/flake-module.nix
+++ b/clanModules/flake-module.nix
@@ -13,6 +13,7 @@
     golem-provider = ./golem-provider;
     heisenbridge = ./heisenbridge;
     iwd = ./iwd;
+    importer = ./importer;
     localbackup = ./localbackup;
     localsend = ./localsend;
     matrix-synapse = ./matrix-synapse;
diff --git a/clanModules/importer/README.md b/clanModules/importer/README.md
new file mode 100644
index 000000000..c75039925
--- /dev/null
+++ b/clanModules/importer/README.md
@@ -0,0 +1,27 @@
+---
+description = "Convenient, structured module imports for hosts."
+categories = ["Utility"]
+features = [ "inventory" ]
+---
+The importer module allows users to configure importing modules in a flexible and structured way.
+
+It exposes the `extraModules` functionality of the inventory, without any added configuration.
+
+## Usage:
+
+```nix
+inventory.services = {
+  importer.base = {
+    roles.default.tags = [ "all" ];
+    roles.default.extraModules = [ "modules/base.nix" ];
+  };
+  importer.zone1 = {
+    roles.default.tags = [ "zone1" ];
+    roles.default.extraModules = [ "modules/zone1.nix" ];
+  };
+};
+```
+
+This will import the module `modules/base.nix` to all machines that have the `all` tag,
+which by default is every machine managed by the clan.
+And also import for all machines tagged with `zone1` the module at `modules/zone1.nix`.
diff --git a/clanModules/importer/default.nix b/clanModules/importer/default.nix
new file mode 100644
index 000000000..7ee1167ac
--- /dev/null
+++ b/clanModules/importer/default.nix
@@ -0,0 +1,4 @@
+# Dont import this file
+# It is only here for backwards compatibility.
+# Dont author new modules with this file.
+{ }
diff --git a/clanModules/importer/roles/default.nix b/clanModules/importer/roles/default.nix
new file mode 100644
index 000000000..ffcd4415b
--- /dev/null
+++ b/clanModules/importer/roles/default.nix
@@ -0,0 +1 @@
+{ }
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index ed86b6576..cd5f72e50 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -79,6 +79,7 @@ nav:
           - reference/clanModules/heisenbridge.md
           - reference/clanModules/index.md
           - reference/clanModules/iwd.md
+          - reference/clanModules/importer.md
           - reference/clanModules/localbackup.md
           - reference/clanModules/localsend.md
           - reference/clanModules/machine-id.md