From f7e8660527b7e669a65e759f32832a6d05155db8 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:11:36 -0500
Subject: [PATCH 01/15] Add mkcert and hostctl instrumentation

---
 devshell.toml       | 20 +++++++++++++++++
 instrumentation.nix | 53 +++++++++++++++++++++++++++++++++++++++++++++
 options.nix         | 52 ++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 121 insertions(+), 4 deletions(-)
 create mode 100644 instrumentation.nix

diff --git a/devshell.toml b/devshell.toml
index da84d794..140d1785 100644
--- a/devshell.toml
+++ b/devshell.toml
@@ -16,6 +16,18 @@ packages = [
 #
 # motd = ""
 
+# This setting helps to add a project's shared *development* root CA
+# to host's local trust stores by instrumenting the mkcert third party tool.
+# Defining this section also adds `mkcert` to the available packages.
+# Set to the path where mkcert-generated CAROOT files are expected to exist
+#
+# NOTES:
+# - be careful to only put *development* certificates under version control
+# - create those files with the devshell generated *-install-CA command
+# - optionally put this path under .gitignore, if you want users to
+#   generate certificates themselves on first clone (using *-install-CA)
+# dev-ca-path = "./dev-ca"
+
 # Use this section to set environment variables to have in the environment.
 #
 # NOTE: all the values are escaped
@@ -52,3 +64,11 @@ package = "nixpkgs-fmt"
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+
+# These settings help to manage local DNS overrides via
+# instrumentation of the hostcl third party tool.
+# Defining this section also adds `hostctl` to the available packages.
+[static-dns]
+test.domain.local = 172.0.0.1
+shared.domain.link-local = 169.254.0.5
+
diff --git a/instrumentation.nix b/instrumentation.nix
new file mode 100644
index 00000000..7fdac7f3
--- /dev/null
+++ b/instrumentation.nix
@@ -0,0 +1,53 @@
+{ lib, pkgs, config }:
+let
+  inherit (config)
+    name
+    dev-ca-path
+    static-dns
+    ;
+  installProjectCA = {
+    name = "${name}-install-ca";
+    help = "install dev CA";
+    package = pkgs.mkcert;
+    command = ''
+      echo "$(tput bold)Installing the project's dev CA into local trust stores via mkcert command ...$(tput sgr0)"
+      export CAROOT=${dev-ca-path}
+      ${pkgs.mkcert}/bin/mkcert -install
+      '';
+  };
+  uninstallProjectCA = {
+    name = "${name}-uninstall-ca";
+    help = "uninstall dev CA";
+    package = pkgs.mkcert;
+    command = ''
+      echo "$(tput bold)Purging the project's dev CA from local trust stores via mkcert command ...$(tput sgr0)"
+      export CAROOT=${dev-ca-path}
+      ${pkgs.mkcert}/bin/mkcert -uninstall
+      '';
+  };
+
+  etcHosts = writeText "${name}-etchosts" concatStringsSep "\n" servicenames;
+  # since this temporarily modifies /etc/hosts, use of sudo can't be avoided
+  fqdnsActivate = {
+    name = "${name}-dns-activate";
+    help = "activate pre-configured static dns";
+    package = pkgs.hostctl;
+    command = ''
+      echo "$(tput bold)Installing ${name}'s static local DNS resolution via hostctl command ...$(tput sgr0)"
+      sudo ${pkgs.hostctl}/bin/hostctl add ${name} --from ${etcHosts}
+      '';
+  };
+  fqdnsDeactivate = {
+    name = "${name}-dns-deactivate";
+    help = "deactivate pre-configured static dns";
+    package = pkgs.hostctl;
+    command = ''
+      echo "$(tput bold)Purging ${name}'s static local DNS resolution via hostctl command ...$(tput sgr0)"
+      sudo ${pkgs.hostctl}/bin/hostctl remove ${name}
+      '';
+  };
+in
+if static-dns == null || static-dns == "" then []
+else [ fqdnsActivate fqdnsDeactivate ] ++
+if dev-ca-path == null || dev-ca-path == "" then []
+else [ installProjectCA uninstallProjectCA ];
diff --git a/options.nix b/options.nix
index 356ca847..78a00a80 100644
--- a/options.nix
+++ b/options.nix
@@ -1,6 +1,8 @@
 { lib, pkgs, config, ... }:
 with lib;
 let
+  instrumentedCommands = (import ./instrumentation.nix) {lib, pkgs, config};
+
   resolveKey = key:
     let
       attrs = builtins.filter builtins.isString (builtins.split "\\." key);
@@ -115,6 +117,27 @@ in
       '';
     };
 
