BREAKING: Simplify export template variable naming (#116)

peteski22 · web-flow · commit 865f125cfaec · 2025-08-01T20:58:18.000+01:00
Remove __ARG__ suffix from command-line argument template variables to create  cleaner, more consistent naming across environment variables and arguments.

BREAKING CHANGES:
  - Template variables for command-line arguments changed from
    MCPD__{SERVER}__ARG__{VAR} to MCPD__{SERVER}__{VAR}
  - Both environment variables and command-line arguments now use the same
    naming scheme: MCPD__{SERVER_NAME}__{VARIABLE_NAME}

Migration:
  - Users with existing CI/CD pipelines using exported variables must rename
    their environment variables to remove the __ARG__ suffix if they re-create files from export
  - Example: MCPD__SERVER__ARG__TOKEN → MCPD__SERVER__TOKEN

Other improvements:
  - Consolidated template generation logic to use single source of truth
  - Added documentation for variable name collision handling
  - Updated command help text to reflect unified naming scheme
diff --git a/cmd/config/export/export.go b/cmd/config/export/export.go
@@ -75,8 +75,8 @@ func (c *Cmd) longDescription() string {
 		"execution context file (e.g. `~/.config/mcpd/secrets.dev.toml`), the export command outputs two files:\n\n" +
 		"Environment Contract:\n\n" +
 		"Lists all required and configured environment variables as secure, namespaced placeholders:\n\n" +
-		"`MCPD__{SERVER_NAME}__{ENV_VAR}` - Creates placeholders for command line arguments to be populated with env vars\n\n" +
-		"`MCPD__{SERVER_NAME}__ARG_{ARG_NAME}` - This file is intended for the platform operator or CI/CD system\n\n" +
+		"`MCPD__{SERVER_NAME}__{VAR_NAME}` - Creates placeholders for both environment variables and command line arguments to be populated with env vars\n\n" +
+		"This file is intended for the platform operator or CI/CD system\n\n" +
 		"Portable Execution Context:\n\n" +
 		"- A new secrets `.toml` file that defines sanitized runtime args and env sections for each server using the " +
 		"placeholders aligned with the environment contract\n" +
diff --git a/cmd/config/export/testdata/basic_export/context.test.toml b/cmd/config/export/testdata/basic_export/context.test.toml
@@ -1,6 +1,6 @@
 [servers]
   [servers.test-server]
-    args = ["--verbose", "--debug", "--config=${MCPD__TEST_SERVER__ARG__CONFIG}", "--port=${MCPD__TEST_SERVER__ARG__PORT}", "--extra=${MCPD__TEST_SERVER__ARG__EXTRA}"]
+    args = ["--verbose", "--debug", "--config=${MCPD__TEST_SERVER__CONFIG}", "--port=${MCPD__TEST_SERVER__PORT}", "--extra=${MCPD__TEST_SERVER__EXTRA}"]
     [servers.test-server.env]
       API_KEY = "${MCPD__TEST_SERVER__API_KEY}"
       EXTRA_VAR = "${MCPD__TEST_SERVER__EXTRA_VAR}"
diff --git a/cmd/config/export/testdata/basic_export/contract.test.env b/cmd/config/export/testdata/basic_export/contract.test.env
@@ -1,6 +1,6 @@
 MCPD__TEST_SERVER__API_KEY=${MCPD__TEST_SERVER__API_KEY}
-MCPD__TEST_SERVER__ARG__CONFIG=${MCPD__TEST_SERVER__ARG__CONFIG}
-MCPD__TEST_SERVER__ARG__EXTRA=${MCPD__TEST_SERVER__ARG__EXTRA}
-MCPD__TEST_SERVER__ARG__PORT=${MCPD__TEST_SERVER__ARG__PORT}
+MCPD__TEST_SERVER__CONFIG=${MCPD__TEST_SERVER__CONFIG}
+MCPD__TEST_SERVER__EXTRA=${MCPD__TEST_SERVER__EXTRA}
 MCPD__TEST_SERVER__EXTRA_VAR=${MCPD__TEST_SERVER__EXTRA_VAR}
+MCPD__TEST_SERVER__PORT=${MCPD__TEST_SERVER__PORT}
 MCPD__TEST_SERVER__SECRET=${MCPD__TEST_SERVER__SECRET}
diff --git a/cmd/config/export/testdata/github_server_hyphens/context.test.toml b/cmd/config/export/testdata/github_server_hyphens/context.test.toml
@@ -1,6 +1,6 @@
 [servers]
   [servers.github-server]
-    args = ["--org=${MCPD__GITHUB_SERVER__ARG__ORG}", "--api-version=${MCPD__GITHUB_SERVER__ARG__API_VERSION}"]
+    args = ["--org=${MCPD__GITHUB_SERVER__ORG}", "--api-version=${MCPD__GITHUB_SERVER__API_VERSION}"]
     [servers.github-server.env]
       DEBUG = "${MCPD__GITHUB_SERVER__DEBUG}"
       GITHUB_TOKEN = "${MCPD__GITHUB_SERVER__GITHUB_TOKEN}"
diff --git a/cmd/config/export/testdata/github_server_hyphens/contract.test.env b/cmd/config/export/testdata/github_server_hyphens/contract.test.env
@@ -1,4 +1,4 @@
-MCPD__GITHUB_SERVER__ARG__API_VERSION=${MCPD__GITHUB_SERVER__ARG__API_VERSION}
-MCPD__GITHUB_SERVER__ARG__ORG=${MCPD__GITHUB_SERVER__ARG__ORG}
+MCPD__GITHUB_SERVER__API_VERSION=${MCPD__GITHUB_SERVER__API_VERSION}
 MCPD__GITHUB_SERVER__DEBUG=${MCPD__GITHUB_SERVER__DEBUG}
-MCPD__GITHUB_SERVER__GITHUB_TOKEN=${MCPD__GITHUB_SERVER__GITHUB_TOKEN}
+MCPD__GITHUB_SERVER__GITHUB_TOKEN=${MCPD__GITHUB_SERVER__GITHUB_TOKEN}
+MCPD__GITHUB_SERVER__ORG=${MCPD__GITHUB_SERVER__ORG}
diff --git a/cmd/config/export/testdata/minimal_server_required_only/context.test.toml b/cmd/config/export/testdata/minimal_server_required_only/context.test.toml
@@ -1,5 +1,5 @@
 [servers]
   [servers.minimal-server]
-    args = ["--required-arg=${MCPD__MINIMAL_SERVER__ARG__REQUIRED_ARG}"]
+    args = ["--required-arg=${MCPD__MINIMAL_SERVER__REQUIRED_ARG}"]
     [servers.minimal-server.env]
       REQUIRED_VAR = "${MCPD__MINIMAL_SERVER__REQUIRED_VAR}"
diff --git a/cmd/config/export/testdata/minimal_server_required_only/contract.test.env b/cmd/config/export/testdata/minimal_server_required_only/contract.test.env
@@ -1,2 +1,2 @@
-MCPD__MINIMAL_SERVER__ARG__REQUIRED_ARG=${MCPD__MINIMAL_SERVER__ARG__REQUIRED_ARG}
+MCPD__MINIMAL_SERVER__REQUIRED_ARG=${MCPD__MINIMAL_SERVER__REQUIRED_ARG}
 MCPD__MINIMAL_SERVER__REQUIRED_VAR=${MCPD__MINIMAL_SERVER__REQUIRED_VAR}
diff --git a/cmd/config/export/testdata/multiple_servers/context.test.toml b/cmd/config/export/testdata/multiple_servers/context.test.toml
@@ -1,6 +1,6 @@
 [servers]
   [servers.server-a]
-    args = ["--token=${MCPD__SERVER_A__ARG__TOKEN}", "--port=${MCPD__SERVER_A__ARG__PORT}"]
+    args = ["--token=${MCPD__SERVER_A__TOKEN}", "--port=${MCPD__SERVER_A__PORT}"]
   [servers.server-b]
     [servers.server-b.env]
       DATABASE_URL = "${MCPD__SERVER_B__DATABASE_URL}"
diff --git a/cmd/config/export/testdata/multiple_servers/contract.test.env b/cmd/config/export/testdata/multiple_servers/contract.test.env
@@ -1,4 +1,4 @@
-MCPD__SERVER_A__ARG__PORT=${MCPD__SERVER_A__ARG__PORT}
-MCPD__SERVER_A__ARG__TOKEN=${MCPD__SERVER_A__ARG__TOKEN}
+MCPD__SERVER_A__PORT=${MCPD__SERVER_A__PORT}
+MCPD__SERVER_A__TOKEN=${MCPD__SERVER_A__TOKEN}
 MCPD__SERVER_B__DATABASE_URL=${MCPD__SERVER_B__DATABASE_URL}
 MCPD__SERVER_B__DEBUG_MODE=${MCPD__SERVER_B__DEBUG_MODE}
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -62,3 +62,34 @@ Options:
 !!! warning "Setting Log Path"
     Log entries will be discarded by default, unless a log path is configured. 
     Output intended for the terminal is still emitted.
+
+---
+
+## Configuration Export
+
+The `mcpd config export` command generates portable configuration files for deployment across different environments. It creates template variables using the naming pattern `MCPD__{SERVER_NAME}__{VARIABLE_NAME}`.
+
+### Template Variable Generation
+
+Environment variables and command-line arguments are both converted to template variables using the same naming scheme:
+
+- Environment variable`DATABASE_URL` becomes `MCPD__{SERVER_NAME}__DATABASE_URL`  
+- Command-line argument `--database-url` becomes `MCPD__{SERVER_NAME}__DATABASE_URL`
+
+### Variable Name Collisions
+
+!!! danger "Naming Collisions"
+    If a server has both an environment variable and a command-line argument that normalize to the same name (e.g., `DATABASE_URL` and `--database-url`), they will generate the same template variable name.
+    
+In most cases, this is intentional, the same configuration value is being used in different ways. The collision results in a single template variable that can be used for both the environment variable and command-line argument.
+    
+#### Example collision
+
+```toml
+[[servers]]
+name = "example"
+required_env = ["DATABASE_URL"]
+required_args = ["--database-url"]
+```
+    
+Both will use the template variable `MCPD__EXAMPLE__DATABASE_URL` in the generated files.
diff --git a/internal/runtime/export_arg_transform.go b/internal/runtime/export_arg_transform.go
@@ -10,9 +10,9 @@ import (
 type valueArgTransformation struct {
 	Raw             string // --foo=bar
 	Name            string // foo
-	EnvVarName      string // MCPD__TEST__ARG__FOO
-	EnvVarReference string // ${MCPD__TEST__ARG__FOO}
-	FormattedArg    string // --foo=${MCPD__TEST__ARG__FOO}
+	EnvVarName      string // MCPD__TEST__FOO
+	EnvVarReference string // ${MCPD__TEST__FOO}
+	FormattedArg    string // --foo=${MCPD__TEST__FOO}
 }
 
 // normalizeForEnvVarName converts string name (e.g. app name, env var name) to uppercase with underscores
@@ -41,12 +41,12 @@ func extractArgNameWithPrefix(rawArg string) string {
 	return rawArg
 }
 
-// buildEnvVarName creates the environment variable name: MCPD__TEST__ARG__FOO
+// buildEnvVarName creates the environment variable name: MCPD__TEST__FOO
 func buildEnvVarName(appName, serverName, argName string) string {
 	sanitizedAppName := normalizeForEnvVarName(appName)
 	sanitizedServer := normalizeForEnvVarName(serverName)
 	sanitizedArg := strings.ToUpper(strings.ReplaceAll(argName, "-", "_"))
-	return fmt.Sprintf("%s__%s__ARG__%s", sanitizedAppName, sanitizedServer, sanitizedArg)
+	return fmt.Sprintf("%s__%s__%s", sanitizedAppName, sanitizedServer, sanitizedArg)
 }
 
 // transformValueArg converts a raw CLI argument into its transformed representations.
@@ -57,7 +57,7 @@ func transformValueArg(appName, serverName, rawArg string) *valueArgTransformati
 	envVarName := buildEnvVarName(appName, serverName, argName)
 	argPrefix := extractArgNameWithPrefix(rawArg)
 
-	// Value argument: --foo=bar => --foo=${MCPD__TEST__ARG__FOO}
+	// Value argument: --foo=bar => --foo=${MCPD__TEST__FOO}
 	formattedArg := fmt.Sprintf("%s=${%s}", argPrefix, envVarName)
 
 	return &valueArgTransformation{
diff --git a/internal/runtime/export_arg_transform_test.go b/internal/runtime/export_arg_transform_test.go
@@ -201,35 +201,35 @@ func TestBuildEnvVarName(t *testing.T) {
 			appName:    "mcpd",
 			serverName: "test",
 			argName:    "foo",
-			expected:   "MCPD__TEST__ARG__FOO",
+			expected:   "MCPD__TEST__FOO",
 		},
 		{
 			name:       "hyphenated server name",
 			appName:    "mcpd",
 			serverName: "my-server",
 			argName:    "foo",
-			expected:   "MCPD__MY_SERVER__ARG__FOO",
+			expected:   "MCPD__MY_SERVER__FOO",
 		},
 		{
 			name:       "hyphenated arg name",
 			appName:    "mcpd",
 			serverName: "test",
 			argName:    "my-arg",
-			expected:   "MCPD__TEST__ARG__MY_ARG",
+			expected:   "MCPD__TEST__MY_ARG",
 		},
 		{
 			name:       "all hyphenated",
 			appName:    "my-app",
 			serverName: "my-server",
 			argName:    "my-arg",
-			expected:   "MY_APP__MY_SERVER__ARG__MY_ARG",
+			expected:   "MY_APP__MY_SERVER__MY_ARG",
 		},
 		{
 			name:       "mixed case inputs",
 			appName:    "McPd",
 			serverName: "Test-Server",
 			argName:    "My-Arg",
-			expected:   "MCPD__TEST_SERVER__ARG__MY_ARG",
+			expected:   "MCPD__TEST_SERVER__MY_ARG",
 		},
 	}
 
@@ -261,9 +261,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "--foo=bar",
 				Name:            "foo",
-				EnvVarName:      "MCPD__TEST__ARG__FOO",
-				EnvVarReference: "${MCPD__TEST__ARG__FOO}",
-				FormattedArg:    "--foo=${MCPD__TEST__ARG__FOO}",
+				EnvVarName:      "MCPD__TEST__FOO",
+				EnvVarReference: "${MCPD__TEST__FOO}",
+				FormattedArg:    "--foo=${MCPD__TEST__FOO}",
 			},
 		},
 		{
@@ -274,9 +274,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "--my-arg",
 				Name:            "my-arg",
-				EnvVarName:      "MCPD__TEST__ARG__MY_ARG",
-				EnvVarReference: "${MCPD__TEST__ARG__MY_ARG}",
-				FormattedArg:    "--my-arg=${MCPD__TEST__ARG__MY_ARG}",
+				EnvVarName:      "MCPD__TEST__MY_ARG",
+				EnvVarReference: "${MCPD__TEST__MY_ARG}",
+				FormattedArg:    "--my-arg=${MCPD__TEST__MY_ARG}",
 			},
 		},
 		{
@@ -287,9 +287,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "--my-arg=123",
 				Name:            "my-arg",
-				EnvVarName:      "MCPD__TEST__ARG__MY_ARG",
-				EnvVarReference: "${MCPD__TEST__ARG__MY_ARG}",
-				FormattedArg:    "--my-arg=${MCPD__TEST__ARG__MY_ARG}",
+				EnvVarName:      "MCPD__TEST__MY_ARG",
+				EnvVarReference: "${MCPD__TEST__MY_ARG}",
+				FormattedArg:    "--my-arg=${MCPD__TEST__MY_ARG}",
 			},
 		},
 		{
@@ -300,9 +300,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "--config=file.json",
 				Name:            "config",
-				EnvVarName:      "MCPD__MY_SERVER__ARG__CONFIG",
-				EnvVarReference: "${MCPD__MY_SERVER__ARG__CONFIG}",
-				FormattedArg:    "--config=${MCPD__MY_SERVER__ARG__CONFIG}",
+				EnvVarName:      "MCPD__MY_SERVER__CONFIG",
+				EnvVarReference: "${MCPD__MY_SERVER__CONFIG}",
+				FormattedArg:    "--config=${MCPD__MY_SERVER__CONFIG}",
 			},
 		},
 		{
@@ -313,9 +313,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "-f=file.txt",
 				Name:            "f",
-				EnvVarName:      "MCPD__TEST__ARG__F",
-				EnvVarReference: "${MCPD__TEST__ARG__F}",
-				FormattedArg:    "-f=${MCPD__TEST__ARG__F}",
+				EnvVarName:      "MCPD__TEST__F",
+				EnvVarReference: "${MCPD__TEST__F}",
+				FormattedArg:    "-f=${MCPD__TEST__F}",
 			},
 		},
 		{
@@ -326,9 +326,9 @@ func TestTransformArg(t *testing.T) {
 			expected: &valueArgTransformation{
 				Raw:             "--empty=",
 				Name:            "empty",
-				EnvVarName:      "MCPD__TEST__ARG__EMPTY",
-				EnvVarReference: "${MCPD__TEST__ARG__EMPTY}",
-				FormattedArg:    "--empty=${MCPD__TEST__ARG__EMPTY}",
+				EnvVarName:      "MCPD__TEST__EMPTY",
+				EnvVarReference: "${MCPD__TEST__EMPTY}",
+				FormattedArg:    "--empty=${MCPD__TEST__EMPTY}",
 			},
 		},
 	}
