feat(tmpl): replace "auto" sentinel with {{AUTO_*}} placeholders

Using explicit {{AUTO_PORT}}, {{AUTO_UUID}}, {{AUTO_PASSWORD}}, etc.
prevents false matches when a config legitimately contains the word "auto".

- resolveAuto checks {{AUTO_PORT/TCP_PORT/UDP_PORT/QUIC_PORT/SOCKS_PORT/UPSTREAM_PORT}}
- {{AUTO_UUID}} and {{AUTO_PASSWORD}} for credential generation
- examples/run.json updated to new placeholder syntax
- New test: TestRender_AutoLiteralPreserved verifies "auto" passthrough
- Docs updated in run-json.md and templates.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hiddifydeveloper

docs/run-json.md

@@ -167,13 +167,21 @@ to the template.
 
 ### Auto-resolution
 
-`"auto"` in a vars value triggers runtime resolution:
+Use `{{AUTO_*}}` placeholders as var values to trigger runtime resolution:
 
-| Key | Resolution |
+| Value | Resolution |
 |---|---|
-| `PORT`, `TCP_PORT`, `UDP_PORT`, `QUIC_PORT`, `SOCKS_PORT`, `UPSTREAM_PORT` | Random free port |
-| `UUID` | `uuid.New()` v4 |
-| `PASSWORD` | 16 random bytes, hex-encoded |
+| `{{AUTO_PORT}}` | Random free TCP port |
+| `{{AUTO_TCP_PORT}}` | Random free TCP port |
+| `{{AUTO_UDP_PORT}}` | Random free TCP port |
+| `{{AUTO_QUIC_PORT}}` | Random free TCP port |
+| `{{AUTO_SOCKS_PORT}}` | Random free TCP port |
+| `{{AUTO_UPSTREAM_PORT}}` | Random free TCP port |
+| `{{AUTO_UUID}}` | `uuid.New()` v4 |
+| `{{AUTO_PASSWORD}}` | 16 random bytes, hex-encoded |
+
+Unlike the old `"auto"` string, these placeholders are unambiguous — a config
+value that legitimately contains the word `"auto"` is left untouched.
 
 Full placeholder reference: [placeholders.md](placeholders.md).
 

docs/templates.md

@@ -217,16 +217,28 @@ same directory as the original.
 
 ## Auto-resolved vars
 
-Set a var to `"auto"` in `run.json` and the runner fills it in:
+Use `{{AUTO_*}}` placeholders as var values in `run.json` and the runner fills them in:
 
-| Var | Resolved to |
+```json5
+"vars": {
+  "PORT":       "{{AUTO_PORT}}",
+  "SOCKS_PORT": "{{AUTO_SOCKS_PORT}}",
+  "UUID":       "{{AUTO_UUID}}",
+  "PASSWORD":   "{{AUTO_PASSWORD}}"
+}
+```
+
+| Placeholder | Resolved to |
 |---|---|
-| `PORT`, `TCP_PORT`, `UDP_PORT`, `QUIC_PORT` | Random free port (each) |
-| `SOCKS_PORT`, `UPSTREAM_PORT` | Random free port |
-| `UUID` | UUID v4 (`uuid.New()`) |
-| `PASSWORD` | 16 random bytes, hex-encoded |
-| `LISTEN_SERVER` | Copied from `SERVER` when unset |
-| `LOG_LEVEL` | `"error"` when unset |
+| `{{AUTO_PORT}}`, `{{AUTO_TCP_PORT}}`, `{{AUTO_UDP_PORT}}`, `{{AUTO_QUIC_PORT}}` | Random free port |
+| `{{AUTO_SOCKS_PORT}}`, `{{AUTO_UPSTREAM_PORT}}` | Random free port |
+| `{{AUTO_UUID}}` | UUID v4 (`uuid.New()`) |
+| `{{AUTO_PASSWORD}}` | 16 random bytes, hex-encoded |
+| `LISTEN_SERVER` | Copied from `SERVER` when unset (automatic) |
+| `LOG_LEVEL` | `"error"` when unset (automatic) |
+
+Using explicit placeholders means a var value that legitimately contains the
+word `"auto"` is never misinterpreted.
 
 Full list: [placeholders.md](placeholders.md).
 

examples/run.json

@@ -8,21 +8,21 @@
     {
       "TITLE":      "local",
       "SERVER":     "127.0.0.1",
-      "PORT":       "auto",
-      "SOCKS_PORT": "auto",
-      "UUID":       "auto",
-      "PASSWORD":   "auto",
+      "PORT":       "{{AUTO_PORT}}",
+      "SOCKS_PORT": "{{AUTO_SOCKS_PORT}}",
+      "UUID":       "{{AUTO_UUID}}",
+      "PASSWORD":   "{{AUTO_PASSWORD}}",
       // "HOST_NAME": "example.com",
       // "SNI_NAME":  "example.com",
     },
     // Add more entries to test against additional servers, e.g.:
     // {
     //   "TITLE":  "remote",
     //   "SERVER": "203.0.113.10",
