fix: restore storage.sdkPath semantics

Restore storage.sdkPath to the original v0.10.x storage layout. New SDKs continue to use the original sdkPath/<sdk> format, while SDKs installed under the incorrect sdkPath/cache/<sdk> path remain temporarily compatible.

Closes #649.

Author: aooohan

docs/guides/configuration.md

@@ -69,6 +69,16 @@ storage:
   sdkPath: /tmp
 ```
 
+`storage.sdkPath` is the root directory used to store SDKs. For example, if `sdkPath` is `/tmp`, Node.js will be installed under `/tmp/nodejs/`.
+
+::: warning Compatibility Note
+`v1.0.2` to `v1.0.7` incorrectly treated `storage.sdkPath` as a shared root and installed SDKs under `sdkPath/cache/<sdk>`.
+
+This behavior has been corrected to match `v0.10.x`. Existing SDKs under the incorrect `cache` path are still temporarily supported. New installs use the correct layout `sdkPath/<sdk>`.
+
+If both `sdkPath/<sdk>` and `sdkPath/cache/<sdk>` exist, `vfox` will prefer `sdkPath/<sdk>`.
+:::
+
 ## Plugin Registry Address
 
 `vfox` will default to retrieve plugins from [plugins registry](https://version-fox.github.io/vfox-plugins).

docs/zh-hans/guides/configuration.md

@@ -66,6 +66,16 @@ storage:
   sdkPath: /tmp
 ```
 
