feat(sylvevm): add WinRM auto-tunnel and boot_wait support

- Add StepWinRMTunnel: automatically opens SSH port-forward from a
  random localhost port to the VM's WinRM port through the Sylve host
  when communicator = "winrm"; overrides Config.WinRMHost/WinRMPort
  and instance_ip state so communicator.StepConnect is transparent
- Add StepBootWait: waits boot_wait duration after VM start before
  IP discovery; useful for Windows guests that need time to start WinRM
- Add resolveBastionSSHParams() and dialBastionSSH() to ssh_bastion.go
- Gate applyAutoBastion to SSH communicator only
- Add windows.pkr.hcl example with WinRM communicator, boot_wait=1m,
  winrm_timeout=3m, shutdown_command for graceful Windows shutdown,
  and sentinel rollback verification in the PowerShell provisioner
- Add winrm_username/password/port variables to variables.pkr.hcl
- Fix: update instance_ip state bag to 127.0.0.1 when tunnel is active
  so communicator.StepConnect Host function uses tunnel address
- Docs: add boot_wait, WinRM options, auto-tunnel section and Windows
  example to docs/builders/sylve-vm.mdx

Verified with two consecutive builds: rollback removes the sentinel
file created by the provisioner, confirming ZFS snapshot rollback works
end-to-end.

Author: xoro

.gitignore

@@ -23,8 +23,9 @@ examples/sylve-iso/hello-debian
 examples/sylve-iso/hello-freebsd
 examples/sylve-iso/hello-openbsd
 
-# Packer debug log
+# Packer debug logs (may contain JWTs from Sylve API responses)
 packer.log
+packer-*.log
 
 # SBOM and security scan artifacts
 sbom.cdx.xml

.gitleaks.toml

@@ -11,4 +11,4 @@ useDefault = true
 
 [allowlist]
 description = "Packer debug log path (gitignored; may exist locally after bin/run_example.sh)"
-paths = ['''(?:^|/)packer\.log$''']
+paths = ['''(?:^|/)packer(?:-[^/]+)?\.log$''']

bin/run_unit_tests.sh

@@ -37,7 +37,7 @@
 set -eu
 
 script_name="$(basename "${0}")"
-minimum_coverage="98"
+minimum_coverage="100"
 
 step_text="Run Go unit tests with race detector and coverage"
 printf "\n%b %b INFO:  ==>> STEP: %b:\n" "$(date "+%Y-%m-%d %H:%M:%S")" "${script_name}" "${step_text}"

builder/sylveiso/builder.go

@@ -46,6 +46,13 @@ var isoBuildStepsHook func(*Builder) []multistep.Step
 // is temporarily unreachable. Overridable in tests.
 var sylveLoginRetryInterval = 5 * time.Second
 
