From 98ccc23ef5214c219f06e18e03940fec80224781 Mon Sep 17 00:00:00 2001
From: Jack O'Sullivan <jackos1998@gmail.com>
Date: Sun, 14 Jun 2026 20:35:06 +0100
Subject: [PATCH] devshell: Add `check-system` and `ssh-machine` utilities

`check-system` evaluates a NixOS config without building it; `ssh-machine`
SSHs to a system or home by name, resolving the target and ssh options
from its `deploy-rs` node. Document both in `AGENTS.md`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md             | 12 ++++++++++++
 devshell/commands.nix | 25 +++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index ff52c56..ce454eb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,7 +21,17 @@ Common ones:
 - `build-home <name>` / `home-switch` — build / switch a home-manager config.
 - `run-vm <host>` — build & boot a system as a dev VM (installs `.keys/dev.key` into the VM).
 - `build-iso` / `build-kexec` / `build-netboot <host>` — alternate build outputs via `config.my.buildAs.*`.
+- `check-system <host> [nix args]` — evaluate a system (catches eval errors without a full build).
+  **Prefer this over `build-system` to validate a config change** — evaluation surfaces module/option
+  errors quickly and cheaply; only do a full build when you specifically need the built artifact.
 - `deploy <host>` and `deploy-multi <hosts...>` — deploy-rs deployment (uses `.keys/deploy.key`, `--skip-checks`).
+  Pass the flake-qualified node, e.g. `deploy .#git`. The deploy node name is **always** the system
+  name (`deploy-rs.nix` keys nodes directly off `nixos.systems` / `home-manager.homes`); a system is
+  only a deploy target when `config.my.deploy.enable` is true (defaults true; auto-disabled for dev
+  VMs and containers).
+- `ssh-machine <name> [cmd]` — SSH to a NixOS system or home-manager config by name. Resolves the
+  target and ssh options (identity, port) from its deploy-rs node, so it needs `my.deploy.enable`
+  (same gate as `deploy`).
 - `ragenix` — edit age secrets using `.keys/dev.key` as identity (see Secrets).
 - `repl` — `nix repl .#`.
 - `update-nixpkgs` / `update-home-manager` — bump pinned inputs.
@@ -99,3 +109,5 @@ private keys) is required for editing secrets, deploying, and running dev VMs.
 - New host → box file under `nixos/boxes/` + entry in the `configs` list in `flake.nix`.
 - Custom packages live in `pkgs/` and are registered in `pkgs/default.nix`; the overlay is exposed
   as `overlays.default`.
+- In prose and commit messages, quote code-like identifiers (commands, options, paths, package and
+  attribute names) in backticks.
diff --git a/devshell/commands.nix b/devshell/commands.nix
index 71efa71..83fbd43 100644
--- a/devshell/commands.nix
+++ b/devshell/commands.nix
@@ -48,6 +48,25 @@ in
       help = "Print the ed25519 pubkey for a host";
       command = "${pkgs.openssh}/bin/ssh-keyscan -t ed25519 \"$1\" 2> /dev/null | awk '{ print $2 \" \" $3 }'";
     }
+    {
+      name = "ssh-machine";
+      category = "utilities";
+      help = "SSH to a machine by NixOS system or home-manager config name";
+      command = ''
+        name="$1"
+        shift
+        # Run from the project root so deploy's relative identity path (.keys/deploy.key) resolves
+        cd "$PRJ_ROOT"
+        # deploy-rs node names are the system/home name, with `@` mangled to `-at-`
+        node="''${name//@/-at-}"
+        # Single eval: resolve `user@host` plus merged (global + node) deploy-rs ssh options
+        info="$(nix eval --raw .#deploy --apply 'd: let n = d.nodes."'"$node"'"; in "''${n.sshUser}@''${n.hostname} ''${builtins.concatStringsSep " " (d.sshOpts ++ n.sshOpts)}"')"
+        target="''${info%% *}"
+        opts="''${info#* }"
+        # shellcheck disable=SC2086
+        exec ${pkgs.openssh}/bin/ssh $opts "$target" "$@"
+      '';
+    }
     {
       name = "json2nix";
       category = "utilities";
@@ -73,6 +92,12 @@ in
       help = "Build NixOS configuration";
       command = ''nix build "''${@:2}" ".#nixosConfigurations.\"$1\".config.system.build.toplevel"'';
     }
+    {
+      name = "check-system";
+      category = "utilities";
+      help = "Evaluate NixOS configuration (check validity without building)";
+      command = ''nix eval "''${@:2}" ".#nixosConfigurations.\"$1\".config.system.build.toplevel.drvPath"'';
+    }
     {
       name = "build-n-switch";
       category = "tasks";