+    # exclusively consumed by command instrumentation
+    dev-ca-path = mkOption {
+      type = types.str;
+      default = "";
+      description = ''
+        Path to a development CA.
+
+        Users can load/unload this dev CA easily and cleanly into their local
+        trust stores via a wrapper around mkcert third party tool so that browsers
+        and other tools would accept issued certificates under this CA as valid.
+
+        Use cases:
+         - Ship static dev certificates under version control and make them trusted
+           on user machines: add the rootCA under version control alongside the
+           your dev certificates.
+         - Provide users with easy and reliable CA bootstrapping through the mkcert
+           command: exempt this path from version control via .gitignore and have
+           users  easily and reliably bootstrap a dev CA infrastructure on first use.
+      '';
+    };
+
     commands = mkOption {
       type = types.listOf (types.submodule { options = commandOptions; });
       default = [ ];
@@ -185,6 +208,23 @@ in
       '';
     };
 
+    # exclusively consumed by command instrumentation
+    static-dns = mkOption {
+      type = types.attrs;
+      default = { };
+      description = ''
+        A list of static DNS entries, for which to enable instrumentation.
+
+        Users can enable/disable listed static DNS easily and cleanly
+        via a wrapper around the hostctl third party tool.
+      '';
+      example = {
+        "test.domain.local" = "172.0.0.1";
+        "shared.domain.link-local" = "169.254.0.5";
+      };
+    };
+
+
   };
 
   config = {
@@ -195,14 +235,18 @@ in
         command = ''
           echo "[commands]"
           cat <<'DEVSHELL_MENU'
-          ${commandsToMenu config.commands}
+          ${commandsToMenu (config.commands ++ instrumentedCommands)}
           DEVSHELL_MENU
         '';
       }
-    ];
+    ] ++ instrumentedCommands;
 
     packages =
-      builtins.filter (x: x != null)
-        (map (x: x.package) config.commands);
+      lib.unique (
+        builtins.filter (x: x != null)
+          (map (x: x.package)
+            (config.commands ++ instrumentedCommands)
+          )
+        );
   };
 }

From 1cd0da89e64cb4c6d1472d7d61399cf1bd164e5d Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:15:19 -0500
Subject: [PATCH 02/15] Docs: Add mkcert and hostctl instrumentation (skaffold)

---
 docs/devshell.toml    | 19 +++++++++++++++++++
 docs/devshell.toml.md | 23 +++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/docs/devshell.toml b/docs/devshell.toml