-    //   "PORT":   "auto",
-    //   "SOCKS_PORT": "auto",
-    //   "UUID":   "auto",
-    //   "PASSWORD": "auto",
+    //   "PORT":   "{{AUTO_PORT}}",
+    //   "SOCKS_PORT": "{{AUTO_SOCKS_PORT}}",
+    //   "UUID":   "{{AUTO_UUID}}",
+    //   "PASSWORD": "{{AUTO_PASSWORD}}",
     // },
   ],
 

internal/runner/config_test.go

@@ -31,7 +31,7 @@ func TestLoadRunConfig_InheritanceVars(t *testing.T) {
 		"checks":      []string{"dns", "http"},
 		"timeout_sec": 30,
 		"vars": []interface{}{
-			map[string]interface{}{"TITLE": "T1", "SERVER": "127.0.0.1", "PORT": "auto", "SOCKS_PORT": "auto"},
+			map[string]interface{}{"TITLE": "T1", "SERVER": "127.0.0.1", "PORT": "{{AUTO_PORT}}", "SOCKS_PORT": "{{AUTO_SOCKS_PORT}}"},
 		},
 	})
 
@@ -48,8 +48,8 @@ func TestLoadRunConfig_InheritanceVars(t *testing.T) {
 		"server_config": "server.json",
 		"client_config": "client.json",
 		"vars": []interface{}{
-			map[string]interface{}{"TITLE": "plain-tls", "TLS": "1", "UUID": "auto"},
-			map[string]interface{}{"TITLE": "vless-flow", "TLS": "1", "UUID": "auto", "VLESS_FLOW": "xtls-rprx-vision"},
+			map[string]interface{}{"TITLE": "plain-tls", "TLS": "1", "UUID": "{{AUTO_UUID}}"},
+			map[string]interface{}{"TITLE": "vless-flow", "TLS": "1", "UUID": "{{AUTO_UUID}}", "VLESS_FLOW": "xtls-rprx-vision"},
 		},
 	})
 

internal/tmpl/tmpl.go

@@ -24,11 +24,12 @@
 //
 // # Auto-resolved vars
 //
-// Set a var's value to "auto" in run.json and the runner picks:
+// Set a var's value to an AUTO placeholder in run.json and the runner picks:
 //
-//	PORT, SOCKS_PORT, UPSTREAM_PORT  →  random free TCP port
-//	UUID                              →  new UUID v4
-//	PASSWORD                          →  16 random bytes, hex-encoded
+//	{{AUTO_PORT}}, {{AUTO_TCP_PORT}}, {{AUTO_UDP_PORT}},
+//	{{AUTO_QUIC_PORT}}, {{AUTO_SOCKS_PORT}}, {{AUTO_UPSTREAM_PORT}}  →  random free TCP port
+//	{{AUTO_UUID}}      →  new UUID v4
+//	{{AUTO_PASSWORD}}  →  16 random bytes, hex-encoded
 package tmpl
 
 import (
@@ -85,8 +86,8 @@ func init() {
 	})
 }
 
-// Render renders src as a Pongo2/Jinja2 template against vars, resolves "auto"
-// values, then optionally strips JSON5 extensions.
+// Render renders src as a Pongo2/Jinja2 template against vars, resolves {{AUTO_*}}
+// sentinels, then optionally strips JSON5 extensions.
 //
 // stripJSON5 (optional, default true): when false, JSON5 comments and trailing
 // commas are kept in the output — useful for cores that accept JSON5, or for
