Add versioning support and detailed CLI version command

- Introduced embedded version metadata (version, commit, and build date) during build time using `-ldflags`.
- Updated README with instructions for generating release binaries with version info.
- Added `version` command to display detailed build metadata.
- Updated root command to support `--version` and provide a summarized version output.
- Refactored internal version handling into a dedicated `internal/version.go` package.

Author: rolling-space

README.md

@@ -16,7 +16,35 @@ A practical CLI to manage your `~/.puma-dev` domain mappings. Because editing ra
 ## Install
 
 ```bash
-go install github.com/yourusername/pumadevctl@latest
+go install github.com/rolling-space/pumadevctl@latest
+```
+
+## Versioning and releases
+
+This CLI embeds version metadata at build time. By default, local builds display `dev`.
+
+To produce a release binary with version, commit, and build date:
+
+```bash
+VERSION=v0.4.0
+COMMIT=$(git rev-parse --short HEAD)
+DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Build to ./exe as per project guidelines
+mkdir -p ./exe
+GOOS=$(go env GOOS) GOARCH=$(go env GOARCH) \
+  go build -ldflags "-s -w \
+    -X github.com/rolling-space/pumadevctl/internal.Version=$VERSION \
+    -X github.com/rolling-space/pumadevctl/internal.Commit=$COMMIT \
+    -X github.com/rolling-space/pumadevctl/internal.Date=$DATE" \
+  -o ./exe/pumadevctl .
+```
+
+Check the result:
+
+```bash
+./exe/pumadevctl --version         # short summary
+./exe/pumadevctl version           # detailed info
 ```
 
 ## Usage

cmd/root.go

@@ -7,8 +7,8 @@ import (
 	"runtime"
 	"time"
 
-	"github.com/spf13/cobra"
 	"github.com/rolling-space/pumadevctl/internal"
+	"github.com/spf13/cobra"
 )
 
 var (
@@ -19,13 +19,11 @@ var (
 	portMinFlag   int
 	portMaxFlag   int
 	portBlockSize int
-	version       = "0.3.0"
 )
 
 var rootCmd = &cobra.Command{
-	Use:     "pumadevctl",
-	Short:   "Manage puma-dev mappings (~/.puma-dev) with CRUD, list, validate, cleanup",
-	Version: version,
+	Use:   "pumadevctl",
+	Short: "Manage puma-dev mappings (~/.puma-dev) with CRUD, list, validate, cleanup",
 }
 
 func Execute() {
@@ -36,6 +34,10 @@ func Execute() {
 }
 
 func init() {
+	// Configure version for Cobra (supports `--version` and `pumadevctl version`)
+	rootCmd.Version = internal.VersionSummary()
+	rootCmd.SetVersionTemplate("{{.Version}}\n")
+
 	home, _ := os.UserHomeDir()
 	defaultDir := filepath.Join(home, ".puma-dev")
 

cmd/version.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/rolling-space/pumadevctl/internal"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	cmd := &cobra.Command{
+		Use:   "version",
+		Short: "Show detailed version information",
+		Run: func(cmd *cobra.Command, args []string) {
+			fmt.Println(internal.VersionLong())
+		},
+	}
+	rootCmd.AddCommand(cmd)
+}

internal/version.go

@@ -0,0 +1,55 @@
+package internal
+
+import (
+	"fmt"
+	"runtime"
+)
+
+// Version metadata populated at build time via -ldflags. Defaults are for dev builds.
+var (
+	// Version is the semver for the release. e.g. v0.4.0. Defaults to "dev".
+	Version = "dev"
+	// Commit is the short git commit SHA for reproducibility.
+	Commit = ""
+	// Date is the build timestamp in UTC (ISO-8601), e.g. 2025-10-20T04:21:00Z.
+	Date = ""
+)
+
+// VersionSummary returns a human-friendly single-line version suitable for Cobra's Version field.
+func VersionSummary() string {
+	base := Version
+	meta := ""
+	if Commit != "" {
+		meta = Commit
+	}
+	if Date != "" {
+		if meta != "" {
+			meta = fmt.Sprintf("%s, %s", meta, Date)
+		} else {
+			meta = Date
+		}
+	}
+	if meta != "" {
+		return fmt.Sprintf("%s (%s, %s/%s)", base, meta, runtime.GOOS, runtime.GOARCH)
+	}
+	return fmt.Sprintf("%s (%s/%s)", base, runtime.GOOS, runtime.GOARCH)
+}
+
+// VersionLong returns a multi-line detailed version string.
+func VersionLong() string {
+	return fmt.Sprintf("version: %s\ncommit: %s\ndate:   %s\ngo:     %s %s/%s",
+		Version,
+		valueOrDash(Commit),
+		valueOrDash(Date),
+		runtime.Version(),
+		runtime.GOOS,
+		runtime.GOARCH,
+	)
+}
+
+func valueOrDash(s string) string {
+	if s == "" {
+		return "-"
+	}
+	return s
+}