index da84d794..80405178 100644
--- a/docs/devshell.toml
+++ b/docs/devshell.toml
@@ -16,6 +16,18 @@ packages = [
 #
 # motd = ""
 
+# This setting helps to add a project's shared *development* root CA
+# to host's local trust stores by instrumenting the mkcert third party tool.
+# Defining this section also adds `mkcert` to the available packages.
+# Set to the path where mkcert-generated CAROOT files are expected to exist
+#
+# NOTES:
+# - be careful to only put *development* certificates under version control
+# - create those files with the devshell generated *-install-CA command
+# - optionally put this path under .gitignore, if you want users to
+#   generate certificates themselves on first clone (using *-install-CA)
+# dev-ca-path = "./dev-ca"
+
 # Use this section to set environment variables to have in the environment.
 #
 # NOTE: all the values are escaped
@@ -52,3 +64,10 @@ package = "nixpkgs-fmt"
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+
+# These settings help to manage local DNS overrides via
+# instrumentation of the hostcl third party tool.
+# Defining this section also adds `hostctl` to the available packages.
+[static-dns]
+test.domain.local = 172.0.0.1
+shared.domain.link-local = 169.254.0.5
diff --git a/docs/devshell.toml.md b/docs/devshell.toml.md
index 5e7cf2d0..44acfb5f 100644
--- a/docs/devshell.toml.md
+++ b/docs/devshell.toml.md
@@ -24,6 +24,18 @@ packages = [
 #
 # motd = ""
 
+# This setting helps to add a project's shared *development* root CA
+# to host's local trust stores by instrumenting the mkcert third party tool.
+# Defining this section also adds `mkcert` to the available packages.
+# Set to the path where mkcert-generated CAROOT files are expected to exist
+#
+# NOTES:
+# - be careful to only put *development* certificates under version control
+# - create those files with the devshell generated *-install-CA command
+# - optionally put this path under .gitignore, if you want users to
+#   generate certificates themselves on first clone (using *-install-CA)
+# dev-ca-path = "./dev-ca"
+
 # Use this section to set environment variables to have in the environment.
 #
 # NOTE: all the values are escaped
@@ -60,6 +72,13 @@ package = "nixpkgs-fmt"
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+
+# These settings help to manage local DNS overrides via
+# instrumentation of the hostcl third party tool.
+# Defining this section also adds `hostctl` to the available packages.
+[static-dns]
+test.domain.local = 172.0.0.1
+shared.domain.link-local = 169.254.0.5
 ```
 
 ## Schema
@@ -83,6 +102,8 @@ The name field is optional and defaults to `devshell`.
 
 ### The `motd` field
 
+### The `dev-ca-path` field
+
 ### The `env` section
 
 ### The `bash.extra` field
@@ -96,3 +117,5 @@ The name field is optional and defaults to `devshell`.
 * `name`:
 * `package`:
 
+### The `dns` section
+

From 01760d1747b2f1b2ed9a74c86ed9f3a8d8491ccd Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:21:42 -0500
Subject: [PATCH 03/15] Go: Add mkcert and hostctl instrumentation

---
 go/devshell/config.go | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/go/devshell/config.go b/go/devshell/config.go
index d7136769..3959e0d4 100644
--- a/go/devshell/config.go
+++ b/go/devshell/config.go
@@ -22,12 +22,14 @@ type configCommand struct {
 }
 
 type config struct {
-	Name     string                 `toml:"name"`
-	Packages []string               `toml:"packages"`
-	Motd     *string                `toml:"motd"`
-	Env      map[string]interface{} `toml:"env"`
-	Bash     configBash             `toml:"bash,omitempty"`
-	Commands []configCommand        `toml:"commands"`
+	Name      string                 `toml:"name"`
+	Packages  []string               `toml:"packages"`
+	Motd      *string                `toml:"motd"`
+	DevCaPath *string                `toml:"dev-ca-path,omitempty"`
+	Env       map[string]interface{} `toml:"env"`
+	Bash      configBash             `toml:"bash,omitempty"`
+	Commands  []configCommand        `toml:"commands"`
+	StaticDNS map[string]interface{} `toml:"static-dns,omitempty"`
 }
 
 func configLoad(path string) (*config, error) {

From a013f1d1aabeeb41bb58e52e2d2f5265c5555460 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:37:08 -0500
Subject: [PATCH 04/15] Various fixups

---
 devshell.toml                                         | 4 ++--
 docs/devshell.toml                                    | 4 ++--
 docs/devshell.toml.md                                 | 4 ++--
 instrumentation.nix => mkDevShell/instrumentation.nix | 8 ++++----
 4 files changed, 10 insertions(+), 10 deletions(-)
 rename instrumentation.nix => mkDevShell/instrumentation.nix (89%)

diff --git a/devshell.toml b/devshell.toml
index b560f8f9..f1207baf 100644
--- a/devshell.toml
+++ b/devshell.toml
@@ -69,6 +69,6 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = 172.0.0.1
-shared.domain.link-local = 169.254.0.5
+test.domain.local = "172.0.0.1"
+shared.domain.link-local = "169.254.0.5"
 
diff --git a/docs/devshell.toml b/docs/devshell.toml
index 80405178..5d5a60cc 100644
--- a/docs/devshell.toml
+++ b/docs/devshell.toml
@@ -69,5 +69,5 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = 172.0.0.1
-shared.domain.link-local = 169.254.0.5
+test.domain.local = "172.0.0.1"
+shared.domain.link-local = "169.254.0.5"
diff --git a/docs/devshell.toml.md b/docs/devshell.toml.md
index 44acfb5f..60624b09 100644
--- a/docs/devshell.toml.md
+++ b/docs/devshell.toml.md
@@ -77,8 +77,8 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = 172.0.0.1
-shared.domain.link-local = 169.254.0.5
+test.domain.local = "172.0.0.1"
+shared.domain.link-local = "169.254.0.5"
 ```
 
 ## Schema
diff --git a/instrumentation.nix b/mkDevShell/instrumentation.nix
similarity index 89%
rename from instrumentation.nix
rename to mkDevShell/instrumentation.nix
index 7fdac7f3..bcbb6402 100644
--- a/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -47,7 +47,7 @@ let
       '';
   };
 in
-if static-dns == null || static-dns == "" then []
-else [ fqdnsActivate fqdnsDeactivate ] ++
-if dev-ca-path == null || dev-ca-path == "" then []
-else [ installProjectCA uninstallProjectCA ];
+(if static-dns == null || static-dns == "" then []
+else [ fqdnsActivate fqdnsDeactivate ]) ++
+(if dev-ca-path == null || dev-ca-path == "" then []
+else [ installProjectCA uninstallProjectCA ])

From 22260f5a326fdc1facf0961c82027cfd29ce073d Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:41:34 -0500
Subject: [PATCH 05/15] Another Fixup

---
 mkDevShell/options.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index 2f7c871b..3b290239 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -1,7 +1,7 @@
 { lib, pkgs, config, ... }:
 with lib;
 let
-  instrumentedCommands = (import ./instrumentation.nix) {lib, pkgs, config};
+  instrumentedCommands = import ./instrumentation.nix { inherit lib pkgs config; };
 
   resolveKey = key:
     let

From e6b981697230461ea64f5a405df4f6fdb7d9b54a Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:42:19 -0500
Subject: [PATCH 06/15] Fixup 3

---
 mkDevShell/options.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index 3b290239..5203a0c4 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -236,7 +236,7 @@ in
           DEVSHELL_MENU
         '';
       }
