add field-level change details to dry-run and reconcile output

.gitea/workflows/dry-run.yml

@@ -87,16 +87,59 @@ jobs:
                       elif t.startswith("delete"): groups["Delete"].append(op)
                       else: groups["Update"].append(op)
 
+                  def fmt_val(v):
+                      """Format a value for display in markdown."""
+                      if isinstance(v, bool):
+                          return str(v).lower()
+                      if isinstance(v, list):
+                          return ", ".join(str(x) for x in v) if v else "(empty)"
+                      if v is None:
+                          return "(none)"
+                      return str(v)
+
+                  def fmt_create_details(op):
+                      """Summarize key fields for a create operation."""
+                      d = op.get("details", {})
+                      if not d:
+                          return ""
+                      parts = []
+                      if "enabled" in d:
+                          parts.append(f"enabled={fmt_val(d['enabled'])}")
+                      if "sources" in d and "destinations" in d:
+                          parts.append(f"{fmt_val(d['sources'])} → {fmt_val(d['destinations'])}")
+                      if "auto_groups" in d:
+                          parts.append(f"groups: {fmt_val(d['auto_groups'])}")
+                      if "type" in d and "address" in d:
+                          parts.append(f"{d['type']}:{d['address']}")
+                      if "peers" in d:
+                          parts.append(f"peers: {fmt_val(d['peers'])}")
+                      return "; ".join(parts) if parts else ""
+
+                  def fmt_changes(op):
+                      """Format field changes as 'field: old → new'."""
+                      changes = op.get("changes", [])
+                      if not changes:
+                          return ""
+                      parts = []
+                      for c in changes:
+                          parts.append(f"`{c['field']}`: {fmt_val(c['from'])} → {fmt_val(c['to'])}")
+                      return "; ".join(parts)
+
                   for action, items in groups.items():
                       if not items:
                           continue
-                      emoji = {"Create": "+", "Update": "~", "Delete": "-"}[action]
                       lines.append(f"### {action} ({len(items)})\n")
-                      lines.append("| Resource | Name |")
+                      lines.append("| Resource | Name | Details |")
-                      lines.append("|----------|------|")
+                      lines.append("|----------|------|---------|")
                       for op in items:
                           resource = op["type"].split("_", 1)[1] if "_" in op["type"] else op["type"]
-                          lines.append(f"| {resource} | {op['name']} |")
+                          if action == "Update":
+                              detail = fmt_changes(op)
+                          elif action == "Create":
+                              detail = fmt_create_details(op)
+                          else:
+                              detail = ""
+                          lines.append(f"| {resource} | {op['name']} | {detail} |")
                       lines.append("")
 
                   c, u, d = summary.get("created", 0), summary.get("updated", 0), summary.get("deleted", 0)

.gitea/workflows/reconcile.yml

@@ -95,6 +95,27 @@ jobs:
                     f"{summary.get('updated',0)} updated, "
                     f"{summary.get('deleted',0)} deleted")
 
+              # Log each operation with details
+              for op in data.get("operations", []):
+                  t = op["type"]
+                  n = op["name"]
+                  s = op.get("status", "?")
+                  action = "CREATE" if t.startswith("create") else "DELETE" if t.startswith("delete") else "UPDATE"
+                  resource = t.split("_", 1)[1] if "_" in t else t
+                  prefix = f"[{env}] {action} {resource} '{n}' -> {s}"
+
+                  changes = op.get("changes", [])
+                  if changes:
+                      def fmt(v):
+                          if isinstance(v, bool): return str(v).lower()
+                          if isinstance(v, list): return ", ".join(str(x) for x in v) if v else "(empty)"
+                          if v is None: return "(none)"
+                          return str(v)
+                      parts = [f"{c['field']}: {fmt(c['from'])} -> {fmt(c['to'])}" for c in changes]
+                      print(f"  {prefix} [{'; '.join(parts)}]")
+                  else:
+                      print(f"  {prefix}")
+
               keys = data.get("created_keys", {})
               if keys:
                   print(f"[{env}] Created setup keys: {list(keys.keys())}")