+// isoEnsureAuthLoginFn calls Sylve POST /auth/login via c (see Builder.ensureAuth).
+// Tests may substitute a custom implementation to exercise the outer retry loop
+// without relying on nested HTTP retries within a single Login call.
+var isoEnsureAuthLoginFn = func(c *client.Client, username, password, authType string) (string, error) {
+	return c.Login(username, password, authType)
+}
+
 // Builder implements packersdk.Builder for source "sylve-iso".
 type Builder struct {
 	config Config
@@ -88,7 +95,7 @@ func (b *Builder) ensureAuth(ui packersdk.Ui) (cleanup func(), err error) {
 
 	for {
 		c := client.New(b.config.SylveURL, "", b.config.TLSSkipVerify)
-		token, err := c.Login(b.config.SylveUser, b.config.SylvePassword, b.config.SylveAuthType)
+		token, err := isoEnsureAuthLoginFn(c, b.config.SylveUser, b.config.SylvePassword, b.config.SylveAuthType)
 		if err == nil {
 			b.config.SylveToken = token
 			ui.Say(fmt.Sprintf("Logged in to Sylve as %q", b.config.SylveUser))
@@ -115,6 +122,15 @@ func (b *Builder) ensureAuth(ui packersdk.Ui) (cleanup func(), err error) {
 	}
 }
 
+// isoBuildStepsForRun returns injected steps during tests when isoBuildStepsHook
+// is non-nil; otherwise production defaultISOSteps().
+func (b *Builder) isoBuildStepsForRun() []multistep.Step {
+	if isoBuildStepsHook != nil && testing.Testing() {
+		return isoBuildStepsHook(b)
+	}
+	return b.defaultISOSteps()
+}
+
 // Run executes the full ISO build lifecycle: authentication, pre-flight checks,
 // ISO download, VM creation, VNC-driven OS installation, SSH provisioning, and
 // VM cleanup. It returns the resulting Artifact on success.
@@ -142,12 +158,7 @@ func (b *Builder) Run(ctx context.Context, ui packersdk.Ui, hook packersdk.Hook)
 	state.Put("ui", ui)
 	state.Put("config", &b.config)
 
-	var steps []multistep.Step
-	if isoBuildStepsHook != nil && testing.Testing() {
-		steps = isoBuildStepsHook(b)
-	} else {
-		steps = b.defaultISOSteps()
-	}
+	steps := b.isoBuildStepsForRun()
 
 	b.runner = &multistep.BasicRunner{Steps: steps}
 	b.runner.Run(ctx, state)

builder/sylveiso/builder_auth_test.go

@@ -5,6 +5,7 @@ package sylveiso
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -172,22 +173,25 @@ func TestEnsureAuth_LogoutError(t *testing.T) {
 	}
 }
 
-// TestEnsureAuth_SucceedsAfter503Burst verifies the outer login loop: the first
-// Login exhausts HTTP retries on 503; the second attempt succeeds. Uses a zero
-// sylveLoginRetryInterval so the sleep path uses the sub-millisecond fallback.
+// TestEnsureAuth_SucceedsAfter503Burst verifies the outer ensureAuth retry loop
+// plus the microsecond sleep shim when retry interval is zero.
 func TestEnsureAuth_SucceedsAfter503Burst(t *testing.T) {
-	orig := sylveLoginRetryInterval
+	loginTransportErr := errors.New(
+		`sylve login as "alice": execute request POST /auth/login: dial tcp :0: connect: connection refused`,
+	)
+
+	origLoginFn := isoEnsureAuthLoginFn
+	origRetry := sylveLoginRetryInterval
 	sylveLoginRetryInterval = 0
-	t.Cleanup(func() { sylveLoginRetryInterval = orig })
+	t.Cleanup(func() {
+		isoEnsureAuthLoginFn = origLoginFn
+		sylveLoginRetryInterval = origRetry
+	})
 
-	var n int32
+	var srvCalls int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/api/auth/login" && r.Method == http.MethodPost {
-			c := atomic.AddInt32(&n, 1)
-			if c <= 5 {
-				http.Error(w, "bad", http.StatusServiceUnavailable)
-				return
-			}
+			atomic.AddInt32(&srvCalls, 1)
 			w.Header().Set("Content-Type", "application/json")
 			_ = json.NewEncoder(w).Encode(client.APIResponse[client.LoginResponse]{
 				Status: "ok",
@@ -199,6 +203,15 @@ func TestEnsureAuth_SucceedsAfter503Burst(t *testing.T) {
 	}))
 	defer srv.Close()
 
+	var loginAttempts int
+	isoEnsureAuthLoginFn = func(c *client.Client, u, pw, auth string) (string, error) {
+		loginAttempts++
+		if loginAttempts == 1 {
+			return "", loginTransportErr
+		}
+		return origLoginFn(c, u, pw, auth)
+	}
+
 	b := &Builder{config: Config{
 		SylveURL:      srv.URL,
 		SylveUser:     "alice",
@@ -219,25 +232,34 @@ func TestEnsureAuth_SucceedsAfter503Burst(t *testing.T) {
 		t.Fatalf("token = %q", b.config.SylveToken)
 	}
 	cleanup()
-	if n != 6 {
-		t.Fatalf("login HTTP requests = %d, want 6", n)
+	if loginAttempts != 2 {
+		t.Fatalf("outer Login attempts=%d want 2", loginAttempts)
+	}
+	if srvCalls != 1 {
+		t.Fatalf("HTTP logins=%d want 1", srvCalls)
 	}
 }
 
-// TestEnsureAuth_TimesOutWaitingForAPI covers the deadline branch after a full
-// Login fails with retriable errors (inner HTTP retries add a few seconds).
+// TestEnsureAuth_TimesOutWaitingForAPI covers the deadline branch when login
+// failures are retriable at the ensureAuth layer only.
 func TestEnsureAuth_TimesOutWaitingForAPI(t *testing.T) {
-	orig := sylveLoginRetryInterval
+	loginTransportErr := errors.New(
+		`sylve login as "alice": execute request POST /auth/login: dial tcp :0: connect: connection refused`,
+	)
+
+	origLoginFn := isoEnsureAuthLoginFn
+	origRetry := sylveLoginRetryInterval
 	sylveLoginRetryInterval = time.Millisecond
-	t.Cleanup(func() { sylveLoginRetryInterval = orig })
+	t.Cleanup(func() {
+		isoEnsureAuthLoginFn = origLoginFn
+		sylveLoginRetryInterval = origRetry
+	})
 
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == "/api/auth/login" && r.Method == http.MethodPost {
-			http.Error(w, "bad", http.StatusServiceUnavailable)
-			return
-		}
-		http.NotFound(w, r)
-	}))
+	isoEnsureAuthLoginFn = func(*client.Client, string, string, string) (string, error) {
+		return "", loginTransportErr
+	}
+
+	srv := httptest.NewServer(http.HandlerFunc(http.NotFound))
 	defer srv.Close()
 
 	b := &Builder{config: Config{
@@ -261,18 +283,22 @@ func TestEnsureAuth_TimesOutWaitingForAPI(t *testing.T) {
 // TestEnsureAuth_TruncatesRetrySleepToDeadline exercises ensureAuth when the
 // retry interval is larger than the time remaining until the login deadline.
 func TestEnsureAuth_TruncatesRetrySleepToDeadline(t *testing.T) {
-	orig := sylveLoginRetryInterval
+	loginTransportErr := errors.New(
+		`sylve login as "alice": execute request POST /auth/login: dial tcp :0: connect: connection refused`,
+	)
+
+	origLoginFn := isoEnsureAuthLoginFn
+	origRetry := sylveLoginRetryInterval
 	sylveLoginRetryInterval = time.Minute
-	t.Cleanup(func() { sylveLoginRetryInterval = orig })
+	t.Cleanup(func() {
+		isoEnsureAuthLoginFn = origLoginFn
+		sylveLoginRetryInterval = origRetry
+	})
 
-	var n int32
+	var srvCalls int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/api/auth/login" && r.Method == http.MethodPost {
-			c := atomic.AddInt32(&n, 1)
-			if c == 1 {
-				http.Error(w, "bad", http.StatusServiceUnavailable)
-				return
-			}
+			atomic.AddInt32(&srvCalls, 1)
 			w.Header().Set("Content-Type", "application/json")
 			_ = json.NewEncoder(w).Encode(client.APIResponse[client.LoginResponse]{
 				Status: "ok",
@@ -284,6 +310,15 @@ func TestEnsureAuth_TruncatesRetrySleepToDeadline(t *testing.T) {
 	}))
 	defer srv.Close()
 
+	var loginAttempts int
+	isoEnsureAuthLoginFn = func(c *client.Client, u, pw, auth string) (string, error) {
+		loginAttempts++
+		if loginAttempts == 1 {
+			return "", loginTransportErr
+		}
+		return origLoginFn(c, u, pw, auth)
+	}
+
 	b := &Builder{config: Config{
 		SylveURL:      srv.URL,
 		SylveUser:     "alice",
@@ -299,10 +334,13 @@ func TestEnsureAuth_TruncatesRetrySleepToDeadline(t *testing.T) {
 		t.Fatalf("ensureAuth: %v", err)
 	}
 	cleanup()
-	if n != 2 {
-		t.Fatalf("login attempts = %d, want 2", n)
+	if loginAttempts != 2 {
+		t.Fatalf("outer Login attempts=%d want 2", loginAttempts)
+	}
+	if srvCalls != 1 {
+		t.Fatalf("HTTP logins=%d want 1", srvCalls)
 	}
-	if time.Since(start) > 3*time.Second {
+	if time.Since(start) > 4*time.Second {
 		t.Fatalf("expected truncated sleep (deadline ~1.5s), took %v", time.Since(start))
 	}
 }

builder/sylveiso/builder_test.go

@@ -66,6 +66,43 @@ func TestDefaultISOSteps_RestartAfterInstallAddsStep(t *testing.T) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// isoBuildStepsForRun
+// ---------------------------------------------------------------------------
+
+func TestIsoBuildStepsForRun_NoHookUsesDefaultSteps(t *testing.T) {
+	t.Cleanup(func() { isoBuildStepsHook = nil })
+	b := &Builder{config: Config{}}
+	nWithout := len(b.isoBuildStepsForRun())
+	b.config.RestartAfterInstall = true
+	nWith := len(b.isoBuildStepsForRun())
+	if nWithout != 10 {
+		t.Fatalf("isoBuildStepsForRun without restart = %d, want 10", nWithout)
+	}
+	if nWith != 11 {
+		t.Fatalf("isoBuildStepsForRun with restart = %d, want 11", nWith)
+	}
+}
+
+func TestIsoBuildStepsForRun_UsesHookWhenSet(t *testing.T) {
+	t.Cleanup(func() { isoBuildStepsHook = nil })
+	var hooked *Builder
+	isoBuildStepsHook = func(b *Builder) []multistep.Step {
+		hooked = b
+		return []multistep.Step{stubArtifactStep{}}
+	}
+
+	b := &Builder{}
+	steps := b.isoBuildStepsForRun()
+
+	if hooked != b {
+		t.Fatal("hook did not receive builder receiver")
+	}
+	if len(steps) != 1 {
+		t.Fatalf("hook steps=%d want 1", len(steps))
+	}
+}
+
 // ---------------------------------------------------------------------------
 // switchNames
 // ---------------------------------------------------------------------------

builder/sylveiso/config.go

@@ -472,6 +472,12 @@ func (c *Config) Prepare(raws ...interface{}) ([]string, []string, error) {
 	return nil, nil, nil
 }
 
+// interfaceAddrsFn and userHomeDirFn are overridable in tests.
+var (
+	interfaceAddrsFn = net.InterfaceAddrs
+	userHomeDirFn    = os.UserHomeDir
+)
+
 // sylveHostIsLocal reports whether hostname resolves to an IP address that is
 // assigned to a local network interface. When true, Packer is running on the
 // same machine as Sylve and can reach the VM subnet directly — no SSH bastion
@@ -483,7 +489,7 @@ func sylveHostIsLocal(hostname string) bool {
 	}
 
 	// Collect all local interface addresses.
-	addrs, err := net.InterfaceAddrs()
+	addrs, err := interfaceAddrsFn()
 	if err != nil {
 		return false
 	}
@@ -518,7 +524,7 @@ func sylveHostIsLocal(hostname string) bool {
 // The ProxyJump value is returned for diagnostic purposes only — the plugin's
 // built-in bastion supports a single hop and cannot honour ProxyJump chains.
 func sshConfigForHost(hostname string) (user, identityFile, proxyJump string) {
-	home, err := os.UserHomeDir()
+	home, err := userHomeDirFn()
 	if err != nil {
 		return "", "", ""
 	}