-    ] ++ instrumentedCommands;
+    ];
 
     packages =
       lib.unique (

From 7f4c6f57b213816cd9680b8ed7f9669023f0f671 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Wed, 7 Oct 2020 17:43:39 -0500
Subject: [PATCH 07/15] Fixup 4

---
 docs/devshell.toml.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/devshell.toml.md b/docs/devshell.toml.md
index 60624b09..4d8c469f 100644
--- a/docs/devshell.toml.md
+++ b/docs/devshell.toml.md
@@ -117,5 +117,5 @@ The name field is optional and defaults to `devshell`.
 * `name`:
 * `package`:
 
-### The `dns` section
+### The `static-dns` section
 

From 7164929875b2b14ed9930854ccefddb632605b3a Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:17:26 -0500
Subject: [PATCH 08/15] Fixup 5

---
 mkDevShell/instrumentation.nix | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/mkDevShell/instrumentation.nix b/mkDevShell/instrumentation.nix
index bcbb6402..00804042 100644
--- a/mkDevShell/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -26,7 +26,9 @@ let
       '';
   };
 
-  etcHosts = writeText "${name}-etchosts" concatStringsSep "\n" servicenames;
+  etcHosts = pkgs.writeText "${name}-etchosts"
+    (lib.concatStringsSep "\n"
+      (lib.mapAttrsToList (name: value: value + " " + name) static-dns));
   # since this temporarily modifies /etc/hosts, use of sudo can't be avoided
   fqdnsActivate = {
     name = "${name}-dns-activate";

From d02166758b116ca46a4b1a807b212f0387434a81 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:17:34 -0500
Subject: [PATCH 09/15] Temporarily add hostctl overlay
 (NixOS/nixpkgs/pull/100048)

---
 hostctl/default.nix | 41 +++++++++++++++++++++++++++++++++++++++++
 overlay.nix         |  1 +
 2 files changed, 42 insertions(+)
 create mode 100644 hostctl/default.nix

diff --git a/hostctl/default.nix b/hostctl/default.nix
new file mode 100644
index 00000000..b78ec9b1
--- /dev/null
+++ b/hostctl/default.nix
@@ -0,0 +1,41 @@
+{ buildGoModule, fetchFromGitHub, lib, installShellFiles }:
+
+buildGoModule rec {
+  pname = "hostctl";
+  version = "1.0.14";
+
+  src = fetchFromGitHub {
+    owner = "guumaster";
+    repo = pname;
+    rev = "v${version}";
+    sha256 = "02bjii97l4fy43v2rb93m9b0ad8y6mjvbvp4sz6a5n0w9dm1z1q9";
+  };
+
+  vendorSha256 = "1lqk3cda0frqp2vwkqa4b3xkdw814wgkbr7g9r2mwxn85fpdcq5c";
+
+  doCheck = false;
+  buildFlagsArray = [ "-ldflags=-s -w -X github.com/guumaster/hostctl/cmd/hostctl/actions.version=${version}" ];
+
+  nativeBuildInputs = [ installShellFiles ];
+  postInstall = ''
+    $out/bin/hostctl completion bash > hostctl.bash
+    $out/bin/hostctl completion zsh > hostctl.zsh
+    installShellCompletion hostctl.{bash,zsh}
+    # replace above by following once merged https://github.com/NixOS/nixpkgs/pull/83630
+    # installShellCompletion --cmd hostctl \
+    #   --bash <($out/bin/hostctl completion bash) \
+    #   --zsh <($out/bin/hostctl completion zsh)
+  '';
+
+  meta = with lib; {
+    description = "Your dev tool to manage /etc/hosts like a pro!";
+    longDescription = ''
+      This tool gives you more control over the use of your hosts file.
+      You can have multiple profiles and switch them on/off as you need.
+    '';
+    homepage = "https://guumaster.github.io/hostctl/";
+    license = licenses.mit;
+    maintainers = with maintainers; [ blaggacao ];
+  };
+}
+
diff --git a/overlay.nix b/overlay.nix
index d2770bae..41dc3148 100644
--- a/overlay.nix
+++ b/overlay.nix
@@ -2,4 +2,5 @@ final: prev:
 {
   devshell = prev.callPackage ./devshell { };
   mkDevShell = prev.callPackage ./mkDevShell { };
+  hostctl = prev.callPackage ./hostctl { };
 }

From 620d4d09baf7ae584c5c03bed54663b44acb32bb Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:27:01 -0500
Subject: [PATCH 10/15] fmt

---
 hostctl/default.nix            |  1 -
 mkDevShell/instrumentation.nix | 23 ++++++++++++++---------
 mkDevShell/options.nix         | 11 +++++++----
 3 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/hostctl/default.nix b/hostctl/default.nix
index b78ec9b1..2ace1db2 100644
--- a/hostctl/default.nix
+++ b/hostctl/default.nix
@@ -38,4 +38,3 @@ buildGoModule rec {
     maintainers = with maintainers; [ blaggacao ];
   };
 }
