Add --emulator-platform flag and CLI_EMULATOR_PLATFORM variable (#374)

feat: add --emulator-platform flag and CLI_EMULATOR_PLATFORM variable (#374)

## Summary
Implements container platform specification for embedded emulator with comprehensive platform detection and reporting.

## Key Changes
- Added `--emulator-platform` flag to specify container platform (e.g., linux/amd64, linux/arm64)
- Added `CLI_EMULATOR_PLATFORM` read-only system variable showing actual running platform
- Updated spanemuboost to v0.2.11 for platform support
- Implemented multi-strategy platform detection with fallbacks
- Added comprehensive test coverage for platform functionality
- Updated README documentation

## Platform Detection
The implementation ensures accurate platform reporting:
- Flag controls requested platform from Docker
- System variable always shows actual running platform
- Supports partial platform specs (e.g., "linux" → "linux/arm64")

## Usage
```bash
# Auto-detect platform
spanner-mycli --embedded-emulator

# Request specific platform
spanner-mycli --embedded-emulator --emulator-platform linux/amd64

# Check actual platform
spanner> SHOW VARIABLE CLI_EMULATOR_PLATFORM;
```

Fixes #373

Co-authored-by: Gemini Code Assist <gemini-code-assist@google.com>
EOF < /dev/null

Author: apstndb

.gemini/styleguide.md

@@ -39,6 +39,49 @@ Reference: https://go.dev/blog/loopvar-preview
 - Use `t.Setenv()` instead of `os.Setenv()` for better test isolation
 - Avoid global state modifications in tests
 
+### Global State Exceptions
+
+While global state modifications should generally be avoided in tests, `slog` (structured logging) is an **accepted exception** in this project because:
+
+1. Many functions throughout the codebase use the global `slog` for logging
+2. Refactoring all functions to accept a logger parameter would be impractical
+3. The save/restore pattern provides adequate test isolation
+
+**When modifying slog in tests, you MUST use the save/restore pattern**:
+
+```go
+// Save the original logger
+oldLogger := slog.Default()
+defer slog.SetDefault(oldLogger)
+
+// Set up test-specific logger
+handler := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
+    Level: slog.LevelDebug,
+})
+slog.SetDefault(slog.New(handler))
+```
+
+This pattern ensures that global logger modifications don't affect other tests, even when running in parallel.
+
+### Package-level Test Functions
+
+In Go, test files within the same package share the same namespace. This means that helper functions defined in one test file (e.g., `main_flags_test.go`) are accessible from other test files in the same package (e.g., `main_platform_test.go`).
+
+**DO NOT** report as missing when a test uses a helper function defined in another test file of the same package:
+
+```go
+// In main_flags_test.go
+func contains(s, substr string) bool {
+    return strings.Contains(s, substr)
+}
+
+// In main_platform_test.go (same package)
+// This is valid - contains() is accessible
+if !contains(platform, tt.wantOS) {
+    // ...
+}
+```
+
 ## Code Review Focus
 
 When reviewing pull requests, please focus on:

CLAUDE.md

@@ -37,6 +37,7 @@ spanner-mycli is a personal fork of spanner-cli, designed as an interactive comm
 5. **Repository merge policy**: This repository enforces **squash merge only** via Repository Ruleset - AI assistants must use `squash` method for all automated merges
 6. **PR merge process**: Before merging, if additional commits have been pushed since the initial review, request an updated summary by commenting `/gemini summary`. An initial summary is generated automatically, so this is only for updates. Then, use `go tool gh-helper reviews wait` (**DO NOT** use `--request-review`)
 7. **Squash merge commits**: MUST include descriptive summary of PR changes in squash commit message
+8. **GitHub comment editing**: NEVER use `gh pr comment --edit-last` - always specify the exact comment ID to avoid editing the wrong comment
 
 ## Essential Commands
 
@@ -162,26 +163,31 @@ This is a simplified guide. For detailed information, refer to:
 1. **ALWAYS check**: [dev-docs/architecture-guide.md](dev-docs/architecture-guide.md) - Understand system architecture
 2. **For system variables**: [dev-docs/patterns/system-variables.md](dev-docs/patterns/system-variables.md) - Implementation patterns
 3. **For client statements**: [dev-docs/architecture-guide.md#client-side-statement-system](dev-docs/architecture-guide.md#client-side-statement-system) - Statement definition patterns
+4. **Code documentation**: When code review feedback indicates confusion about design decisions:
+   - Add clarifying comments directly in the source code
+   - Document the rationale for non-obvious choices
+   - Example: If a function returns "unknown" instead of an error, explain why in comments
 
 ### When working with GitHub issues/PRs:
 1. **ALWAYS check**: [dev-docs/issue-management.md](dev-docs/issue-management.md) - Complete GitHub workflow
-2. **For PR labels**: [dev-docs/issue-management.md#pull-request-labels](dev-docs/issue-management.md#pull-request-labels) - Release notes categorization
-3. **For insights capture**: [dev-docs/issue-management.md#knowledge-management](dev-docs/issue-management.md#knowledge-management) - PR comment best practices
-4. **For review analysis**: Use `go tool gh-helper reviews fetch` for comprehensive feedback analysis (prevents missing critical issues)
-5. **For thread replies**: Use `go tool gh-helper threads reply` - Automated thread replies
-6. **GitHub operation priority**: Use tools in this order: `gh-helper` → `gh` command → GitHub MCP (API calls)
-7. **Sub-issue operations**: Use `gh-helper issues` commands instead of GraphQL:
+2. **Language requirement**: ALL GitHub communications (PRs, issues, comments, commit messages) MUST be in English
+3. **For PR labels**: [dev-docs/issue-management.md#pull-request-labels](dev-docs/issue-management.md#pull-request-labels) - Release notes categorization
+4. **For insights capture**: [dev-docs/issue-management.md#knowledge-management](dev-docs/issue-management.md#knowledge-management) - PR comment best practices
+5. **For review analysis**: Use `go tool gh-helper reviews fetch` for comprehensive feedback analysis (prevents missing critical issues)
+6. **For thread replies**: Use `go tool gh-helper threads reply` - Automated thread replies
+7. **GitHub operation priority**: Use tools in this order: `gh-helper` → `gh` command → GitHub MCP (API calls)
+8. **Sub-issue operations**: Use `gh-helper issues` commands instead of GraphQL:
    - `issues show <parent> --include-sub` - List sub-issues and check completion
    - `issues edit <issue> --parent <parent>` - Link as sub-issue (replaces deprecated `link-parent`)
    - `issues edit <issue> --parent <new> --overwrite` - Move to different parent
    - `issues edit <issue> --unlink-parent` - Remove parent relationship
    - `issues edit <issue> --after <other>` - Reorder sub-issue after another
    - `issues edit <issue> --position first` - Move sub-issue to beginning
-8. **Safe Issue/PR content handling**: ALWAYS use stdin or variables for Issue/PR creation/updates as they commonly contain code blocks with special characters (e.g., backticks, quotes, dollar signs, parentheses)
-9. **GitHub GraphQL API**: [docs.github.com/en/graphql](https://docs.github.com/en/graphql) - Now only needed for:
-   - Complex custom field selections beyond gh-helper's output
-   - Advanced queries requiring specific field combinations
-10. **Schema introspection**: Use `go tool github-schema` instead of GraphQL:
+9. **Safe Issue/PR content handling**: ALWAYS use stdin or variables for Issue/PR creation/updates as they commonly contain code blocks with special characters (e.g., backticks, quotes, dollar signs, parentheses)
+10. **GitHub GraphQL API**: [docs.github.com/en/graphql](https://docs.github.com/en/graphql) - Now only needed for:
+    - Complex custom field selections beyond gh-helper's output
+    - Advanced queries requiring specific field combinations
+11. **Schema introspection**: Use `go tool github-schema` instead of GraphQL:
    - `go tool github-schema type <TypeName>` - Show type fields and descriptions
    - `go tool github-schema mutation <MutationName>` - Show mutation requirements
    - `go tool github-schema search <pattern>` - Search for types/fields
@@ -217,6 +223,12 @@ gh issue create --body-file tmp/issue_body.md
 1. **ALWAYS check**: [dev-docs/development-insights.md](dev-docs/development-insights.md) - Known patterns and solutions
 2. **For error handling**: [dev-docs/development-insights.md#error-handling-architecture-evolution](dev-docs/development-insights.md#error-handling-architecture-evolution)
 3. **For resource management**: [dev-docs/development-insights.md#resource-management-in-batch-processing](dev-docs/development-insights.md#resource-management-in-batch-processing)
+4. **Use `go doc` commands**: When investigating Go types, interfaces, or package APIs:
+   - `go doc <package>` - Show package documentation
+   - `go doc <package>.<type>` - Show specific type documentation
+   - `go doc -all <package>` - Show ALL exported identifiers (don't miss anything!)
+   - Example: `go doc github.com/testcontainers/testcontainers-go.GenericProvider`
+   - Example: `go doc -all github.com/testcontainers/testcontainers-go | grep Provider`
 
 ### When setting up development environment:
 1. **Start here**: Use `make worktree-setup WORKTREE_NAME=issue-123-feature` for worktree setup

README.md

@@ -121,6 +121,7 @@ spanner:
       --insecure                                          Skip TLS verification and permit plaintext gRPC. --skip-tls-verify is an alias.
       --embedded-emulator                                 Use embedded Cloud Spanner Emulator. --project, --instance, --database, --endpoint, --insecure will be automatically configured.
       --emulator-image=                                   container image for --embedded-emulator
+      --emulator-platform=                                Container platform (e.g. linux/amd64, linux/arm64) for embedded emulator
       --output-template=                                  Filepath of output template. (EXPERIMENTAL)
       --log-level=
       --log-grpc                                          Show gRPC logs
@@ -820,7 +821,7 @@ mutation_count: 9
 spanner-mycli can launch Cloud Spanner Emulator with empty database, powered by testcontainers.
 
 ```
-$ spanner-mycli --embedded-emulator [--emulator-image= gcr.io/cloud-spanner-emulator/emulator:${VERSION}]
+$ spanner-mycli --embedded-emulator [--emulator-image=gcr.io/cloud-spanner-emulator/emulator:${VERSION}] [--emulator-platform=linux/amd64]
 > SET CLI_PROMPT="%p:%i:%d%n> ";
 Empty set (0.00 sec)
 

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/apstndb/gsqlutils v0.0.0-20250517013444-d2334c88d6ae
 	github.com/apstndb/lox v0.0.0-20241212132733-62f24606dc82
 	github.com/apstndb/memebridge v0.5.0
-	github.com/apstndb/spanemuboost v0.2.10
+	github.com/apstndb/spanemuboost v0.2.11
 	github.com/apstndb/spannerplan v0.1.3
 	github.com/apstndb/spantype v0.3.8
 	github.com/apstndb/spanvalue v0.1.6

go.sum

@@ -2471,6 +2471,8 @@ github.com/apstndb/memebridge v0.5.0 h1:WaWD0Wp3Yw1BZwyvT4bIf2XsXAA+vq9ZNxUKXXV/
 github.com/apstndb/memebridge v0.5.0/go.mod h1:fPrWYKcg5/eaavD6RovT9qeq8K7bDhgLKOcGhqg6zo4=
 github.com/apstndb/spanemuboost v0.2.10 h1:4L0NtAIsJidTnNvI/+rSOv2+W4qYzICYC/klMzMB0x4=
 github.com/apstndb/spanemuboost v0.2.10/go.mod h1:KmsJ3/u6BZSA99E5jizrfSAjN3+6MSheruMsmGpLhTQ=
+github.com/apstndb/spanemuboost v0.2.11 h1:lJgklbfLo/mYfxXnIwvHn4bTwcrnFwimr0pJudERev0=
+github.com/apstndb/spanemuboost v0.2.11/go.mod h1:KmsJ3/u6BZSA99E5jizrfSAjN3+6MSheruMsmGpLhTQ=
 github.com/apstndb/spannerplan v0.1.3 h1:nFzTEvRL4yMzQeFdtWp3V0VaUidNA/o3T7HyIYIGk/U=
 github.com/apstndb/spannerplan v0.1.3/go.mod h1:iPN9r9R2AknoFnBFqA232cUO+2ZkHpk4Q1qeSAU9xEM=
 github.com/apstndb/spantype v0.3.8 h1:xy43Cclc2Hz6SL+3tZYuozOqJv6AML4Mv8cASgYo1O0=

main.go

@@ -36,6 +36,8 @@ import (
 	"cloud.google.com/go/spanner"
 	"github.com/apstndb/spanemuboost"
 	"github.com/olekukonko/tablewriter"
+	"github.com/testcontainers/testcontainers-go"
+	tcspanner "github.com/testcontainers/testcontainers-go/modules/gcloud/spanner"
 	"github.com/olekukonko/tablewriter/renderer"
 	"github.com/olekukonko/tablewriter/tw"
 
@@ -93,6 +95,7 @@ type spannerOptions struct {
 	SkipTlsVerify             *bool             `long:"skip-tls-verify" description:"Hidden alias of --insecure from original spanner-cli" hidden:"true" default-mask:"-"`
 	EmbeddedEmulator          bool              `long:"embedded-emulator" description:"Use embedded Cloud Spanner Emulator. --project, --instance, --database, --endpoint, --insecure will be automatically configured." default-mask:"-"`
 	EmulatorImage             string            `long:"emulator-image" description:"container image for --embedded-emulator" default-mask:"-"`
+	EmulatorPlatform          string            `long:"emulator-platform" description:"Container platform (e.g. linux/amd64, linux/arm64) for embedded emulator" default-mask:"-"`
 	OutputTemplate            string            `long:"output-template" description:"Filepath of output template. (EXPERIMENTAL)" default-mask:"-"`
 	LogLevel                  string            `long:"log-level" default-mask:"-"`
 	LogGrpc                   bool              `long:"log-grpc" description:"Show gRPC logs" default-mask:"-"`
@@ -214,6 +217,168 @@ func main() {
 	os.Exit(exitCodeSuccess)
 }
 
+// withPlatform creates a ContainerCustomizer that sets the container platform
+func withPlatform(platform string) testcontainers.ContainerCustomizer {
+	return testcontainers.CustomizeRequest(
+		testcontainers.GenericContainerRequest{
+			ContainerRequest: testcontainers.ContainerRequest{
+				ImagePlatform: platform,
+			},
+		},
+	)
+}
+
+// detectContainerPlatform detects the platform of a running container
+// It tries multiple methods in order of preference:
+// 1. ImageManifestDescriptor.Platform (most accurate but not always available)
+// 2. Docker API image inspect (reliable when Docker socket is accessible)
+// 3. Basic Platform field from container (usually just OS, e.g., "linux")
+// Returns "unknown" if platform detection fails - this is intentional as the function
+// must return a string value for the system variable, and "unknown" accurately
+// represents that the platform could not be determined.
+func detectContainerPlatform(ctx context.Context, container *tcspanner.Container) string {
+	inspectResult, err := container.Inspect(ctx)
+	if err != nil {
+		slog.Warn("Failed to inspect container", "error", err)
+		// Return "unknown" rather than empty string to indicate detection attempted but failed
+		return "unknown"
+	}
+
+	// Debug log the inspect result
+	slog.Debug("Container inspect result",
+		"Platform", inspectResult.Platform,
+		"ImageManifestDescriptor", inspectResult.ImageManifestDescriptor != nil,
+		"Image", inspectResult.Image,
+		"ConfigNotNil", inspectResult.Config != nil,
+	)
+	
+	// Log config details if available
+	if inspectResult.Config != nil {
+		slog.Debug("Container config details",
+			"Image", inspectResult.Config.Image,
+			"Labels", inspectResult.Config.Labels,
+		)
+	}
+	
+	// Method 1: Try ImageManifestDescriptor (OCI standard)
+	if inspectResult.ImageManifestDescriptor != nil && inspectResult.ImageManifestDescriptor.Platform != nil {
+		p := inspectResult.ImageManifestDescriptor.Platform
+		slog.Debug("ImageManifestDescriptor.Platform details",
+			"OS", p.OS,
+			"Architecture", p.Architecture,
+			"Variant", p.Variant,
+			"OSVersion", p.OSVersion,
+			"OSFeatures", p.OSFeatures,
+		)
+		platform := p.OS + "/" + p.Architecture
+		if p.Variant != "" {
+			platform += "/" + p.Variant
+		}
+		return platform
+	}
+
+	// Method 2: Try Docker API image inspect
+	slog.Debug("ImageManifestDescriptor not available, trying image inspect")
+	if inspectResult.Config != nil && inspectResult.Config.Image != "" {
+		// Get provider for image inspection.
+		// IMPORTANT: GetProvider() creates a NEW provider instance each time, not a singleton.
+		// We must close it to avoid resource leaks.
+		// See: https://github.com/testcontainers/testcontainers-go/blob/main/provider.go
+		genericProvider, err := testcontainers.ProviderDefault.GetProvider()
+		if err != nil {
+			slog.Debug("Failed to get testcontainers provider", "error", err)
+		} else {
+			defer func() {
+				if err := genericProvider.Close(); err != nil {
+					slog.Debug("Failed to close testcontainers provider", "error", err)
+				}
+			}()
+			
+			platform := inspectImagePlatform(ctx, inspectResult.Config.Image, genericProvider)
+			if platform != "" {
+				return platform
+			}
+		}
+	}
+
+	// Method 3: Fallback to basic platform field
+	if inspectResult.Platform != "" {
+		slog.Debug("Using basic Platform field", "Platform", inspectResult.Platform)
+		return inspectResult.Platform
+	}
+
+	// All detection methods failed - return "unknown" to indicate this state
+	return "unknown"
+}
+
+// inspectImagePlatform uses container runtime API (Docker/Podman) to get platform information from an image.
+// The provider parameter should be obtained from testcontainers.ProviderDefault.GetProvider().
+// The caller is responsible for managing the provider lifecycle.
+func inspectImagePlatform(ctx context.Context, imageName string, provider testcontainers.GenericProvider) string {
+	slog.Debug("inspectImagePlatform called", "imageName", imageName)
+	
+	// Both Docker and Podman providers return *DockerProvider type, even for Podman.
+	// This is because Podman provides Docker-compatible API.
+	dockerProvider, ok := provider.(*testcontainers.DockerProvider)
+	if !ok {
+		slog.Debug("Provider is not a DockerProvider", "type", fmt.Sprintf("%T", provider))
+		return ""
+	}
+	
+	// The provider embeds *client.Client directly (not as a field), so we can access it
+	// using provider.Client() which returns the embedded Docker/Podman client.
+	dockerClient := dockerProvider.Client()
+	slog.Debug("Using container runtime client from testcontainers provider")
+	
+	// Use a context with a timeout for Docker API calls to prevent hangs
+	// if the container runtime is unresponsive
+	inspectCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	
+	// Log Docker client info
+	info, err := dockerClient.Info(inspectCtx)
+	if err != nil {
+		slog.Debug("Failed to get Docker info", "error", err)
+	} else {
+		slog.Debug("Docker client info", 
+			"ServerVersion", info.ServerVersion,
+			"OSType", info.OSType,
+			"Architecture", info.Architecture)
+	}
+	
+	imageInspect, err := dockerClient.ImageInspect(inspectCtx, imageName)
+	if err != nil {
+		slog.Debug("Image inspect failed", 
+			"error", err,
+			"imageName", imageName)
+		return ""
+	}
+
+	slog.Debug("Image inspect successful",
+		"imageName", imageName,
+		"Architecture", imageInspect.Architecture,
+		"Os", imageInspect.Os,
+		"Variant", imageInspect.Variant,
+		"ID", imageInspect.ID,
+	)
+	
+	// Validate that we have the required fields
+	if imageInspect.Os == "" || imageInspect.Architecture == "" {
+		slog.Debug("Image inspect result missing Os or Architecture", 
+			"imageName", imageName, 
+			"Os", imageInspect.Os, 
+			"Architecture", imageInspect.Architecture)
+		return ""
+	}
+	
+	platform := imageInspect.Os + "/" + imageInspect.Architecture
+	if imageInspect.Variant != "" {
+		platform += "/" + imageInspect.Variant
+	}
+	slog.Debug("Returning platform", "platform", platform)
+	return platform
+}
+
 // run executes the main functionality of the application.
 // It returns an error that may contain an exit code.
 // Use GetExitCode(err) to determine the appropriate exit code.
@@ -270,12 +435,25 @@ func run(ctx context.Context, opts *spannerOptions) error {
 			emulatorOpts = append(emulatorOpts, spanemuboost.EnableInstanceAutoConfigOnly())
 		}
 
+		// Add platform customizer if specified
+		if opts.EmulatorPlatform != "" {
+			emulatorOpts = append(emulatorOpts, spanemuboost.WithContainerCustomizers(withPlatform(opts.EmulatorPlatform)))
+		}
+		
 		container, teardown, err := spanemuboost.NewEmulator(ctx, emulatorOpts...)
 		if err != nil {
 			return fmt.Errorf("failed to start Cloud Spanner Emulator: %w", err)
 		}
 		defer teardown()
 
+		// Always detect the actual platform the container is running on
+		// The --emulator-platform flag only controls what platform is requested,
+		// but we want to show the actual platform in CLI_EMULATOR_PLATFORM
+		sysVars.EmulatorPlatform = detectContainerPlatform(ctx, container)
+		slog.Debug("Detected container platform", 
+			"requested", opts.EmulatorPlatform,
+			"actual", sysVars.EmulatorPlatform)
+
 		sysVars.Endpoint = container.URI()
 		sysVars.WithoutAuthentication = true
 	}