test: add unit tests for run-commit --ref feature

Two new files, matching the existing repo test style (tags_test.go
pattern for handler tests via httptest.NewServer, routing_test.go
table-driven pattern for cmd-level pure-function tests):

  internal/handlers/run_commit_test.go:
    - TestHandleRunCommit_CommitIDPath — verifies default (IsRef=false)
      sends commit_id, no ref key in body
    - TestHandleRunCommit_RefPath      — verifies IsRef=true sends ref,
      no commit_id key
    - TestHandleRunCommit_ServerError  — verifies non-2xx surfaces as
      a caller-visible error (no silent swallowing)

  cmd/run_commit_test.go:
    - TestLooksLikeRepoRef (table-driven, 16 cases) — positive: canonical
      repo:tag shapes with various legal chars. Negative: empty/no-colon,
      malformed colon placement, chars outside the legal name set (space,
      slash, @, #, non-ASCII).
    - TestLooksLikeRepoRef_MultipleColons — documents the current (intended)
      behavior for a:b:c as NOT matching, since the second colon isn't a
      legal name char.

Author: nsluss

cmd/run_commit_test.go

@@ -0,0 +1,60 @@
+package cmd
+
+import "testing"
+
+// TestLooksLikeRepoRef verifies the heuristic used to suggest --ref when
+// the user passes a repo:tag-shaped argument. False positives are cheap
+// (we just show an extra suggestion); false negatives mean the user hits
+// a cryptic 422 from the API, so the positive cases get careful coverage.
+func TestLooksLikeRepoRef(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  bool
+	}{
+		// Positive: canonical repo:tag shapes
+		{"simple", "my-app:latest", true},
+		{"minimal", "a:b", true},
+		{"semver-tag", "my_app:v1.0.0", true},
+		{"dotted-parts", "x.y:1.2", true},
+		{"numeric-parts", "123:456", true},
+		{"mixed-legal-chars", "pi-agent:2026-04-19-v4", true},
+
+		// Negative: no colon
+		{"empty", "", false},
+		{"no-colon", "abc-123", false},
+		{"uuid", "aa84beb8-a080-4be5-bb7f-86374a68b380", false},
+
+		// Negative: malformed colon placement
+		{"colon-at-start", ":latest", false},
+		{"colon-at-end", "my-app:", false},
+		{"lone-colon", ":", false},
+
+		// Negative: contains characters not valid in repo/tag names
+		{"space", "my app:latest", false},
+		{"slash", "owner/my-app:latest", false},
+		{"at-sign", "my-app@v1:latest", false},
+		{"hash", "my-app#1:latest", false},
+		{"non-ascii", "my-app:päivä", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := looksLikeRepoRef(tt.input)
+			if got != tt.want {
+				t.Errorf("looksLikeRepoRef(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestLooksLikeRepoRef_MultipleColons documents the current behavior for
+// strings with more than one colon. The first colon splits repo from tag,
+// and subsequent characters (including another colon) must be legal name
+// chars. A bare `a:b:c` has a colon in the tag part, which fails the
+// legal-char check and returns false.
+func TestLooksLikeRepoRef_MultipleColons(t *testing.T) {
+	if looksLikeRepoRef("a:b:c") {
+		t.Error("expected a:b:c to NOT look like a repo:tag (colon in tag part is not a legal name char)")
+	}
+}

internal/handlers/run_commit_test.go

@@ -0,0 +1,124 @@
+package handlers_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/hdresearch/vers-cli/internal/handlers"
+)
+
+// TestHandleRunCommit_CommitIDPath verifies that when IsRef is false, the
+// request body places the argument under "commit_id" (no "ref" key).
+// This is the default behavior — any existing callers must not regress.
+func TestHandleRunCommit_CommitIDPath(t *testing.T) {
+	var receivedBody map[string]interface{}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/vm/from_commit" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.Method != http.MethodPost {
+			t.Errorf("expected POST, got %s", r.Method)
+		}
+		body, _ := io.ReadAll(r.Body)
+		json.Unmarshal(body, &receivedBody)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"vm_id": "vm-uuid-1"}`))
+	}))
+	defer server.Close()
+
+	a := testApp(server.URL)
+	res, err := handlers.HandleRunCommit(context.Background(), a, handlers.RunCommitReq{
+		CommitKey: "abc-123",
+		IsRef:     false,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.RootVmID != "vm-uuid-1" {
+		t.Errorf("expected VM ID vm-uuid-1, got %s", res.RootVmID)
+	}
+	if res.CommitKey != "abc-123" {
+		t.Errorf("expected CommitKey abc-123, got %s", res.CommitKey)
+	}
+
+	// The SDK flattens the vm_from_commit_request union into the top-level
+	// request body (MarshalJSON on VmRestoreFromCommitParams inlines it).
+	if receivedBody["commit_id"] != "abc-123" {
+		t.Errorf("expected commit_id=abc-123, got %v", receivedBody["commit_id"])
+	}
+	if _, refPresent := receivedBody["ref"]; refPresent {
+		t.Errorf("expected no 'ref' key when IsRef=false, got: %v", receivedBody)
+	}
+}
+
+// TestHandleRunCommit_RefPath verifies that when IsRef is true, the request
+// body uses "ref" instead of "commit_id". This is the new behavior added
+// by the --ref flag.
+func TestHandleRunCommit_RefPath(t *testing.T) {
+	var receivedBody map[string]interface{}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/vm/from_commit" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.Method != http.MethodPost {
+			t.Errorf("expected POST, got %s", r.Method)
+		}
+		body, _ := io.ReadAll(r.Body)
+		json.Unmarshal(body, &receivedBody)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"vm_id": "vm-uuid-2"}`))
+	}))
+	defer server.Close()
+
+	a := testApp(server.URL)
+	res, err := handlers.HandleRunCommit(context.Background(), a, handlers.RunCommitReq{
+		CommitKey: "my-app:latest",
+		IsRef:     true,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.RootVmID != "vm-uuid-2" {
+		t.Errorf("expected VM ID vm-uuid-2, got %s", res.RootVmID)
+	}
+	if res.CommitKey != "my-app:latest" {
+		t.Errorf("expected CommitKey my-app:latest, got %s", res.CommitKey)
+	}
+
+	// The SDK flattens the vm_from_commit_request union into the top-level
+	// request body (MarshalJSON on VmRestoreFromCommitParams inlines it).
+	if receivedBody["ref"] != "my-app:latest" {
+		t.Errorf("expected ref=my-app:latest, got %v", receivedBody["ref"])
+	}
+	if _, commitIDPresent := receivedBody["commit_id"]; commitIDPresent {
+		t.Errorf("expected no 'commit_id' key when IsRef=true, got: %v", receivedBody)
+	}
+}
+
+// TestHandleRunCommit_ServerError verifies that non-2xx responses surface as
+// errors to the caller (no silent swallowing).
+func TestHandleRunCommit_ServerError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUnprocessableEntity)
+		w.Write([]byte(`{"error": "invalid commit id"}`))
+	}))
+	defer server.Close()
+
+	a := testApp(server.URL)
+	_, err := handlers.HandleRunCommit(context.Background(), a, handlers.RunCommitReq{
+		CommitKey: "not-a-uuid",
+		IsRef:     false,
+	})
+	if err == nil {
+		t.Fatal("expected error for 422 response, got nil")
+	}
+}