-
diff --git a/mkDevShell/instrumentation.nix b/mkDevShell/instrumentation.nix
index 00804042..79cdb466 100644
--- a/mkDevShell/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -13,7 +13,7 @@ let
       echo "$(tput bold)Installing the project's dev CA into local trust stores via mkcert command ...$(tput sgr0)"
       export CAROOT=${dev-ca-path}
       ${pkgs.mkcert}/bin/mkcert -install
-      '';
+    '';
   };
   uninstallProjectCA = {
     name = "${name}-uninstall-ca";
@@ -23,12 +23,13 @@ let
       echo "$(tput bold)Purging the project's dev CA from local trust stores via mkcert command ...$(tput sgr0)"
       export CAROOT=${dev-ca-path}
       ${pkgs.mkcert}/bin/mkcert -uninstall
-      '';
+    '';
   };
 
   etcHosts = pkgs.writeText "${name}-etchosts"
     (lib.concatStringsSep "\n"
-      (lib.mapAttrsToList (name: value: value + " " + name) static-dns));
+      (lib.mapAttrsToList (name: value: value + " " + name) static-dns)
+    );
   # since this temporarily modifies /etc/hosts, use of sudo can't be avoided
   fqdnsActivate = {
     name = "${name}-dns-activate";
@@ -37,7 +38,7 @@ let
     command = ''
       echo "$(tput bold)Installing ${name}'s static local DNS resolution via hostctl command ...$(tput sgr0)"
       sudo ${pkgs.hostctl}/bin/hostctl add ${name} --from ${etcHosts}
-      '';
+    '';
   };
   fqdnsDeactivate = {
     name = "${name}-dns-deactivate";
@@ -46,10 +47,14 @@ let
     command = ''
       echo "$(tput bold)Purging ${name}'s static local DNS resolution via hostctl command ...$(tput sgr0)"
       sudo ${pkgs.hostctl}/bin/hostctl remove ${name}
-      '';
+    '';
   };
 in