@@ -95,7 +96,7 @@ func init() {
 // Returns: rendered bytes, fully-resolved vars map, error.
 func Render(src []byte, vars map[string]string, stripJSON5 ...bool) ([]byte, map[string]string, error) {
 	doStrip := len(stripJSON5) == 0 || stripJSON5[0]
-	// 1. Resolve "auto" vars before rendering so the template sees real values.
+	// 1. Resolve {{AUTO_*}} sentinels before rendering so the template sees real values.
 	resolved, err := resolveAuto(vars)
 	if err != nil {
 		return nil, nil, err
@@ -206,16 +207,22 @@ func buildContext(resolved map[string]string) pongo2.Context {
 	return ctx
 }
 
-// resolveAuto returns a copy of vars with "auto" values resolved.
+// autoPlaceholder returns the {{AUTO_KEY}} sentinel for a given var name.
+// Used when checking if a var value requests auto-resolution.
+func autoPlaceholder(key string) string { return "{{AUTO_" + key + "}}" }
+
+// resolveAuto returns a copy of vars with {{AUTO_*}} sentinels resolved.
+// Using explicit placeholders (instead of the bare string "auto") avoids
+// false matches when a config legitimately contains the word "auto".
 func resolveAuto(vars map[string]string) (map[string]string, error) {
 	out := make(map[string]string, len(vars))
 	for k, v := range vars {
 		out[k] = v
 	}
 
-	// All recognized port vars — "auto" gets a random free port each.
+	// Port vars — {{AUTO_PORT}} etc. get a random free port each.
 	for _, k := range []string{"PORT", "TCP_PORT", "UDP_PORT", "SOCKS_PORT", "UPSTREAM_PORT", "QUIC_PORT"} {
-		if out[k] == "auto" {
+		if out[k] == autoPlaceholder(k) {
 			p, err := freePort()
 			if err != nil {
 				return nil, fmt.Errorf("tmpl: free port for %s: %w", k, err)
@@ -238,24 +245,24 @@ func resolveAuto(vars map[string]string) (map[string]string, error) {
 
 	// Built-in protocol defaults — override in vars if needed.
 	builtinDefaults := map[string]string{
-		"LOG_LEVEL":   "error",
-		"VLESS_ENC":   "none",
-		"VLESS_DEC":   "none",
-		"VLESS_FLOW":  "",
-		"HOST_NAME":   "example.com",
-		"SNI_NAME":    "example.com",
+		"LOG_LEVEL":  "error",
+		"VLESS_ENC":  "none",
+		"VLESS_DEC":  "none",
+		"VLESS_FLOW": "",
+		"HOST_NAME":  "example.com",
+		"SNI_NAME":   "example.com",
 	}
 	for k, def := range builtinDefaults {
 		if out[k] == "" {
 			out[k] = def
 		}
 	}
 
-	if out["UUID"] == "auto" {
+	if out["UUID"] == autoPlaceholder("UUID") {
 		out["UUID"] = uuid.New().String()
 	}
 
-	if out["PASSWORD"] == "auto" {
+	if out["PASSWORD"] == autoPlaceholder("PASSWORD") {
 		b := make([]byte, 16)
 		if _, err := rand.Read(b); err != nil {
 			return nil, fmt.Errorf("tmpl: rand password: %w", err)

internal/tmpl/tmpl_test.go

@@ -98,29 +98,43 @@ func TestRender_CommentInsideString(t *testing.T) {
 // --- auto resolution ---
 
 func TestRender_AutoPort(t *testing.T) {
-	out, resolved, _ := Render([]byte(`{"port":{{PORT}}}`), map[string]string{"PORT": "auto"})
-	if bytes.Contains(out, []byte("auto")) {
-		t.Errorf("auto not resolved: %s", out)
+	out, resolved, _ := Render([]byte(`{"port":{{PORT}}}`), map[string]string{"PORT": "{{AUTO_PORT}}"})
+	if bytes.Contains(out, []byte("AUTO_PORT")) {
+		t.Errorf("AUTO_PORT not resolved: %s", out)
 	}
-	if resolved["PORT"] == "auto" || resolved["PORT"] == "" {
+	if resolved["PORT"] == "{{AUTO_PORT}}" || resolved["PORT"] == "" {
 		t.Errorf("PORT not resolved: %q", resolved["PORT"])
 	}
 }
 
 func TestRender_AutoUUID(t *testing.T) {
-	out, _, _ := Render([]byte(`{"uuid":"{{UUID}}"}`), map[string]string{"UUID": "auto"})
-	if bytes.Contains(out, []byte("auto")) {
+	out, _, _ := Render([]byte(`{"uuid":"{{UUID}}"}`), map[string]string{"UUID": "{{AUTO_UUID}}"})
+	if bytes.Contains(out, []byte("AUTO_UUID")) {
 		t.Errorf("UUID not resolved: %s", out)
 	}
 }
 
 func TestRender_AutoPassword(t *testing.T) {
-	out, _, _ := Render([]byte(`{"pass":"{{PASSWORD}}"}`), map[string]string{"PASSWORD": "auto"})
-	if bytes.Contains(out, []byte("auto")) {
+	out, _, _ := Render([]byte(`{"pass":"{{PASSWORD}}"}`), map[string]string{"PASSWORD": "{{AUTO_PASSWORD}}"})
+	if bytes.Contains(out, []byte("AUTO_PASSWORD")) {
 		t.Errorf("PASSWORD not resolved: %s", out)
 	}
 }
 
+func TestRender_AutoLiteralPreserved(t *testing.T) {
+	// The word "auto" in a real config value must NOT be resolved.
+	out, resolved, err := Render([]byte(`{"mode":"{{ MODE }}"}`), map[string]string{"MODE": "auto"})
+	if err != nil {
+		t.Fatalf("Render: %v", err)
+	}
+	if !bytes.Contains(out, []byte("auto")) {
+		t.Errorf("literal 'auto' value was incorrectly resolved: %s", out)
+	}
+	if resolved["MODE"] != "auto" {
+		t.Errorf("MODE should stay 'auto', got %q", resolved["MODE"])
+	}
+}
+
 // --- combined: JSON5 + pongo2 + auto ---
 
 func TestRender_Combined(t *testing.T) {
@@ -132,5 +146,5 @@ func TestRender_Combined(t *testing.T) {
 		/* optional fields */
 		"network": ["tcp","udp"],
 	}`
-	renderOK(t, src, map[string]string{"PORT": "auto", "PASSWORD": "auto"})
+	renderOK(t, src, map[string]string{"PORT": "{{AUTO_PORT}}", "PASSWORD": "{{AUTO_PASSWORD}}"})
 }