fix(quickstart): preserve legacy env layouts

Author: digitallysavvy

CHANGELOG.md

@@ -26,7 +26,7 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ### Fixed
 
-- Align Python and Go quickstart env writing with the upstream repositories by targeting `server/.env.local` and `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE`, and avoid detecting Go quickstarts as Python quickstarts.
+- Align new Python and Go quickstart env writing with the upstream repositories by targeting `server/.env.local` and `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE`, avoid detecting Go quickstarts as Python quickstarts, and retain compatibility with legacy quickstart env layouts.
 - Correct the Go skills and README quickstart wording from a token-service recipe to the actual Go ConvoAI voice-agent quickstart.
 
 ## [0.2.5] - 2026-06-05

README.md

@@ -214,6 +214,7 @@ Quickstart template behavior:
 - Next.js quickstarts write `.env.local` with `NEXT_PUBLIC_AGORA_APP_ID` plus `NEXT_AGORA_APP_CERTIFICATE`
 - Python quickstarts copy `server/.env.example` to `server/.env.local`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
 - Go quickstarts copy `server/.env.example` to `server/.env.local`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
+- Existing Python and Go quickstarts keep their recorded env path and legacy `APP_ID` / `APP_CERTIFICATE` keys when reconfigured.
 
 `project env write` auto-detects Next.js workspaces (or accepts `--template nextjs|standard`) and writes `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE` or the Next.js equivalents. Use `quickstart env write` when you want the CLI to choose the official quickstart's env path.
 

docs/automation.md

@@ -682,6 +682,7 @@ Env write behavior:
 - quickstart env files contain only the App ID and App Certificate variable names required by the template
 - Next.js uses `NEXT_PUBLIC_AGORA_APP_ID` and `NEXT_AGORA_APP_CERTIFICATE`
 - Python and Go use `AGORA_APP_ID` and `AGORA_APP_CERTIFICATE`
+- existing Python and Go quickstarts retain their recorded env path and legacy `APP_ID` / `APP_CERTIFICATE` keys when reconfigured
 - project metadata such as project ID, project name, region, template, projectType, and env path is stored in `.agora/project.json`
 - existing quickstart env files are preserved; missing credential keys are appended and existing credential keys are updated
 - stale Agora credential aliases for another runtime are commented out to avoid ambiguous dotenv resolution; for example, a Next.js quickstart prefers `NEXT_PUBLIC_AGORA_APP_ID` and comments out old `AGORA_APP_ID` / `APP_ID` entries when replacing them

internal/cli/doctor.go

@@ -46,17 +46,6 @@ func summarizeCategoryStatus(items []doctorCheckItem) string {
 	return "skipped"
 }
 
