feat(run-commit): add --ref flag for repo:tag references

Before this change, 'vers run-commit <arg>' always sent the argument as
{"commit_id": ...} in the API request. Passing a repo:tag reference
like 'my-app:latest' failed with 422 Unprocessable Entity because the
server tried to parse it as a UUID.

--ref switches the underlying payload to {"ref": ...}, which the API
resolves against tags in the caller's own org. The positive case was
verified end-to-end against pi-agent:latest.

Also added a friendly error when the argument looks like a repo:tag
(contains ':') and --ref was omitted, pointing the user at the right
flag instead of hitting a generic 422 from the API.

Author: noah

cmd/run_commit.go

@@ -2,7 +2,9 @@ package cmd
 
 import (
 	"context"
+	"fmt"
 	"os"
+	"strings"
 
 	"github.com/hdresearch/vers-cli/internal/handlers"
 	"github.com/hdresearch/vers-cli/internal/jobs"
@@ -16,27 +18,53 @@ var (
 	runCommitJSON   bool
 	runCommitFormat string
 	runCommitWait   bool
+	runCommitIsRef  bool
 )
 
 // runCommitCmd represents the run-commit command
 var runCommitCmd = &cobra.Command{
-	Use:   "run-commit [commit-key]",
+	Use:   "run-commit [commit-key | repo:tag]",
 	Short: "Start a development environment from a commit",
-	Long: `Start a Vers development environment from an existing commit using its commit key.
+	Long: `Start a Vers development environment from an existing commit.
+
+The argument is treated as a commit ID (UUID) by default. Pass --ref to interpret
+it as a repository reference in "repo_name:tag_name" format instead — the API
+will resolve the tag to the commit it currently points at within your own org.
+
+Examples:
+  vers run-commit c123456789abcdef
+  vers run-commit my-app:latest --ref
+  vers run-commit my-app:latest --ref --vm-alias dev --wait
 
 Use --json for machine-readable output.
 Use --wait to block until the VM is running.`,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		commitKey := args[0]
+
+		// Friendly nudge for the common gotcha: user passed something that
+		// looks like a repo:tag ref without --ref.
+		if !runCommitIsRef && looksLikeRepoRef(commitKey) {
+			return fmt.Errorf(
+				"'%s' looks like a repo:tag reference; did you mean '--ref'?\n"+
+					"  vers run-commit %s --ref",
+				commitKey, commitKey,
+			)
+		}
+
 		cfg, err := runconfig.Load()
 		if err != nil {
 			return err
 		}
 		applyFlagOverrides(cmd, cfg)
 		apiCtx, cancel := context.WithTimeout(context.Background(), application.Timeouts.APILong)
 		defer cancel()
-		req := handlers.RunCommitReq{CommitKey: commitKey, VMAlias: commitVmAlias, Wait: runCommitWait}
+		req := handlers.RunCommitReq{
+			CommitKey: commitKey,
+			VMAlias:   commitVmAlias,
+			Wait:      runCommitWait,
+			IsRef:     runCommitIsRef,
+		}
 		var jobID string
 		if runCommitWait {
 			jobID, _ = jobs.Submit(jobs.Submission{
@@ -70,6 +98,31 @@ Use --wait to block until the VM is running.`,
 	},
 }
 
+// looksLikeRepoRef returns true for strings in "word:word" shape where the
+// parts contain only characters that are legal in repo/tag names. Used only
+// to guess user intent and suggest --ref; never to actually dispatch.
+func looksLikeRepoRef(s string) bool {
+	i := strings.IndexByte(s, ':')
+	if i <= 0 || i == len(s)-1 {
+		return false
+	}
+	legal := func(c byte) bool {
+		return (c >= 'a' && c <= 'z') ||
+			(c >= 'A' && c <= 'Z') ||
+			(c >= '0' && c <= '9') ||
+			c == '-' || c == '_' || c == '.'
+	}
+	for j := 0; j < len(s); j++ {
+		if j == i {
+			continue
+		}
+		if !legal(s[j]) {
+			return false
+		}
+	}
+	return true
+}
+
 func init() {
 	rootCmd.AddCommand(runCommitCmd)
 
@@ -78,4 +131,5 @@ func init() {
 	runCommitCmd.Flags().StringVar(&runCommitFormat, "format", "", "Output format (json) [deprecated: use --json]")
 	_ = runCommitCmd.Flags().MarkDeprecated("format", "use --json instead")
 	runCommitCmd.Flags().BoolVar(&runCommitWait, "wait", false, "Wait until VM is running")
+	runCommitCmd.Flags().BoolVar(&runCommitIsRef, "ref", false, "Interpret the argument as a repo:tag reference instead of a commit ID")
 }

internal/handlers/run_commit.go

@@ -11,16 +11,30 @@ import (
 )
 
 type RunCommitReq struct {
+	// CommitKey is either a commit ID (UUID) or, when IsRef is true, a
+	// repository reference in "repo_name:tag_name" format.
 	CommitKey string
 	VMAlias   string
 	Wait      bool
+	// IsRef switches the underlying API payload from {"commit_id": ...} to
+	// {"ref": ...}, which enables resolving own-org repository tags like
+	// "my-app:latest" instead of raw commit UUIDs.
+	IsRef bool
 }
 
 func HandleRunCommit(ctx context.Context, a *app.App, r RunCommitReq) (presenters.RunCommitView, error) {
-	body := vers.VmRestoreFromCommitParams{
-		VmFromCommitRequest: vers.VmFromCommitRequestParam{
+	var reqUnion vers.VmFromCommitRequestUnionParam
+	if r.IsRef {
+		reqUnion = vers.VmFromCommitRequestRefParam{
+			Ref: vers.F(r.CommitKey),
+		}
+	} else {
+		reqUnion = vers.VmFromCommitRequestCommitIDParam{
 			CommitID: vers.F(r.CommitKey),
-		},
+		}
+	}
+	body := vers.VmRestoreFromCommitParams{
+		VmFromCommitRequest: reqUnion,
 	}
 
 	resp, err := a.Client.Vm.RestoreFromCommit(ctx, body)