feat: cleanup and documentation

Signed-off-by: Brian McGee <[email protected]>

README.md

@@ -0,0 +1,171 @@
+<h1 align="center"> 
+  CBus - Clustered DBus
+  <br>
+  <br>
+</h1>
+
+**Status: highly experimental**
+
+# Motivation
+
+I've been thinking about a clustered `systemctl` for a while now, and when I started digging into it recently I
+eventually ended up looking closely at [DBus](https://www.freedesktop.org/wiki/Software/dbus/).
+
+What I *want to achieve* is remotely monitor and manage multiple machines.
+
+I think DBus provides the underlying mechanism for this in the form of:
+
+-   Properties
+-   Methods
+-   Signals
+
+[Systemd](https://www.freedesktop.org/wiki/Software/systemd/dbus/) integrates deeply with DBus, registering an object
+for every unit, so right out of the gate that's immensely useful without looking at what other buses/objects you might
+find on a Linux system.
+
+This is what inspired me to integrate DBus with NATS.
+
+## Development
+
+### Requirements
+
+You must be familiar with and have the following installed:
+
+-   [Direnv](https://direnv.net)
+-   [Nix](https://nixos.org)
+
+### Quick Start
+
+After cloning the repository cd into the root directory and run:
+
+```terminal
+direnv allow
+```
+
+You will be asked to accept config for some additional substituters to which you should select yes.
+
+Once the dev shell has finished initialising you can see the available commands by typing `menu`:
+
+```terminal
+❯ menu
+
+[[general commands]]
+
+  flake-linter
+  menu             - prints this menu
+
+[development]
+
+  dev              - run local dev services
+  dev-init         - re-initialise data directory
+  gomod2nix        - Convert applications using Go modules -> Nix
+  run-test-machine - run a test vm
+
+[docs]
+
+  gifs             - Generate all gifs used in docs
+  vhs              - A tool for generating terminal GIFs with code
+
+[formatting]
+
+  fmt              - format the repo
+
+[nats]
+
+  nats
+  nsc
+```
+
+To start the local dev services type `dev`.
+
+![](./docs/assets/dev.gif)
+
+You must wait until `nats-setup` has completed successfully and `nats-server` is in the running state.
+
+After a short while the test machines (vms) should start up, and you can try retrieving some properties and invoking
+some methods.
+
+#### Invoke a method on all machines
+
+```terminal
+❯ nix run .# -- invoke org.freedesktop.systemd1 /org/freedesktop/systemd1 GetDefaultTarget
+NKey: UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7
+
+["default.target"]
+
+NKey: UAILZJS66U24VALTH2D6OWVD5JTS3IDFMKOICJSOX7CHNAF3AXFVWIFX
+
+["default.target"]
+
+NKey: UAMLBE4LIDYXH6FO5LW6CPLEBZJ23I2OT3TPZYIJPQY5HJ46X3BU7UJK
+
+["default.target"]
+```
+
+#### Get a property on all machines
+
+```terminal
+❯ nix run .# -- get org.freedesktop.systemd1 /org/freedesktop/systemd1/unit/basic_2etarget ActiveState
+NKey: UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7
+Signature: s
+
+"active"
+
+NKey: UAMLBE4LIDYXH6FO5LW6CPLEBZJ23I2OT3TPZYIJPQY5HJ46X3BU7UJK
+Signature: s
+
+"active"
+
+NKey: UAILZJS66U24VALTH2D6OWVD5JTS3IDFMKOICJSOX7CHNAF3AXFVWIFX
+Signature: s
+
+"active"
+```
+
+#### Get a property on a list of machines by NATS NKey
+
+```terminal
+❯ nix run .# -- get org.freedesktop.systemd1 /org/freedesktop/systemd1/unit/basic_2etarget ActiveState --nkeys UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7,UAMLBE4LIDYXH6FO5LW6CPLEBZJ23I2OT3TPZYIJPQY5HJ46X3BU7UJK
+Signature: s
+NKey: UAMLBE4LIDYXH6FO5LW6CPLEBZJ23I2OT3TPZYIJPQY5HJ46X3BU7UJK
+
+"active"
+
+NKey: UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7
+Signature: s
+
+"active"
+```
+
+#### Listen for all signals from each machine
+
+```terminal
+❯ nats --context TestAdmin sub "dbus.signals.>"
+12:14:06 Subscribing on dbus.signals.> 
+[#1] Received on "dbus.signals.UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7._1_1.org.freedesktop.systemd1.unit.nscd_2eservice"
+Interface: org.freedesktop.DBus.Properties
+Member: PropertiesChanged
+NKey: UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7
+Path: /org/freedesktop/systemd1/unit/nscd_2eservice
+Sender: :1.1
+
+["org.freedesktop.systemd1.Service",{"CleanResult":{},"ControlPID":{},"ExecMainCode":{},"ExecMainExitTimestamp":{},"ExecMainExitTimestampMonotonic":{},"ExecMainPID":{},"ExecMainStartTimestamp":{},"ExecMainStartTimestampMonotonic":{},"ExecMainStatus":{},"GID":{},"MainPID":{},"NRestarts":{},"NotifyAccess":{},"ReloadResult":{},"Result":{},"StatusErrno":{},"StatusText":{},"UID":{}},["ExecCondition","ExecConditionEx","ExecStartPre","ExecStartPreEx","ExecStart","ExecStartEx","ExecStartPost","ExecStartPostEx","ExecReload","ExecReloadEx","ExecStop","ExecStopEx","ExecStopPost","ExecStopPostEx"]]
+
+
+[#2] Received on "dbus.signals.UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7._1_1.org.freedesktop.systemd1.unit.nscd_2eservice"
+Interface: org.freedesktop.DBus.Properties
+Member: PropertiesChanged
+NKey: UBQUIKYGFC7CH5XMF52P2NN4ESI4XTXGAKT3WTG3XGU3352DMHGZQAX7
+Path: /org/freedesktop/systemd1/unit/nscd_2eservice
+Sender: :1.1
+
+["org.freedesktop.systemd1.Unit",{"ActivationDetails":{},"ActiveEnterTimestamp":{},"ActiveEnterTimestampMonotonic":{},"ActiveExitTimestamp":{},"ActiveExitTimestampMonotonic":{},"ActiveState":{},"AssertResult":{},"AssertTimestamp":{},"AssertTimestampMonotonic":{},"ConditionResult":{},"ConditionTimestamp":{},"ConditionTimestampMonotonic":{},"FreezerState":{},"InactiveEnterTimestamp":{},"InactiveEnterTimestampMonotonic":{},"InactiveExitTimestamp":{},"InactiveExitTimestampMonotonic":{},"InvocationID":{},"Job":{},"StateChangeTimestamp":{},"StateChangeTimestampMonotonic":{},"SubState":{}},["Conditions","Asserts"]]
+```
+
+## License
+
+This software is provided free under the [MIT Licence](https://opensource.org/licenses/MIT).
+
+## Contact
+
+There are a few different ways to reach me, all of which are listed on my [website](https://bmcgee.ie/).

docs/vhs/dev.tape

@@ -0,0 +1,23 @@
+Set Shell zsh
+Require dev
+
+Set FontSize 14
+
+Set Width 1440
+Set Height 800
+
+Sleep 1s
+Type "dev"
+Sleep 1s
+Enter
+
+Sleep 5s
+Down
+Sleep 5s
+Down
+
+Sleep 20s
+Ctrl+c
+Sleep 1s
+Enter
+Sleep 1s

nix/default.nix

@@ -2,6 +2,7 @@
   imports = [
     inputs.flake-root.flakeModule
     ./checks.nix
+    ./docs.nix
     ./treefmt.nix
     ./nixpkgs.nix
     ./nixos

nix/dev/default.nix

@@ -1,6 +1,5 @@
 {...}: {
   imports = [
-    ./binary-cache
     ./nats
     ./vms
   ];

nix/dev/vms/default.nix

@@ -69,9 +69,6 @@
       dev.settings.processes = let
         mkAgentProcess = id: {
           command = "run-test-machine ${builtins.toString id}";
-          depends_on = {
-            binary-cache.condition = "process_healthy";
-          };
         };
         configs =
           map

nix/docs.nix

@@ -0,0 +1,27 @@
+{
+  perSystem = {pkgs, ...}: {
+    config.devshells.default = {
+      commands = let
+        category = "docs";
+      in [
+        {
+          inherit category;
+          package = pkgs.vhs;
+        }
+        {
+          inherit category;
+          help = "Generate all gifs used in docs";
+          package = pkgs.writeShellApplication {
+            name = "gifs";
+            runtimeInputs = [pkgs.vhs];
+            text = ''
+              for tape in "$PRJ_ROOT"/docs/vhs/*; do
+                vhs "$tape" -o "$PRJ_ROOT/docs/assets/$(basename "$tape" .tape).gif"
+              done
+            '';
+          };
+        }
+      ];
+    };
+  };
+}