-func quickstartAppIDKey(templateID string) string {
-	switch templateID {
-	case "nextjs":
-		return "NEXT_PUBLIC_AGORA_APP_ID"
-	case "python", "go":
-		return "AGORA_APP_ID"
-	default:
-		return ""
-	}
-}
-
 func lookupDotenvValue(content, key string) (string, bool) {
 	for _, line := range strings.Split(content, "\n") {
 		trimmed := strings.TrimSpace(line)
@@ -196,8 +185,21 @@ func buildWorkspaceDoctorDetails(target projectTarget) (doctorCheckCategory, map
 
 	template, found := findQuickstartTemplate(templateID)
 	envRel := strings.TrimSpace(binding.EnvPath)
+	layout := quickstartEnvLayout{}
 	if found {
-		envRel = template.EnvTargetPath
+		if envRel != "" {
+			layout, _ = quickstartEnvLayoutForEnvPath(*template, envRel)
+		}
+		if layout.EnvTargetPath == "" {
+			if detected, ok := quickstartEnvLayoutForPath(root, *template); ok {
+				layout = detected
+			} else if fallback, ok := template.defaultEnvLayout(); ok {
+				layout = fallback
+			}
+		}
+		if envRel == "" {
+			envRel = layout.EnvTargetPath
+		}
 	}
 	if envRel == "" {
 		items = append(items, doctorCheckItem{Name: "workspace_env_path", Message: "Could not determine quickstart env target path", Status: "warn"})
@@ -270,7 +272,7 @@ func buildWorkspaceDoctorDetails(target projectTarget) (doctorCheckCategory, map
 		warnings = append(warnings, doctorIssue{Code: "WORKSPACE_ENV_METADATA_MISSING", Message: "Quickstart env file is missing Agora-managed project metadata comments"})
 	}
 
-	appIDKey := quickstartAppIDKey(templateID)
+	appIDKey := layout.AppIDKey
 	if appIDKey != "" {
 		if envAppID, ok := lookupDotenvValue(envContent, appIDKey); !ok {
 			items = append(items, doctorCheckItem{

internal/cli/integration_project_test.go

@@ -252,7 +252,7 @@ func TestCLIProjectDoctorDeepDetectsWorkspaceDrift(t *testing.T) {
 	}
 
 	repoRoot := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(repoRoot, "server"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(repoRoot, "server-go"), 0o755); err != nil {
 		t.Fatal(err)
 	}
 	if err := writeLocalProjectBinding(repoRoot, localProjectBinding{
@@ -268,12 +268,12 @@ func TestCLIProjectDoctorDeepDetectsWorkspaceDrift(t *testing.T) {
 		"# BEGIN AGORA CLI QUICKSTART",
 		"# Project ID: prj_other",
 		"# Project Name: Project Other",
-		"AGORA_APP_ID=app_other",
-		"AGORA_APP_CERTIFICATE=other",
+		"APP_ID=app_other",
+		"APP_CERTIFICATE=other",
 		"# END AGORA CLI QUICKSTART",
 		"",
 	}, "\n")
-	if err := os.WriteFile(filepath.Join(repoRoot, "server", ".env.local"), []byte(mismatched), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(repoRoot, "server-go", ".env"), []byte(mismatched), 0o644); err != nil {
 		t.Fatal(err)
 	}
 

internal/cli/integration_quickstart_test.go

@@ -263,21 +263,18 @@ func TestCLIQuickstartEnvWriteUsesTargetRepoBindingPrecedence(t *testing.T) {
 	}
 
 	targetDir := filepath.Join(rootDir, "demo-go")
-	if err := os.MkdirAll(filepath.Join(targetDir, "server"), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(targetDir, "server-go"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(targetDir, "server", ".env.example"), []byte("AGORA_APP_ID=\nAGORA_APP_CERTIFICATE=\nPORT=8080\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(targetDir, "server", "go.mod"), []byte("module agent-quickstart-go/server\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(targetDir, "server-go", "env.example"), []byte("APP_ID=\nAPP_CERTIFICATE=\nPORT=8080\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	if err := writeLocalProjectBinding(targetDir, localProjectBinding{
 		ProjectID:   alpha.ProjectID,
 		ProjectName: alpha.Name,
 		Region:      "global",
 		Template:    "go",
-		EnvPath:     "server/.env.local",
+		EnvPath:     "server-go/.env",
 	}); err != nil {
 		t.Fatal(err)
 	}
@@ -293,13 +290,16 @@ func TestCLIQuickstartEnvWriteUsesTargetRepoBindingPrecedence(t *testing.T) {
 	if result.exitCode != 0 || !strings.Contains(result.stdout, `"projectId":"prj_alpha"`) {
 		t.Fatalf("expected repo-local project binding precedence, got %+v", result)
 	}
-	envRaw, err := os.ReadFile(filepath.Join(targetDir, "server", ".env.local"))
+	envRaw, err := os.ReadFile(filepath.Join(targetDir, "server-go", ".env"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(envRaw), "AGORA_APP_ID=app_alpha") || !strings.Contains(string(envRaw), "PORT=8080") || strings.Contains(string(envRaw), "AGORA_APP_ID=app_beta") {
+	if !strings.Contains(string(envRaw), "APP_ID=app_alpha") || !strings.Contains(string(envRaw), "PORT=8080") || strings.Contains(string(envRaw), "APP_ID=app_beta") {
 		t.Fatalf("expected target repo binding project app id in env, got %s", string(envRaw))
 	}
+	if _, err := os.Stat(filepath.Join(targetDir, "server", ".env.local")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("did not expect a current env file in a legacy scaffold, got %v", err)
+	}
 }
 
 func TestCLIQuickstartEnvWriteMissingBindingEvenWhenEnvExists(t *testing.T) {