+`storage.sdkPath` 表示 SDK 的根目录。例如当 `sdkPath` 为 `/tmp` 时，Node.js 会安装到 `/tmp/nodejs/`。
+
+::: warning 兼容性说明
+`v1.0.2` 到 `v1.0.7` 错误地将 `storage.sdkPath` 当成 shared root 使用，导致 SDK 被安装到 `sdkPath/cache/<sdk>`。
+
+现在该行为已经修正，重新与 `v0.10.x` 保持一致。对于已经落在错误 `cache` 路径下的 SDK，`vfox` 仍会临时兼容；新安装会使用正确布局 `sdkPath/<sdk>`。
+
+如果 `sdkPath/<sdk>` 和 `sdkPath/cache/<sdk>` 同时存在，`vfox` 会优先使用 `sdkPath/<sdk>`。
+:::
+
 ## 插件注册表地址
 
 `vfox`默认从[插件仓库](https://version-fox.github.io/vfox-plugins)检索插件。

internal/pathmeta/path_meta.go

@@ -178,14 +178,14 @@ func (p *PathMeta) ApplyStoragePath(storagePath string) error {
 	if storagePath == "" {
 		return nil
 	}
-	
+
 	// Update the Installs path to use the configured storage path
-	p.Shared.Installs = filepath.Join(storagePath, installedDirPrefix)
-	
+	p.Shared.Installs = filepath.Join(storagePath)
+
 	// Ensure the directory exists
 	if err := os.MkdirAll(p.Shared.Installs, ReadWriteAuth); err != nil {
 		return fmt.Errorf("failed to create storage directory: %w", err)
 	}
-	
+
 	return nil
 }

internal/pathmeta/path_meta_test.go

@@ -19,7 +19,6 @@
 package pathmeta
 
 import (
-	"path/filepath"
 	"runtime"
 	"testing"
 )
@@ -182,20 +181,13 @@ func TestApplyStoragePath(t *testing.T) {
 
 	t.Run("Valid storage path updates Installs", func(t *testing.T) {
 		customPath := tmpDir + "/custom"
-		
-		// Create a reference PathMeta to get the expected suffix
-		refMeta, err := NewPathMeta(tmpDir, customPath, tmpDir, 1)
-		if err != nil {
-			t.Fatalf("Failed to create reference PathMeta: %v", err)
-		}
-		expectedSuffix := filepath.Base(refMeta.Shared.Installs)
-		
+
 		// Now test ApplyStoragePath
-		err = meta.ApplyStoragePath(customPath)
+		err := meta.ApplyStoragePath(customPath)
 		if err != nil {
 			t.Errorf("ApplyStoragePath with valid path should not error: %v", err)
 		}
-		expectedPath := filepath.Join(customPath, expectedSuffix)
+		expectedPath := customPath
 		if meta.Shared.Installs != expectedPath {
 			t.Errorf("Installs path not updated correctly: got %q, want %q", meta.Shared.Installs, expectedPath)
 		}

internal/sdk/sdk.go

@@ -1048,6 +1048,14 @@ func NewSdk(runtimeEnvContext *env.RuntimeEnvContext, pluginPath string) (Sdk, e
 		strings.ToLower(sdkName),
 	)
 
+	if !util.FileExists(installPath) {
+		// compatibility bug path introduced in v1.0.2
+		newVar := filepath.Join(runtimeEnvContext.PathMeta.Shared.Installs, "cache", strings.ToLower(sdkName))
+		if util.FileExists(newVar) {
+			installPath = newVar
+		}
+	}
+
 	return &impl{
 		Name:        sdkName,
 		InstallPath: installPath,

internal/sdk/sdk_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/version-fox/vfox/internal/config"
 	"github.com/version-fox/vfox/internal/env"
 	"github.com/version-fox/vfox/internal/pathmeta"
 )
@@ -510,6 +511,61 @@ func TestEnsureVfoxInGitignore(t *testing.T) {
 	}
 }
 
+func TestNewSdk_PrefersPrimaryInstallPath(t *testing.T) {
+	tempDir := t.TempDir()
+	installRoot := filepath.Join(tempDir, "sdks")
+	pluginPath := filepath.Join("..", "plugin", "testdata", "plugins", "java_with_metadata")
+
+	primaryInstallPath := filepath.Join(installRoot, "java_with_metadata")
+	legacyInstallPath := filepath.Join(installRoot, "cache", "java_with_metadata")
+
+	if err := os.MkdirAll(primaryInstallPath, 0755); err != nil {
+		t.Fatalf("Failed to create primary install path: %v", err)
+	}
+	if err := os.MkdirAll(legacyInstallPath, 0755); err != nil {
+		t.Fatalf("Failed to create legacy install path: %v", err)
+	}
+
+	source, err := NewSdk(&env.RuntimeEnvContext{
+		UserConfig:     config.DefaultConfig,
+		PathMeta:       &pathmeta.PathMeta{Shared: pathmeta.SharedPaths{Installs: installRoot}},
+		RuntimeVersion: "test",
+	}, pluginPath)
+	if err != nil {
+		t.Fatalf("NewSdk returned error: %v", err)
+	}
+	defer source.Close()
+
+	if got := source.Metadata().SdkInstalledPath; got != primaryInstallPath {
+		t.Fatalf("SdkInstalledPath = %q, want %q", got, primaryInstallPath)
+	}
+}
+
+func TestNewSdk_FallsBackToLegacyInstallPath(t *testing.T) {
+	tempDir := t.TempDir()
+	installRoot := filepath.Join(tempDir, "sdks")
+	pluginPath := filepath.Join("..", "plugin", "testdata", "plugins", "java_with_metadata")
+
+	legacyInstallPath := filepath.Join(installRoot, "cache", "java_with_metadata")
+	if err := os.MkdirAll(legacyInstallPath, 0755); err != nil {
+		t.Fatalf("Failed to create legacy install path: %v", err)
+	}
+
+	source, err := NewSdk(&env.RuntimeEnvContext{
+		UserConfig:     config.DefaultConfig,
+		PathMeta:       &pathmeta.PathMeta{Shared: pathmeta.SharedPaths{Installs: installRoot}},
+		RuntimeVersion: "test",
+	}, pluginPath)
+	if err != nil {
+		t.Fatalf("NewSdk returned error: %v", err)
+	}
+	defer source.Close()
+
+	if got := source.Metadata().SdkInstalledPath; got != legacyInstallPath {
+		t.Fatalf("SdkInstalledPath = %q, want %q", got, legacyInstallPath)
+	}
+}
+
 // Helper function to check if a line exists in content
 func containsLine(content, line string) bool {
 	lines := splitLines(content)