Merge pull request #4 from lispking/develop

refactor: migrate directory layout to XDG Base Directory Specification

Author: lispking

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
           version: '0.16.0'
 
       - name: Build
-        run: zig build -Doptimize=ReleaseSafe -Dtarget=aarch64-linux-gnu
+        run: zig build
         shell: bash
 
       - name: Run tests

README.md

@@ -63,7 +63,7 @@ zig build -Doptimize=ReleaseSafe
 Add zvm's bin directory to your PATH:
 
 ```bash
-export PATH="$HOME/.zvm/bin:$PATH"
+export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/zvm/bin:$PATH"
 ```
 
 ## Quick Start
@@ -217,28 +217,36 @@ eval "$(zvm completion bash)"
 
 ## How It Works
 
+zvm follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/):
+
 ```
-~/.zvm/
-├── bin            → symlink/junction to the active version directory
-├── .active        → marker file tracking the active version name
-├── 0.16.0/        → Zig 0.16.0 installation
-│   └── zig        → Zig compiler binary
-├── 0.14.0/        → Zig 0.14.0 installation
+~/.config/zvm/                  ($XDG_CONFIG_HOME/zvm/)
+└── settings.json               Configuration file
+
+~/.local/share/zvm/             ($XDG_DATA_HOME/zvm/)
+├── bin                         → symlink/junction to the active version directory
+├── .active                     → marker file tracking the active version name
+├── 0.16.0/                     → Zig 0.16.0 installation
+│   └── zig                     → Zig compiler binary
+├── 0.14.0/                     → Zig 0.14.0 installation
 │   └── zig
-├── master/        → Latest nightly build
+├── master/                     → Latest nightly build
 │   └── zig
-├── self/          → zvm's own data
-└── settings.json  → Configuration file
+└── self/                       → zvm's own data (upgrade staging)
+
+~/.cache/zvm/                   ($XDG_CACHE_HOME/zvm/)
+├── versions.json               → cached Zig version map
+└── versions-zls.json           → cached ZLS version map
 ```
 
-- **Version switching** uses symbolic links (junctions on Windows) — `~/.zvm/bin` points to the active version's directory
+- **Version switching** uses symbolic links (junctions on Windows) — the `bin` directory points to the active version's directory
 - **Downloads** are streamed to disk with SHA256 verification and latency-based mirror selection
-- **Settings** are persisted immediately on every change to `~/.zvm/settings.json`
+- **Settings** are persisted immediately on every change to `settings.json`
 - **No background services** — zvm runs only when you invoke it
 
 ## Configuration
 
-Settings are stored in `~/.zvm/settings.json`:
+Settings are stored in `$XDG_CONFIG_HOME/zvm/settings.json` (default: `~/.config/zvm/settings.json`):
 
 ```json
 {
@@ -253,10 +261,31 @@ Settings are stored in `~/.zvm/settings.json`:
 }
 ```
 
-Override the default `~/.zvm` location with the `ZVM_PATH` environment variable:
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `ZVM_PATH` | Override the data directory (legacy, takes precedence over `XDG_DATA_HOME`) |
+| `XDG_CONFIG_HOME` | Config directory (default: `~/.config`) |
+| `XDG_DATA_HOME` | Data directory (default: `~/.local/share`) |
+| `XDG_CACHE_HOME` | Cache directory (default: `~/.cache`) |
+
+### Migrating from `~/.zvm`
+
+If you previously used zvm with the `~/.zvm` directory, migrate with:
+
+```bash
+mkdir -p ~/.config/zvm ~/.local/share/zvm ~/.cache/zvm
+mv ~/.zvm/settings.json ~/.config/zvm/
+mv ~/.zvm/versions*.json ~/.cache/zvm/
+mv ~/.zvm/[0-9]* ~/.zvm/master ~/.zvm/bin ~/.zvm/.active ~/.local/share/zvm/
+rm -rf ~/.zvm
+```
+
+Then update your shell config to use the new PATH:
 
 ```bash
-export ZVM_PATH="/custom/path"
+export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/zvm/bin:$PATH"
 ```
 
 ## CI / Releases
