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.
This commit is contained in:
Willie
2026-02-16 12:58:28 +08:00
parent cb9db75dfb
commit d99653025c
6 changed files with 75 additions and 83 deletions
+18
View File
@@ -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
+8 -28
View File
@@ -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
+1 -4
View File
@@ -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)
+7 -35
View File
@@ -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 {
@@ -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` |
+27 -16
View File
@@ -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 |
---