src/reconcile/diff.ts

@@ -1,7 +1,11 @@
 import type { DesiredState } from "../state/schema.ts";
 import type { ActualState } from "../state/actual.ts";
 import type { NbPolicyRule } from "../netbird/types.ts";
-import { EXECUTION_ORDER, type Operation } from "./operations.ts";
+import {
+  EXECUTION_ORDER,
+  type FieldChange,
+  type Operation,
+} from "./operations.ts";
 
 /**
  * Compares desired state against actual state and returns an ordered list of
@@ -53,10 +57,14 @@ function diffPostureChecks(
       continue;
     }
 
-    if (
+    const pcChanges: FieldChange[] = [];
-      existing.description !== config.description ||
+    if (existing.description !== config.description) {
-      JSON.stringify(existing.checks) !== JSON.stringify(config.checks)
+      pcChanges.push({ field: "description", from: existing.description, to: config.description });
-    ) {
+    }
+    if (JSON.stringify(existing.checks) !== JSON.stringify(config.checks)) {
+      pcChanges.push({ field: "checks", from: existing.checks, to: config.checks });
+    }
+    if (pcChanges.length > 0) {
       ops.push({
         type: "update_posture_check",
         name,
@@ -64,6 +72,7 @@ function diffPostureChecks(
           description: config.description,
           checks: config.checks,
         },
+        changes: pcChanges,
       });
     }
   }
@@ -108,6 +117,9 @@ function diffGroups(
           desired_peers: desiredPeerNames,
           actual_peers: actualPeerNames,
         },
+        changes: [
+          { field: "peers", from: actualPeerNames, to: desiredPeerNames },
+        ],
       });
     }
   }
@@ -219,6 +231,9 @@ function diffNetworks(
         type: "update_network",
         name,
         details: { description: config.description },
+        changes: [
+          { field: "description", from: existing.description, to: config.description },
+        ],
       });
     }
 
@@ -293,13 +308,23 @@ function diffNetworkResources(
     const actualGroupNames = existing.groups.map((g) => g.name).sort();
     const desiredGroupNames = [...res.groups].sort();
 
-    if (
+    const resChanges: FieldChange[] = [];
-      existing.description !== res.description ||
+    if (existing.description !== res.description) {
-      existing.type !== res.type ||
+      resChanges.push({ field: "description", from: existing.description, to: res.description });
-      existing.address !== res.address ||
+    }
-      existing.enabled !== res.enabled ||
+    if (existing.type !== res.type) {
-      !arraysEqual(actualGroupNames, desiredGroupNames)
+      resChanges.push({ field: "type", from: existing.type, to: res.type });
-    ) {
+    }
+    if (existing.address !== res.address) {
+      resChanges.push({ field: "address", from: existing.address, to: res.address });
+    }
+    if (existing.enabled !== res.enabled) {
+      resChanges.push({ field: "enabled", from: existing.enabled, to: res.enabled });
+    }
+    if (!arraysEqual(actualGroupNames, desiredGroupNames)) {
+      resChanges.push({ field: "groups", from: actualGroupNames, to: desiredGroupNames });
+    }
+    if (resChanges.length > 0) {
       ops.push({
         type: "update_network_resource",
         name: res.name,
@@ -312,6 +337,7 @@ function diffNetworkResources(
           enabled: res.enabled,
           groups: res.groups,
         },
+        changes: resChanges,
       });
     }
   }
@@ -362,11 +388,17 @@ function diffNetworkRouters(
     }
 
     // Compare mutable fields
-    if (
+    const routerChanges: FieldChange[] = [];
-      existing.metric !== router.metric ||
+    if (existing.metric !== router.metric) {
-      existing.masquerade !== router.masquerade ||
+      routerChanges.push({ field: "metric", from: existing.metric, to: router.metric });
-      existing.enabled !== router.enabled
+    }
-    ) {
+    if (existing.masquerade !== router.masquerade) {
+      routerChanges.push({ field: "masquerade", from: existing.masquerade, to: router.masquerade });
+    }
+    if (existing.enabled !== router.enabled) {
+      routerChanges.push({ field: "enabled", from: existing.enabled, to: router.enabled });
+    }
+    if (routerChanges.length > 0) {
       ops.push({
         type: "update_network_router",
         name: key,
@@ -379,6 +411,7 @@ function diffNetworkRouters(
           masquerade: router.masquerade,
           enabled: router.enabled,
         },
+        changes: routerChanges,
       });
     }
   }
@@ -441,7 +474,7 @@ function diffPeers(
     const existing = actual.peersByName.get(name);
     if (!existing) continue; // Never create or delete peers
 
-    let changed = false;
+    const peerChanges: FieldChange[] = [];
 
     // Compare groups (excluding "All"), resolve actual peer group names
     const actualGroupNames = existing.groups
@@ -450,19 +483,20 @@ function diffPeers(
       .sort();
     const desiredGroupNames = [...config.groups].sort();
     if (!arraysEqual(actualGroupNames, desiredGroupNames)) {
-      changed = true;
+      peerChanges.push({ field: "groups", from: actualGroupNames, to: desiredGroupNames });
     }
 
-    if (
+    if (existing.login_expiration_enabled !== config.login_expiration_enabled) {
-      existing.login_expiration_enabled !== config.login_expiration_enabled ||
+      peerChanges.push({ field: "login_expiration_enabled", from: existing.login_expiration_enabled, to: config.login_expiration_enabled });
-      existing.inactivity_expiration_enabled !==
+    }
-        config.inactivity_expiration_enabled ||
+    if (existing.inactivity_expiration_enabled !== config.inactivity_expiration_enabled) {
-      existing.ssh_enabled !== config.ssh_enabled
+      peerChanges.push({ field: "inactivity_expiration_enabled", from: existing.inactivity_expiration_enabled, to: config.inactivity_expiration_enabled });
-    ) {
+    }
-      changed = true;
+    if (existing.ssh_enabled !== config.ssh_enabled) {
+      peerChanges.push({ field: "ssh_enabled", from: existing.ssh_enabled, to: config.ssh_enabled });
     }
 
-    if (changed) {
+    if (peerChanges.length > 0) {
       ops.push({
         type: "update_peer",
         name,
@@ -472,6 +506,7 @@ function diffPeers(
           inactivity_expiration_enabled: config.inactivity_expiration_enabled,
           ssh_enabled: config.ssh_enabled,
         },
+        changes: peerChanges,
       });
     }
   }
@@ -511,10 +546,14 @@ function diffUsers(
     ).sort();
     const desiredAutoGroupNames = [...config.auto_groups].sort();
 
-    if (
+    const userChanges: FieldChange[] = [];
-      existing.role !== config.role ||
+    if (existing.role !== config.role) {
-      !arraysEqual(actualAutoGroupNames, desiredAutoGroupNames)
+      userChanges.push({ field: "role", from: existing.role, to: config.role });
-    ) {
+    }
+    if (!arraysEqual(actualAutoGroupNames, desiredAutoGroupNames)) {
+      userChanges.push({ field: "auto_groups", from: actualAutoGroupNames, to: desiredAutoGroupNames });
+    }
+    if (userChanges.length > 0) {
       ops.push({
         type: "update_user",
         name: email,
@@ -523,6 +562,7 @@ function diffUsers(
           role: config.role,
           auto_groups: config.auto_groups,
         },
+        changes: userChanges,
       });
     }
   }
@@ -609,12 +649,30 @@ function diffPolicies(
       desiredPostureChecks,
     );
 
-    if (
+    const changes: FieldChange[] = [];
-      existing.enabled !== config.enabled ||
+    if (existing.enabled !== config.enabled) {
-      !arraysEqual(actualSources, desiredSources) ||
+      changes.push({ field: "enabled", from: existing.enabled, to: config.enabled });
-      destsChanged ||
+    }
-      postureChecksChanged
+    if (!arraysEqual(actualSources, desiredSources)) {
-    ) {
+      changes.push({ field: "sources", from: actualSources, to: desiredSources });
+    }
+    if (destsChanged) {
+      if (config.destination_resource) {
+        const actualDestRes = existing.rules[0]?.destinationResource;
+        changes.push({ field: "destination_resource", from: actualDestRes ?? null, to: config.destination_resource });
+      } else {
+        const actualDests = extractGroupNames(
+          existing.rules.flatMap((r) => r.destinations ?? []),
+          actual,
+        ).sort();
+        changes.push({ field: "destinations", from: actualDests, to: [...config.destinations].sort() });
+      }
+    }
+    if (postureChecksChanged) {
+      changes.push({ field: "source_posture_checks", from: actualPostureChecks, to: desiredPostureChecks });
+    }
+
+    if (changes.length > 0) {
       ops.push({
         type: "update_policy",
         name,
@@ -625,6 +683,7 @@ function diffPolicies(
           destination_resource: config.destination_resource,
           source_posture_checks: config.source_posture_checks,
         },
+        changes,
       });
     }
   }
@@ -682,11 +741,17 @@ function diffRoutes(
       continue;
     }
 
-    if (
+    const routeChanges: FieldChange[] = [];
-      existing.enabled !== config.enabled ||
+    if (existing.enabled !== config.enabled) {
-      existing.description !== config.description ||
+      routeChanges.push({ field: "enabled", from: existing.enabled, to: config.enabled });
-      existing.network !== config.network
+    }
-    ) {
+    if (existing.description !== config.description) {
+      routeChanges.push({ field: "description", from: existing.description, to: config.description });
+    }
+    if (existing.network !== config.network) {
+      routeChanges.push({ field: "network", from: existing.network, to: config.network });
+    }
+    if (routeChanges.length > 0) {
       ops.push({
         type: "update_route",
         name: networkId,
@@ -695,6 +760,7 @@ function diffRoutes(
           description: config.description,
           network: config.network,
         },
+        changes: routeChanges,
       });
     }
   }
@@ -741,11 +807,17 @@ function diffDns(
       config.nameservers,
     );
 
-    if (
+    const dnsChanges: FieldChange[] = [];
-      existing.enabled !== config.enabled ||
+    if (existing.enabled !== config.enabled) {
-      existing.primary !== config.primary ||
+      dnsChanges.push({ field: "enabled", from: existing.enabled, to: config.enabled });
-      nsChanged
+    }
-    ) {
+    if (existing.primary !== config.primary) {
+      dnsChanges.push({ field: "primary", from: existing.primary, to: config.primary });
+    }
+    if (nsChanged) {
+      dnsChanges.push({ field: "nameservers", from: existing.nameservers, to: config.nameservers });
+    }
+    if (dnsChanges.length > 0) {
       ops.push({
         type: "update_dns",
         name,
@@ -754,6 +826,7 @@ function diffDns(
           primary: config.primary,
           nameservers: config.nameservers,
         },
+        changes: dnsChanges,
       });
     }
   }

src/reconcile/operations.ts

@@ -33,10 +33,17 @@ export type OperationType =
   | "update_user"
   | "delete_user";
 
+export interface FieldChange {
+  field: string;
+  from: unknown;
+  to: unknown;
+}
+
 export interface Operation {
   type: OperationType;
   name: string;
   details?: Record<string, unknown>;
+  changes?: FieldChange[];
 }
 
 export interface OperationResult extends Operation {

src/server.ts

@@ -109,6 +109,8 @@ async function handleReconcile(
         operations: ops.map((op) => ({
           type: op.type,
           name: op.name,
+          ...(op.details && { details: op.details }),
+          ...(op.changes && { changes: op.changes }),
         })),
         summary: summarize(ops),
       });
@@ -141,6 +143,8 @@ async function handleReconcile(
         type: r.type,
         name: r.name,
         status: r.status,
+        ...(r.details && { details: r.details }),
+        ...(r.changes && { changes: r.changes }),
       })),
       created_keys: createdKeysObj,
       summary: summarize(results),