@@ -291,7 +320,7 @@ All available at `https://github.com/lispking/zvm/releases/latest/download/<file
 src/
 ├── main.zig          Entry point: allocator setup, CLI dispatch
 ├── cli.zig           Hand-written CLI parser with aliases and flags
-├── zvm.zig           Core ZVM struct (base dir, settings, versions)
+├── zvm.zig           Core ZVM struct (XDG dirs, settings, versions)
 ├── settings.zig      Settings persistence (JSON load/save)
 ├── errors.zig        Domain error definitions
 ├── platform.zig      OS/arch detection, symlink management

install.sh

@@ -10,7 +10,7 @@ set -euo pipefail
 
 REPO="lispking/zvm"
 INSTALL_DIR="${ZVM_INSTALL:-$HOME/.local/bin}"
-ZVM_DIR="$HOME/.zvm"
+ZVM_DIR="${ZVM_PATH:-${XDG_DATA_HOME:-$HOME/.local/share}/zvm}"
 
 # ── Colors ──────────────────────────────────────────────────────────────
 RED='\033[0;31m'
@@ -195,7 +195,7 @@ export PATH=\"\${HOME}/.local/bin:\$PATH\""
         fi
         if [ "$needs_zvm_bin" = true ]; then
             append_once "$shell_rc" "# <<< zvm <<<" \
-                "export PATH=\"\${ZVM_DIR:-\$HOME/.zvm}/bin:\$PATH\"
+                "export PATH=\"\${ZVM_PATH:-\${XDG_DATA_HOME:-\$HOME/.local/share}/zvm}/bin:\$PATH\"
 # <<< zvm <<<"
         fi
         if [ "$needs_local_bin" = true ] || [ "$needs_zvm_bin" = true ]; then
@@ -207,7 +207,7 @@ export PATH=\"\${HOME}/.local/bin:\$PATH\""
             warn "Add these lines to your shell config manually:"
             echo ""
             echo '  export PATH="$HOME/.local/bin:$PATH"'
-            echo '  export PATH="$HOME/.zvm/bin:$PATH"'
+            echo '  export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/zvm/bin:$PATH"'
             echo ""
         fi
     fi
@@ -242,7 +242,7 @@ export PATH=\"\${HOME}/.local/bin:\$PATH\""
             echo "    source ${shell_rc}"
         else
             echo "    export PATH=\"\$HOME/.local/bin:\$PATH\""
-            echo "    export PATH=\"\$HOME/.zvm/bin:\$PATH\""
+            echo "    export PATH=\"\${XDG_DATA_HOME:-\$HOME/.local/share}/zvm/bin:\$PATH\""
         fi
         echo ""
     fi

src/clean.zig

@@ -1,10 +1,10 @@
-//! Clean command — remove build artifacts from the zvm directory.
-//! Deletes downloaded .zip, .xz, .tar, and .tar.xz files from ~/.zvm/.
+//! Clean command — remove build artifacts from the cache directory.
+//! Deletes downloaded .zip, .xz, .tar, and .tar.xz files from the XDG cache dir.
 
 const std = @import("std");
 const zvm_mod = @import("zvm.zig");
 
-/// Remove archive files (.zip, .xz, .tar, .tar.xz) from the zvm base directory.
+/// Remove archive files (.zip, .xz, .tar, .tar.xz) from the cache directory.
 /// These are leftover files from downloads that are no longer needed after extraction.
 pub fn run(
     zvm: *zvm_mod.ZVM,
@@ -17,7 +17,7 @@ pub fn run(
 
     const extensions = [_][]const u8{ ".zip", ".xz", ".tar", ".tar.xz" };
 
-    var dir = try std.Io.Dir.cwd().openDir(zvm.io, zvm.base_dir, .{ .iterate = true });
+    var dir = try std.Io.Dir.cwd().openDir(zvm.io, zvm.cache_dir, .{ .iterate = true });
     defer dir.close(zvm.io);
 
     var count: usize = 0;

src/cli.zig

@@ -407,7 +407,7 @@ pub fn printCommandHelp(writer: *std.Io.Writer, cmd: Command) !void {
             \\
         ),
         .clean => try writer.writeAll(
-            \\Remove build artifacts from ~/.zvm/
+            \\Remove build artifacts from the cache directory.
             \\
             \\Usage:
             \\  zvm clean

src/completion.zig

@@ -106,7 +106,7 @@ fn writeZshCompletion(writer: *std.Io.Writer) !void {
         \\
         \\_zvm_installed_versions() {
         \\  local -a versions
-        \\  local zvm_dir="${ZVM_PATH:-$HOME/.zvm}"
+        \\  local zvm_dir="${ZVM_PATH:-${XDG_DATA_HOME:-$HOME/.local/share}/zvm}"
         \\  if [[ -d "$zvm_dir" ]]; then
         \\    for dir in "$zvm_dir"/*/; do
         \\      local ver=$(basename "$dir")
@@ -222,7 +222,7 @@ fn writeBashCompletion(writer: *std.Io.Writer) !void {
         \\}
         \\
         \\_zvm_list_versions() {
-        \\  local zvm_dir="${ZVM_PATH:-$HOME/.zvm}"
+        \\  local zvm_dir="${ZVM_PATH:-${XDG_DATA_HOME:-$HOME/.local/share}/zvm}"
         \\  local -a versions=()
         \\  if [[ -d "$zvm_dir" ]]; then
         \\    for dir in "$zvm_dir"/*/; do

src/install.zig

@@ -105,7 +105,7 @@ fn installVersion(
     const archive_name = if (std.mem.lastIndexOfScalar(u8, tar_url, '/')) |idx| tar_url[idx + 1 ..] else "zig-archive";
 
     var archive_path_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-    const archive_path = try std.fmt.bufPrint(&archive_path_buf, "{s}/{s}", .{ zvm.base_dir, archive_name });
+    const archive_path = try std.fmt.bufPrint(&archive_path_buf, "{s}/{s}", .{ zvm.cache_dir, archive_name });
 
     // Download archive (with optional mirror support)
     try stdout.print("Downloading Zig {s}...\n", .{version});
@@ -151,7 +151,7 @@ fn installVersion(
     try stdout.print("Extracting...\n", .{});
     try stdout.flush();
 
-    archive.extractArchive(allocator, zvm.io, archive_path, zvm.base_dir) catch {
+    archive.extractArchive(allocator, zvm.io, archive_path, zvm.data_dir) catch {
         try terminal.printError(stderr, "Failed to extract archive");
         return error.ExtractionFailed;
     };
@@ -218,7 +218,7 @@ fn renameExtractedDir(
     const arch_part = target[0..dash_idx];
     const os_part = target[dash_idx + 1 ..];
 
-    var dir = std.Io.Dir.cwd().openDir(zvm.io, zvm.base_dir, .{ .iterate = true }) catch return;
+    var dir = std.Io.Dir.cwd().openDir(zvm.io, zvm.data_dir, .{ .iterate = true }) catch return;
     defer dir.close(zvm.io);
 
     var found: ?[]const u8 = null;
@@ -251,15 +251,15 @@ fn renameExtractedDir(
 
 /// Remove any leftover zig-* directories from failed or interrupted extractions.
 fn cleanupExtractedDirs(zvm: *zvm_mod.ZVM) void {
-    var dir = std.Io.Dir.cwd().openDir(zvm.io, zvm.base_dir, .{ .iterate = true }) catch return;
+    var dir = std.Io.Dir.cwd().openDir(zvm.io, zvm.data_dir, .{ .iterate = true }) catch return;
     defer dir.close(zvm.io);
 
     var iter = dir.iterate();
     while (iter.next(zvm.io) catch return) |entry| {
         if (entry.kind != .directory) continue;
         if (std.mem.startsWith(u8, entry.name, "zig-")) {
             var buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-            const path = std.fmt.bufPrint(&buf, "{s}/{s}", .{ zvm.base_dir, entry.name }) catch continue;
+            const path = std.fmt.bufPrint(&buf, "{s}/{s}", .{ zvm.data_dir, entry.name }) catch continue;
             std.Io.Dir.cwd().deleteTree(zvm.io, path) catch {};
         }
     }
@@ -278,9 +278,9 @@ fn verifyInstall(
     const zig_path = try std.fmt.allocPrint(allocator, "{s}/zig", .{ver_path});
     defer allocator.free(zig_path);
 
-    // Create a temporary test file in the zvm base directory
+    // Create a temporary test file in the cache directory
     var test_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-    const test_path = try std.fmt.bufPrint(&test_buf, "{s}/_zvm_smoke_test.zig", .{zvm.base_dir});
+    const test_path = try std.fmt.bufPrint(&test_buf, "{s}/_zvm_smoke_test.zig", .{zvm.cache_dir});
     defer std.Io.Dir.cwd().deleteFile(zvm.io, test_path) catch {};
 
     const test_file = try std.Io.Dir.cwd().createFile(zvm.io, test_path, .{});
@@ -407,13 +407,13 @@ fn installZls(
     const zls_archive_name = if (std.mem.lastIndexOfScalar(u8, zls_tarball, '/')) |idx| zls_tarball[idx + 1 ..] else "zls-archive";
 
     var archive_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-    const zls_archive_path = try std.fmt.bufPrint(&archive_buf, "{s}/{s}", .{ zvm.base_dir, zls_archive_name });
+    const zls_archive_path = try std.fmt.bufPrint(&archive_buf, "{s}/{s}", .{ zvm.cache_dir, zls_archive_name });
 
     try http_client.downloadToFileWithProxy(allocator, zvm.io, zvm.environ_map, zls_tarball, zls_archive_path, zvm.settings.proxy);
 
     // Extract to a temporary directory
     var temp_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-    const temp_dir = try std.fmt.bufPrint(&temp_buf, "{s}/zls-temp", .{zvm.base_dir});
+    const temp_dir = try std.fmt.bufPrint(&temp_buf, "{s}/zls-temp", .{zvm.cache_dir});
     std.Io.Dir.cwd().createDirPath(zvm.io, temp_dir) catch {};
 
     archive.extractArchive(allocator, zvm.io, zls_archive_path, temp_dir) catch {
@@ -437,12 +437,12 @@ fn installZls(
             var inner_iter = inner_dir.iterate();
             while (try inner_iter.next(zvm.io)) |inner_entry| {
                 if (std.mem.eql(u8, inner_entry.name, "zls") or std.mem.eql(u8, inner_entry.name, "zls.exe")) {
-                    // Copy the zls binary to ~/.zvm/<version>/zls
+                    // Copy the zls binary to data_dir/<version>/zls
                     var src_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
                     const src = try std.fmt.bufPrint(&src_buf, "{s}/{s}/{s}", .{ temp_dir, entry.name, inner_entry.name });
 
                     var dst_buf: [std.fs.max_path_bytes * 2]u8 = undefined;
-                    const dst = try std.fmt.bufPrint(&dst_buf, "{s}/{s}/zls", .{ zvm.base_dir, version });
+                    const dst = try std.fmt.bufPrint(&dst_buf, "{s}/{s}/zls", .{ zvm.data_dir, version });
 
                     const src_file = std.Io.Dir.cwd().openFile(zvm.io, src, .{}) catch continue;
                     defer src_file.close(zvm.io);

src/main.zig

@@ -38,7 +38,7 @@ pub fn main(init: std.process.Init) !void {
         std.process.exit(1);
     };
 
-    // Initialize ZVM environment (~/.zvm, settings, etc.)
+    // Initialize ZVM environment (XDG dirs, settings, etc.)
     var zvm = zvm_mod.ZVM.init(allocator, init.io, init.environ_map) catch {
         var stderr_buf: [4096]u8 = undefined;
         var stderr_writer = std.Io.File.stderr().writer(init.io, &stderr_buf);

src/platform.zig

@@ -103,15 +103,9 @@ pub fn removeSymlink(io: std.Io, path: []const u8) void {
     std.Io.Dir.cwd().deleteFile(io, path) catch {};
 }
 
-/// Resolve the user's home directory.
-/// Checks ZVM_PATH env var first, then falls back to HOME (or USERPROFILE on Windows).
+/// Resolve the home directory (used as fallback for XDG defaults).
 /// Caller owns the returned memory.
-pub fn getHomeDir(allocator: std.mem.Allocator, environ_map: *std.process.Environ.Map) ![]const u8 {
-    // Try ZVM_PATH first, then HOME
-    if (environ_map.get("ZVM_PATH")) |path| {
-        return allocator.dupe(u8, path);
-    }
-
+fn getHomeDir(allocator: std.mem.Allocator, environ_map: *std.process.Environ.Map) ![]const u8 {
     if (builtin.os.tag == .windows) {
         if (environ_map.get("USERPROFILE")) |path| {
             return allocator.dupe(u8, path);
@@ -124,6 +118,66 @@ pub fn getHomeDir(allocator: std.mem.Allocator, environ_map: *std.process.Enviro
     return error.FileNotFound;
 }
 
+/// Resolve the XDG config directory.
+/// Checks XDG_CONFIG_HOME, falls back to $HOME/.config.
+/// On Windows, falls back to %APPDATA% or %USERPROFILE%/.config.
+/// Caller owns the returned memory.
+pub fn getConfigDir(allocator: std.mem.Allocator, environ_map: *std.process.Environ.Map) ![]const u8 {
+    if (environ_map.get("XDG_CONFIG_HOME")) |path| {
+        if (path.len > 0) return allocator.dupe(u8, path);
+    }
+
+    if (builtin.os.tag == .windows) {
+        if (environ_map.get("APPDATA")) |path| {
+            if (path.len > 0) return allocator.dupe(u8, path);
+        }
+    }
+
+    const home = try getHomeDir(allocator, environ_map);
+    defer allocator.free(home);
+    return std.fmt.allocPrint(allocator, "{s}/.config", .{home});
+}
+
+/// Resolve the XDG data directory.
+/// Checks ZVM_PATH (legacy override) first, then XDG_DATA_HOME,
+/// falls back to $HOME/.local/share.
+/// On Windows, falls back to %USERPROFILE%/.local/share.
+/// Caller owns the returned memory.
+pub fn getDataDir(allocator: std.mem.Allocator, environ_map: *std.process.Environ.Map) ![]const u8 {
+    // Legacy ZVM_PATH override — use as-is (user already specifies full path)
+    if (environ_map.get("ZVM_PATH")) |path| {
+        if (path.len > 0) return allocator.dupe(u8, path);
+    }
+
+    if (environ_map.get("XDG_DATA_HOME")) |path| {
+        if (path.len > 0) return allocator.dupe(u8, path);
+    }
+
+    const home = try getHomeDir(allocator, environ_map);
+    defer allocator.free(home);
+    return std.fmt.allocPrint(allocator, "{s}/.local/share", .{home});
+}
+
+/// Resolve the XDG cache directory.
+/// Checks XDG_CACHE_HOME, falls back to $HOME/.cache.
+/// On Windows, falls back to %LOCALAPPDATA% or %USERPROFILE%/.cache.
+/// Caller owns the returned memory.
+pub fn getCacheDir(allocator: std.mem.Allocator, environ_map: *std.process.Environ.Map) ![]const u8 {
+    if (environ_map.get("XDG_CACHE_HOME")) |path| {
+        if (path.len > 0) return allocator.dupe(u8, path);
+    }
+
+    if (builtin.os.tag == .windows) {
+        if (environ_map.get("LOCALAPPDATA")) |path| {
+            if (path.len > 0) return allocator.dupe(u8, path);
+        }
+    }
+
+    const home = try getHomeDir(allocator, environ_map);
+    defer allocator.free(home);
+    return std.fmt.allocPrint(allocator, "{s}/.cache", .{home});
+}
+
 /// Build the target-specific platform string used in Zig download URLs.
 /// E.g., "x86_64-macos", "aarch64-linux"
 pub fn platformTarget(buf: []u8, info: SystemInfo) []const u8 {

src/run.zig

@@ -26,7 +26,7 @@ pub fn run(
         std.process.exit(1);
     }
 
-    // Build the zig binary path: ~/.zvm/<version>/zig
+    // Build the zig binary path: data_dir/<version>/zig
     var path_buf: [std.fs.max_path_bytes]u8 = undefined;
     const version_dir = zvm.versionPath(&path_buf, version);
     const zig_path = try std.fmt.allocPrint(allocator, "{s}/zig", .{version_dir});