feat(locale): add FormatPhoneNumber with international support

Parses and formats phone numbers using nyaruka/phonenumbers. Uses
region comparison to choose NATIONAL vs INTERNATIONAL format, with
country-code fallback for fictional numbers (e.g. 555-xxxx).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cpcloud

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/itchyny/gojq v0.12.18
 	github.com/mark3labs/mcp-go v0.46.0
 	github.com/mozilla-ai/any-llm-go v0.9.0
+	github.com/nyaruka/phonenumbers v1.6.12
 	github.com/oklog/ulid/v2 v2.1.1
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1

go.sum

@@ -193,6 +193,8 @@ github.com/muesli/roff v0.1.0 h1:YD0lalCotmYuF5HhZliKWlIx7IEhiXeSfq7hNjFqGF8=
 github.com/muesli/roff v0.1.0/go.mod h1:pjAHQM9hdUUwm/krAfrLGgJkXJ+YuhtsfZ42kieB2Ig=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/nyaruka/phonenumbers v1.6.12 h1:aeGHjGQnfLhdN5/mZPevhoYMs13FWcQ0Vus0YQHh1Ec=
+github.com/nyaruka/phonenumbers v1.6.12/go.mod h1:IUu45lj2bSeYXQuxDyyuzOrdV10tyRa1YSsfH8EKN5c=
 github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
 github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
 github.com/ollama/ollama v0.18.3 h1:sOJhncLeA+ZlwLLjEksY393wojeYE52E1CF4E0ZgFN4=

internal/locale/phone.go

@@ -0,0 +1,38 @@
+// Copyright 2026 Phillip Cloud
+// Licensed under the Apache License, Version 2.0
+
+package locale
+
+import (
+	"strings"
+
+	"github.com/nyaruka/phonenumbers"
+)
+
+// FormatPhoneNumber formats a phone number string for display.
+// regionCode is an uppercase ISO 3166-1 alpha-2 code (e.g. "US").
+// Returns the original string unmodified if parsing fails.
+func FormatPhoneNumber(number, regionCode string) string {
+	trimmed := strings.TrimSpace(number)
+	if trimmed == "" {
+		return ""
+	}
+	parsed, err := phonenumbers.Parse(trimmed, regionCode)
+	if err != nil {
+		return number
+	}
+	// Prefer region comparison (distinguishes US/CA under shared +1 code).
+	// Fall back to country-code comparison for fictional numbers (e.g. 555-xxxx)
+	// that parse successfully but return an empty region.
+	parsedRegion := phonenumbers.GetRegionCodeForNumber(parsed)
+	if parsedRegion != "" {
+		if parsedRegion == regionCode {
+			return phonenumbers.Format(parsed, phonenumbers.NATIONAL)
+		}
+		return phonenumbers.Format(parsed, phonenumbers.INTERNATIONAL)
+	}
+	if int(parsed.GetCountryCode()) == phonenumbers.GetCountryCodeForRegion(regionCode) {
+		return phonenumbers.Format(parsed, phonenumbers.NATIONAL)
+	}
+	return phonenumbers.Format(parsed, phonenumbers.INTERNATIONAL)
+}

internal/locale/phone_test.go

@@ -0,0 +1,39 @@
+// Copyright 2026 Phillip Cloud
+// Licensed under the Apache License, Version 2.0
+
+package locale_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/micasa-dev/micasa/internal/locale"
+)
+
+func TestFormatPhoneNumber(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name   string
+		number string
+		region string
+		want   string
+	}{
+		{"US national", "5551234567", "US", "(555) 123-4567"},
+		{"UK national", "02079460958", "GB", "020 7946 0958"},
+		{"international prefix", "+442079460958", "US", "+44 20 7946 0958"},
+		{"same-region prefix", "+15551234567", "US", "(555) 123-4567"},
+		{"already formatted", "(555) 123-4567", "US", "(555) 123-4567"},
+		{"cross-border shared code", "+16135551234", "US", "+1 613-555-1234"},
+		{"garbage passthrough", "not a phone", "US", "not a phone"},
+		{"empty string", "", "US", ""},
+		{"whitespace only", "   ", "US", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := locale.FormatPhoneNumber(tt.number, tt.region)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}

nix/package.nix

@@ -14,7 +14,7 @@ buildGoModule {
   inherit pname version;
   src = gitignoreSource ../.;
   subPackages = [ "cmd/micasa" ];
-  vendorHash = "sha256-r8zgXVRss4U3EA2iSs9YqLlNlWeANJXIKP8s1O75Wmw=";
+  vendorHash = "sha256-uj8WCXGEfhTAsKRpL6ocFEblqrudq0hfKCgp8dC5fbo=";
   env.CGO_ENABLED = 0;
   preCheck = ''
     export HOME="$(mktemp -d)"