-(if static-dns == null || static-dns == "" then []
-else [ fqdnsActivate fqdnsDeactivate ]) ++
-(if dev-ca-path == null || dev-ca-path == "" then []
-else [ installProjectCA uninstallProjectCA ])
+(
+  if static-dns == null || static-dns == "" then [ ]
+  else [ fqdnsActivate fqdnsDeactivate ]
+) ++
+(
+  if dev-ca-path == null || dev-ca-path == "" then [ ]
+  else [ installProjectCA uninstallProjectCA ]
+)
diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index 5203a0c4..42c8c4a5 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -240,10 +240,13 @@ in
 
     packages =
       lib.unique (
-        builtins.filter (x: x != null)
-          (map (x: x.package)
-            (config.commands ++ instrumentedCommands)
+        builtins.filter
+          (x: x != null)
+          (
+            map
+              (x: x.package)
+              (config.commands ++ instrumentedCommands)
           )
-        );
+      );
   };
 }

From 0562253003fc7a97109b988addac6ef76319f352 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:40:38 -0500
Subject: [PATCH 11/15] Shorten intrumented cmd names (align with #23)

---
 mkDevShell/instrumentation.nix | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/mkDevShell/instrumentation.nix b/mkDevShell/instrumentation.nix
index 79cdb466..ab426f8d 100644
--- a/mkDevShell/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -6,7 +6,7 @@ let
     static-dns
     ;
   installProjectCA = {
-    name = "${name}-install-ca";
+    name = "install-ca";
     help = "install dev CA";
     package = pkgs.mkcert;
     command = ''
@@ -16,7 +16,7 @@ let
     '';
   };
   uninstallProjectCA = {
-    name = "${name}-uninstall-ca";
+    name = "uninstall-ca";
     help = "uninstall dev CA";
     package = pkgs.mkcert;
     command = ''
@@ -32,7 +32,7 @@ let
     );
   # since this temporarily modifies /etc/hosts, use of sudo can't be avoided
   fqdnsActivate = {
-    name = "${name}-dns-activate";
+    name = "dns-activate";
     help = "activate pre-configured static dns";
     package = pkgs.hostctl;
     command = ''
@@ -41,7 +41,7 @@ let
     '';
   };
   fqdnsDeactivate = {
-    name = "${name}-dns-deactivate";
+    name = "dns-deactivate";
     help = "deactivate pre-configured static dns";
     package = pkgs.hostctl;
     command = ''

From 688dd8cddbe3575bc4a071b7ed355021c6ee632c Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:47:26 -0500
Subject: [PATCH 12/15] Fixup 6

---
 devshell.toml          | 4 ++--
 docs/devshell.toml     | 4 ++--
 docs/devshell.toml.md  | 4 ++--
 mkDevShell/options.nix | 2 +-
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/devshell.toml b/devshell.toml
index f1207baf..040a9972 100644
--- a/devshell.toml
+++ b/devshell.toml
@@ -69,6 +69,6 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = "172.0.0.1"
-shared.domain.link-local = "169.254.0.5"
+"test.domain.local" = "172.0.0.1"
+"shared.domain.link-local" = "169.254.0.5"
 
diff --git a/docs/devshell.toml b/docs/devshell.toml
index 5d5a60cc..5685445e 100644
--- a/docs/devshell.toml
+++ b/docs/devshell.toml
@@ -69,5 +69,5 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = "172.0.0.1"
-shared.domain.link-local = "169.254.0.5"
+"test.domain.local" = "172.0.0.1"
+"shared.domain.link-local" = "169.254.0.5"
diff --git a/docs/devshell.toml.md b/docs/devshell.toml.md
index 4d8c469f..e98e4a6d 100644
--- a/docs/devshell.toml.md
+++ b/docs/devshell.toml.md
@@ -77,8 +77,8 @@ package = "gitAndTools.hub"
 # instrumentation of the hostcl third party tool.
 # Defining this section also adds `hostctl` to the available packages.
 [static-dns]
-test.domain.local = "172.0.0.1"
-shared.domain.link-local = "169.254.0.5"
+"test.domain.local" = "172.0.0.1"
+"shared.domain.link-local" = "169.254.0.5"
 ```
 
 ## Schema
diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index 42c8c4a5..05e25017 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -236,7 +236,7 @@ in
           DEVSHELL_MENU
         '';
       }
-    ];
+    ] ++ instrumentedCommands;
 
     packages =
       lib.unique (

From 5cf1f2c33aea868b7c9917d481fd6b8fe53b1aea Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:49:18 -0500
Subject: [PATCH 13/15] Enable dev-ca generation for testing

---
 .gitignore    | 3 +++
 devshell.toml | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 00000000..b32f47a4
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+# mimick use case where users are expected to boostrap their dev ca
+# this is also better for testing devhsell ca bootstrapping
+dev-ca
diff --git a/devshell.toml b/devshell.toml
index 040a9972..0c03b0dc 100644
--- a/devshell.toml
+++ b/devshell.toml
@@ -26,7 +26,7 @@ packages = [
 # - create those files with the devshell generated *-install-CA command
 # - optionally put this path under .gitignore, if you want users to
 #   generate certificates themselves on first clone (using *-install-CA)
-# dev-ca-path = "./dev-ca"
+dev-ca-path = "./dev-ca"
 
 # Use this section to set environment variables to have in the environment.
 #

From 0cc0e661f2b5a643a3a2517acc243fa7797ab6ae Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 15:54:04 -0500
Subject: [PATCH 14/15] Fine Tuning

---
 mkDevShell/instrumentation.nix | 8 ++++----
 mkDevShell/options.nix         | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/mkDevShell/instrumentation.nix b/mkDevShell/instrumentation.nix
index ab426f8d..dfa4b34d 100644
--- a/mkDevShell/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -6,21 +6,21 @@ let
     static-dns
     ;
   installProjectCA = {
-    name = "install-ca";
+    name = "ca-install";
     help = "install dev CA";
     package = pkgs.mkcert;
     command = ''
-      echo "$(tput bold)Installing the project's dev CA into local trust stores via mkcert command ...$(tput sgr0)"
+      echo "$(tput bold)Installing the ${name}'s dev CA into local trust stores via mkcert command ...$(tput sgr0)"
       export CAROOT=${dev-ca-path}
       ${pkgs.mkcert}/bin/mkcert -install
     '';
   };
   uninstallProjectCA = {
-    name = "uninstall-ca";
+    name = "ca-uninstall";
     help = "uninstall dev CA";
     package = pkgs.mkcert;
     command = ''
-      echo "$(tput bold)Purging the project's dev CA from local trust stores via mkcert command ...$(tput sgr0)"
+      echo "$(tput bold)Purging the ${name}'s dev CA from local trust stores via mkcert command ...$(tput sgr0)"
       export CAROOT=${dev-ca-path}
       ${pkgs.mkcert}/bin/mkcert -uninstall
     '';
diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index 05e25017..4e070b86 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -232,7 +232,7 @@ in
         command = ''
           echo "[commands]"
           cat <<'DEVSHELL_MENU'
-          ${commandsToMenu (config.commands ++ instrumentedCommands)}
+          ${commandsToMenu config.commands}
           DEVSHELL_MENU
         '';
       }
@@ -245,7 +245,7 @@ in
           (
             map
               (x: x.package)
-              (config.commands ++ instrumentedCommands)
+              config.commands
           )
       );
   };

From 12081e645e7508ad8f22c2b0281c5801e28f0426 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Thu, 8 Oct 2020 17:22:27 -0500
Subject: [PATCH 15/15] Add command categories

---
 devshell.toml                  |  2 ++
 docs/devshell.toml             |  2 ++
 docs/devshell.toml.md          |  2 ++
 mkDevShell/instrumentation.nix |  4 +++
 mkDevShell/options.nix         | 50 +++++++++++++++++++++++++---------
 5 files changed, 47 insertions(+), 13 deletions(-)

diff --git a/devshell.toml b/devshell.toml
index 0c03b0dc..624e50d0 100644
--- a/devshell.toml
+++ b/devshell.toml
@@ -59,11 +59,13 @@ command = "echo hello"
 help = "used to format Nix code"
 name = "nixpkgs-fmt"
 package = "nixpkgs-fmt"
+category = "formatters"
 
 [[commands]]
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+category = "utilites"
 
 # These settings help to manage local DNS overrides via
 # instrumentation of the hostcl third party tool.
diff --git a/docs/devshell.toml b/docs/devshell.toml
index 5685445e..779cb470 100644
--- a/docs/devshell.toml
+++ b/docs/devshell.toml
@@ -59,11 +59,13 @@ command = "echo hello"
 help = "used to format Nix code"
 name = "nixpkgs-fmt"
 package = "nixpkgs-fmt"
+category = "formatters"
 
 [[commands]]
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+category = "utilites"
 
 # These settings help to manage local DNS overrides via
 # instrumentation of the hostcl third party tool.
diff --git a/docs/devshell.toml.md b/docs/devshell.toml.md
index e98e4a6d..c528c55d 100644
--- a/docs/devshell.toml.md
+++ b/docs/devshell.toml.md
@@ -67,11 +67,13 @@ command = "echo hello"
 help = "used to format Nix code"
 name = "nixpkgs-fmt"
 package = "nixpkgs-fmt"
+category = "formatters"
 
 [[commands]]
 help = "github utility"
 name = "hub"
 package = "gitAndTools.hub"
+category = "utilities"
 
 # These settings help to manage local DNS overrides via
 # instrumentation of the hostcl third party tool.
diff --git a/mkDevShell/instrumentation.nix b/mkDevShell/instrumentation.nix
index dfa4b34d..813e11fe 100644
--- a/mkDevShell/instrumentation.nix
+++ b/mkDevShell/instrumentation.nix
@@ -8,6 +8,7 @@ let
   installProjectCA = {
     name = "ca-install";
     help = "install dev CA";
+    category = "host state";
     package = pkgs.mkcert;
     command = ''
       echo "$(tput bold)Installing the ${name}'s dev CA into local trust stores via mkcert command ...$(tput sgr0)"
@@ -18,6 +19,7 @@ let
   uninstallProjectCA = {
     name = "ca-uninstall";
     help = "uninstall dev CA";
+    category = "host state";
     package = pkgs.mkcert;
     command = ''
       echo "$(tput bold)Purging the ${name}'s dev CA from local trust stores via mkcert command ...$(tput sgr0)"
@@ -33,6 +35,7 @@ let
   # since this temporarily modifies /etc/hosts, use of sudo can't be avoided
   fqdnsActivate = {
     name = "dns-activate";
+    category = "host state";
     help = "activate pre-configured static dns";
     package = pkgs.hostctl;
     command = ''
@@ -42,6 +45,7 @@ let
   };
   fqdnsDeactivate = {
     name = "dns-deactivate";
+    category = "host state";
     help = "deactivate pre-configured static dns";
     package = pkgs.hostctl;
     command = ''
diff --git a/mkDevShell/options.nix b/mkDevShell/options.nix
index fc61b12b..829ae118 100644
--- a/mkDevShell/options.nix
+++ b/mkDevShell/options.nix
@@ -22,10 +22,8 @@ let
 
   commandsToMenu = commands:
     let
-      commandsSorted = builtins.sort (a: b: a.name < b.name) commands;
-
       commandLengths =
-        map ({ name, ... }: builtins.stringLength name) commandsSorted;
+        map ({ name, ... }: builtins.stringLength name) commands;
 
       maxCommandLength =
         builtins.foldl'
@@ -34,18 +32,36 @@ let
           commandLengths
       ;
 
-      op = { name, help, ... }:
+      commandCategoriesSorted = lib.unique (
+        (zipAttrsWithNames [ "category" ] (name: vs: vs) commands).category
+      );
+
+      commandByCategoriesSorted =
+        builtins.attrValues (lib.genAttrs
+          commandCategoriesSorted
+          (category: lib.nameValuePair category (builtins.sort
+            (a: b: a.name < b.name)
+            (builtins.filter
+              (x: x.category == category)
+              commands
+            )
+          ))
+        );
+
+      opCat = { name, value }:
         let
-          len = maxCommandLength - (builtins.stringLength name);
+          opCmd = { name, help, ...}:
+            let
+              len = maxCommandLength - (builtins.stringLength name);
+            in
+            if help == null || help == "" then
+              name
+            else
+              "${pad name len} - ${help}";
         in
-        if help == null || help == "" then
-          name
-        else
-          "${pad name len} - ${help}"
-      ;
-
+         "\n[${name}]\n" + builtins.concatStringsSep "\n" (map opCmd value);
     in
-    builtins.concatStringsSep "\n" (map op commandsSorted)
+    builtins.concatStringsSep "\n" (map opCat commandByCategoriesSorted)
   ;
 
   # Because we want to be able to push pure JSON-like data into the
@@ -63,6 +79,15 @@ let
       '';
     };
 
+    category = mkOption {
+      type = types.str;
+      default = "general commands";
+      description = ''
+        Set a free text category under which this command is grouped
+        and shown in the help menu.
+      '';
+    };
+
     help = mkOption {
       type = types.nullOr types.str;
       default = null;
@@ -230,7 +255,6 @@ in
         help = "prints this menu";
         name = "menu";
         command = ''
-          echo "[commands]"
           cat <<'DEVSHELL_MENU'
           ${commandsToMenu config.commands}
           DEVSHELL_MENU