diff --git a/internal/runtime/server.go b/internal/runtime/server.go
@@ -197,25 +197,20 @@ func envVarsToContract(envs map[string]string) map[string]string {
 // exportEnvVars generates environment variable placeholders for both required and runtime env vars.
 // Returns a map where keys are env var names (e.g., "API_KEY") and values are placeholder references (e.g., "${MCPD__SERVER__API_KEY}").
 func (s *Server) exportEnvVars(appName string) map[string]string {
-	appName = normalizeForEnvVarName(appName)
-
-	parseEnvVar := func(serverName string, envVarName string) string {
-		key := strings.ToUpper(envVarName)
-		return fmt.Sprintf("${%s__%s__%s}", appName, normalizeForEnvVarName(serverName), key)
-	}
-
 	envs := map[string]string{}
 
 	// Any required env names from config should be included.
 	for _, k := range s.RequiredEnvVars {
-		envs[k] = parseEnvVar(s.Name(), k)
+		envVarName := buildEnvVarName(appName, s.Name(), k)
+		envs[k] = fmt.Sprintf("${%s}", envVarName)
 	}
 
 	// Update with any vars that were set in runtime execution context config.
 	for k := range s.Env {
 		// Skip if we've already captured this variable via required env vars.
 		if _, ok := envs[k]; !ok {
-			envs[k] = parseEnvVar(s.Name(), k)
+			envVarName := buildEnvVarName(appName, s.Name(), k)
+			envs[k] = fmt.Sprintf("${%s}", envVarName)
 		}
 	}
 
diff --git a/internal/runtime/server_test.go b/internal/runtime/server_test.go

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		`-MCPD__MINIMAL_SERVER__ARG__REQUIRED_ARG=${MCPD__MINIMAL_SERVER__ARG__REQUIRED_ARG}`
	`1`	`+MCPD__MINIMAL_SERVER__REQUIRED_ARG=${MCPD__MINIMAL_SERVER__REQUIRED_ARG}`
`2`	`2`	`MCPD__MINIMAL_SERVER__REQUIRED_VAR=${MCPD__MINIMAL_SERVER__REQUIRED_VAR}`