From d99653025c33a4c3ee1ed5b4c9a855ec3bc42496 Mon Sep 17 00:00:00 2001 From: Willie Date: Mon, 16 Feb 2026 12:58:28 +0800 Subject: [PATCH] refactor: unify CacheDir into config package and document all platform paths Move GetCacheDir() from version package to config.CacheDir(), consistent with BaseDir()/DataDir()/StateDir() pattern including Windows fallback. Add XDG_CACHE_HOME and cache paths to website docs. --- internal/config/config.go | 18 ++++++++ internal/uidist/uidist.go | 36 ++++------------ internal/uidist/uidist_test.go | 5 +-- internal/version/check.go | 42 +++--------------- .../docs/reference/environment-variables.md | 14 ++++++ website/docs/reference/file-structure.md | 43 ++++++++++++------- 6 files changed, 75 insertions(+), 83 deletions(-) diff --git a/internal/config/config.go b/internal/config/config.go index 1d01ab78d..e0019be21 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -103,6 +103,24 @@ func StateDir() string { return filepath.Join(home, ".local", "state", "skillshare") } +// CacheDir returns the cache directory (XDG_CACHE_HOME). +// Priority: +// 1. $XDG_CACHE_HOME/skillshare (any platform, if set) +// 2. %AppData%/skillshare (Windows only, via os.UserConfigDir()) +// 3. ~/.cache/skillshare (Linux, macOS) +func CacheDir() string { + if xdg := os.Getenv("XDG_CACHE_HOME"); xdg != "" { + return filepath.Join(xdg, "skillshare") + } + if runtime.GOOS == "windows" { + if dir, err := os.UserConfigDir(); err == nil { + return filepath.Join(dir, "skillshare") + } + } + home, _ := os.UserHomeDir() + return filepath.Join(home, ".cache", "skillshare") +} + // ConfigPath returns the config file path, respecting SKILLSHARE_CONFIG env var func ConfigPath() string { // Allow override for testing diff --git a/internal/uidist/uidist.go b/internal/uidist/uidist.go index 8f9b9b464..36c73ec71 100644 --- a/internal/uidist/uidist.go +++ b/internal/uidist/uidist.go @@ -14,6 +14,7 @@ import ( "strings" "time" + "skillshare/internal/config" "skillshare/internal/version" ) @@ -22,21 +23,14 @@ const AssetName = "skillshare-ui-dist.tar.gz" // CacheDir returns the cache directory for a specific version's UI dist. // Path: ~/.cache/skillshare/ui/{ver}/ -func CacheDir(ver string) (string, error) { - base, err := version.GetCacheDir() - if err != nil { - return "", err - } - return filepath.Join(base, "ui", ver), nil +func CacheDir(ver string) string { + return filepath.Join(config.CacheDir(), "ui", ver) } // IsCached checks whether a cached UI dist exists for the given version. // Returns the directory path and true if index.html exists there. func IsCached(ver string) (string, bool) { - dir, err := CacheDir(ver) - if err != nil { - return "", false - } + dir := CacheDir(ver) if _, err := os.Stat(filepath.Join(dir, "index.html")); err == nil { return dir, true } @@ -46,10 +40,7 @@ func IsCached(ver string) (string, bool) { // Download fetches the UI dist tarball for the given version, verifies its // checksum, extracts it to the cache directory, and cleans up old versions. func Download(ver string) error { - dir, err := CacheDir(ver) - if err != nil { - return err - } + dir := CacheDir(ver) // Fetch expected checksum expectedHash, err := fetchChecksum(ver) @@ -92,11 +83,7 @@ func Download(ver string) error { // ClearCache removes the entire UI cache directory (~/.cache/skillshare/ui/). func ClearCache() error { - base, err := version.GetCacheDir() - if err != nil { - return err - } - dir := filepath.Join(base, "ui") + dir := filepath.Join(config.CacheDir(), "ui") if _, err := os.Stat(dir); os.IsNotExist(err) { return nil } @@ -105,10 +92,7 @@ func ClearCache() error { // ClearVersion removes a specific version's cached UI dist. func ClearVersion(ver string) error { - dir, err := CacheDir(ver) - if err != nil { - return err - } + dir := CacheDir(ver) if _, err := os.Stat(dir); os.IsNotExist(err) { return nil } @@ -117,11 +101,7 @@ func ClearVersion(ver string) error { // cleanOldVersions removes cached UI dist versions other than currentVer. func cleanOldVersions(currentVer string) error { - base, err := version.GetCacheDir() - if err != nil { - return err - } - uiDir := filepath.Join(base, "ui") + uiDir := filepath.Join(config.CacheDir(), "ui") entries, err := os.ReadDir(uiDir) if err != nil { return err diff --git a/internal/uidist/uidist_test.go b/internal/uidist/uidist_test.go index da4b3b439..4fd08907f 100644 --- a/internal/uidist/uidist_test.go +++ b/internal/uidist/uidist_test.go @@ -14,10 +14,7 @@ func TestCacheDir_Default(t *testing.T) { tmp := t.TempDir() t.Setenv("XDG_CACHE_HOME", tmp) - dir, err := CacheDir("1.2.3") - if err != nil { - t.Fatal(err) - } + dir := CacheDir("1.2.3") expected := filepath.Join(tmp, "skillshare", "ui", "1.2.3") if dir != expected { t.Errorf("got %s, want %s", dir, expected) diff --git a/internal/version/check.go b/internal/version/check.go index 077caf045..af018fc7c 100644 --- a/internal/version/check.go +++ b/internal/version/check.go @@ -7,6 +7,8 @@ import ( "strconv" "strings" "time" + + "skillshare/internal/config" ) // Version is set by main.go at startup @@ -31,27 +33,9 @@ type CheckResult struct { UpdateAvailable bool } -// GetCacheDir returns the cache directory, respecting XDG_CACHE_HOME -func GetCacheDir() (string, error) { - // XDG Base Directory Specification: use XDG_CACHE_HOME if set - if cacheHome := os.Getenv("XDG_CACHE_HOME"); cacheHome != "" { - return filepath.Join(cacheHome, "skillshare"), nil - } - // Default: ~/.cache/skillshare - homeDir, err := os.UserHomeDir() - if err != nil { - return "", err - } - return filepath.Join(homeDir, ".cache", "skillshare"), nil -} - // getCachePath returns the path to the cache file -func getCachePath() (string, error) { - cacheDir, err := GetCacheDir() - if err != nil { - return "", err - } - return filepath.Join(cacheDir, cacheFileName), nil +func getCachePath() string { + return filepath.Join(config.CacheDir(), cacheFileName) } // legacyCachePath returns the old cache path for migration cleanup @@ -73,11 +57,7 @@ func cleanupLegacyCache() { // ClearCache removes the version check cache file func ClearCache() { - cachePath, err := getCachePath() - if err != nil { - return - } - os.Remove(cachePath) + os.Remove(getCachePath()) } // GetCachedVersion returns the cached latest version if available @@ -91,12 +71,7 @@ func GetCachedVersion() string { // loadCache loads the version check cache from disk func loadCache() (*Cache, error) { - cachePath, err := getCachePath() - if err != nil { - return nil, err - } - - data, err := os.ReadFile(cachePath) + data, err := os.ReadFile(getCachePath()) if err != nil { if os.IsNotExist(err) { return nil, nil // No cache yet @@ -114,10 +89,7 @@ func loadCache() (*Cache, error) { // saveCache saves the version check cache to disk func saveCache(cache *Cache) error { - cachePath, err := getCachePath() - if err != nil { - return err - } + cachePath := getCachePath() // Ensure directory exists if err := os.MkdirAll(filepath.Dir(cachePath), 0755); err != nil { diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 139b72b8a..740b8b85b 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -69,6 +69,19 @@ export XDG_STATE_HOME=~/my-state **Default:** `~/.local/state/skillshare/` +--- + +### XDG_CACHE_HOME + +Override the cache directory (version check cache, UI dist cache). + +```bash +export XDG_CACHE_HOME=~/my-cache +# skillshare will use ~/my-cache/skillshare/ +``` + +**Default:** `~/.cache/skillshare/` + :::tip Automatic migration Starting from v0.13.0, skillshare follows the XDG Base Directory Specification for backups, trash, and logs. If you're upgrading from an older version, these directories are automatically migrated from `~/.config/skillshare/` to their proper XDG locations on first run. ::: @@ -161,6 +174,7 @@ export GITHUB_TOKEN="ghp_your_token_here" | `XDG_CONFIG_HOME` | Base config directory | `~/.config` (Linux/macOS), `%AppData%` (Windows) | | `XDG_DATA_HOME` | Data directory (backups, trash) | `~/.local/share` | | `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` | +| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` | | `GITHUB_TOKEN` | GitHub API auth | None | | `SKILLSHARE_TEST_BINARY` | Test binary path | `bin/skillshare` | diff --git a/website/docs/reference/file-structure.md b/website/docs/reference/file-structure.md index 1e7a37090..17ebf5c9d 100644 --- a/website/docs/reference/file-structure.md +++ b/website/docs/reference/file-structure.md @@ -9,7 +9,7 @@ Directory layout and file locations for skillshare. ## Overview ``` -~/.config/skillshare/ # XDG_CONFIG_HOME +~/.config/skillshare/ # XDG_CONFIG_HOME ├── config.yaml # Configuration file ├── audit-rules.yaml # Custom audit rules (optional) └── skills/ # Source directory @@ -27,7 +27,7 @@ Directory layout and file locations for skillshare. └── api/ └── SKILL.md -~/.local/share/skillshare/ # XDG_DATA_HOME +~/.local/share/skillshare/ # XDG_DATA_HOME ├── backups/ # Backup directory │ ├── 2026-01-20_15-30-00/ │ │ ├── claude/ @@ -40,10 +40,17 @@ Directory layout and file locations for skillshare. └── old-skill_2026-01-19_10-00-00/ └── SKILL.md -~/.local/state/skillshare/ # XDG_STATE_HOME +~/.local/state/skillshare/ # XDG_STATE_HOME └── logs/ # Operation logs (JSONL) ├── operations.log # install, sync, update, etc. └── audit.log # Security audit scans + +~/.cache/skillshare/ # XDG_CACHE_HOME +├── version-check.json # Version check cache (24h TTL) +└── ui/ # Web UI dist cache + └── 0.13.0/ # Per-version cached assets + ├── index.html + └── assets/ ``` --- @@ -102,17 +109,17 @@ See [Configuration](/docs/targets/configuration) for full reference. ``` skills/ -├── skill-name/ # Skill directory -│ ├── SKILL.md # Required: skill definition +├── skill-name/ # Skill directory +│ ├── SKILL.md # Required: skill definition │ ├── .skillshare-meta.json # Optional: install metadata -│ ├── examples/ # Optional: example files -│ └── templates/ # Optional: code templates -├── frontend/ # Category folder (via --into or manual) -│ └── react-skill/ # Skill in subdirectory -│ └── SKILL.md # Synced as frontend__react-skill -└── _tracked-repo/ # Tracked repository - ├── .git/ # Git history - └── ... # Skill subdirectories +│ ├── examples/ # Optional: example files +│ └── templates/ # Optional: code templates +├── frontend/ # Category folder (via --into or manual) +│ └── react-skill/ # Skill in subdirectory +│ └── SKILL.md # Synced as frontend__react-skill +└── _tracked-repo/ # Tracked repository + ├── .git/ # Git history + └── ... # Skill subdirectories ``` --- @@ -287,7 +294,7 @@ _team-skills__frontend__ui/SKILL.md ## Platform Differences :::tip XDG Base Directory -skillshare respects the XDG Base Directory Specification. Override base directories with `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME`. +skillshare respects the XDG Base Directory Specification. Override base directories with `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, and `XDG_CACHE_HOME`. See [Environment Variables](./environment-variables.md#xdg_config_home) for details. ::: @@ -298,9 +305,11 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta |------|------| | Config | `~/.config/skillshare/config.yaml` | | Source | `~/.config/skillshare/skills/` | -| Logs | `~/.local/state/skillshare/logs/` | | Backups | `~/.local/share/skillshare/backups/` | | Trash | `~/.local/share/skillshare/trash/` | +| Logs | `~/.local/state/skillshare/logs/` | +| Version cache | `~/.cache/skillshare/version-check.json` | +| UI cache | `~/.cache/skillshare/ui/{version}/` | | Link type | Symlinks | ### Windows @@ -309,9 +318,11 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta |------|------| | Config | `%AppData%\skillshare\config.yaml` | | Source | `%AppData%\skillshare\skills\` | -| Logs | `%AppData%\skillshare\logs\` | | Backups | `%AppData%\skillshare\backups\` | | Trash | `%AppData%\skillshare\trash\` | +| Logs | `%AppData%\skillshare\logs\` | +| Version cache | `%AppData%\skillshare\version-check.json` | +| UI cache | `%AppData%\skillshare\ui\{version}\` | | Link type | NTFS Junctions | ---