feat: bandwidth-based mirror probing and standalone probe command

Replace latency-only mirror probing with actual throughput measurement.
Each mirror is tested by downloading data for 5 seconds to NUL
(/dev/null), measuring real download speed. This ensures mirrors with
low latency but poor bandwidth are no longer incorrectly prioritized.

New features:
- \zvm probe\: standalone command to test mirror speeds without installing
- \--test\ / \-t\ flag on \zvm install\: force re-probe, ignore 24h cache
- \--help\ / \-h\ support for all subcommands
- Latency tiebreaker: when bandwidth differs by <10%, lower latency wins

Technical changes:
- mirror_probe.zig: rewrite to sequential probing with NUL device I/O,
  same stream+flush pattern as the real download (streamBodyToFile)
- http_client.zig: add force_probe parameter to attemptMirrorDownload,
  update sort to use greaterThanByBandwidth, fix dead code
- probe.zig: new command implementing standalone mirror speed test
- cli.zig, completion.zig, main.zig: register probe command and
  --help/--test flags across CLI, completion, and dispatch

Author: zcg

.gitignore

@@ -40,3 +40,4 @@ tmp/
 temp/
 .claude/
 
+NUL

src/cli.zig

@@ -4,6 +4,7 @@
 //! and subcommands (vmu zig/zls).
 
 const std = @import("std");
+
 const errors = @import("core/errors.zig");
 
 /// Supported shell types for completion generation.
@@ -21,6 +22,7 @@ pub const Command = enum {
     vmu,
     mirrorlist,
     proxy,
+    probe,
     completion,
     version,
     help,
@@ -38,6 +40,7 @@ pub const InstallFlags = packed struct {
     zls: bool = false,
     full: bool = false,
     nomirror: bool = false,
+    reprobe: bool = false,
 };
 
 /// Flags for the list command.
@@ -83,11 +86,12 @@ pub const ParsedCommand = union(Command) {
     proxy: struct {
         url: ?[]const u8,
     },
+    probe,
     completion: struct {
         shell: ShellType,
     },
     version,
-    help,
+    help: ?Command,
 };
 
 /// Global flags that apply before the command (e.g., --color).
@@ -112,6 +116,7 @@ const command_aliases = std.StaticStringMap(Command).initComptime(.{
     .{ "vmu", .vmu },
     .{ "mirrorlist", .mirrorlist },
     .{ "proxy", .proxy },
+    .{ "probe", .probe },
     .{ "completion", .completion },
     .{ "version", .version },
     .{ "help", .help },
@@ -147,7 +152,7 @@ pub fn parse(allocator: std.mem.Allocator, init: std.process.Init.Minimal) !stru
         } else if (std.mem.cutPrefix(u8, arg, "--color=")) |val| {
             if (parseColorValue(val)) |c| global_flags.color = c;
         } else if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
-            return .{ .global = global_flags, .cmd = .help };
+            return .{ .global = global_flags, .cmd = @unionInit(ParsedCommand, "help", null) };
         } else if (std.mem.eql(u8, arg, "--version") or std.mem.eql(u8, arg, "-v")) {
             return .{ .global = global_flags, .cmd = .version };
         } else {
@@ -158,7 +163,7 @@ pub fn parse(allocator: std.mem.Allocator, init: std.process.Init.Minimal) !stru
         }
     }
 
-    const cmd = maybe_cmd orelse return .{ .global = global_flags, .cmd = .help };
+    const cmd = maybe_cmd orelse return .{ .global = global_flags, .cmd = @unionInit(ParsedCommand, "help", null) };
 
     // Check if the raw command name implies --all
     const auto_all = if (cmd_raw) |raw|
@@ -177,9 +182,10 @@ pub fn parse(allocator: std.mem.Allocator, init: std.process.Init.Minimal) !stru
         .vmu => try parseVmu(allocator, &args),
         .mirrorlist => try parseMirrorlist(allocator, &args),
         .proxy => try parseProxy(allocator, &args),
+        .probe => parseProbe(&args),
         .completion => try parseCompletion(&args),
         .version => ParsedCommand.version,
-        .help => ParsedCommand.help,
+        .help => @unionInit(ParsedCommand, "help", null),
     };
 
     return .{ .global = global_flags, .cmd = parsed };
@@ -208,14 +214,18 @@ fn parseInstall(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     var version: ?[]const u8 = null;
 
     while (args.next()) |arg| {
-        if (std.mem.eql(u8, arg, "--force") or std.mem.eql(u8, arg, "-f")) {
+        if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
+            return .{ .help = .install };
+        } else if (std.mem.eql(u8, arg, "--force") or std.mem.eql(u8, arg, "-f")) {
             flags.force = true;
         } else if (std.mem.eql(u8, arg, "--zls")) {
             flags.zls = true;
         } else if (std.mem.eql(u8, arg, "--full")) {
             flags.full = true;
         } else if (std.mem.eql(u8, arg, "--nomirror")) {
             flags.nomirror = true;
+        } else if (std.mem.eql(u8, arg, "--test") or std.mem.eql(u8, arg, "-t")) {
+            flags.reprobe = true;
         } else {
             version = try allocator.dupe(u8, arg);
         }
@@ -232,7 +242,9 @@ fn parseUse(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     var version: ?[]const u8 = null;
 
     while (args.next()) |arg| {
-        if (std.mem.eql(u8, arg, "--sync")) {
+        if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
+            return @unionInit(ParsedCommand, "help", .use);
+        } else if (std.mem.eql(u8, arg, "--sync")) {
             flags.sync = true;
         } else {
             version = try allocator.dupe(u8, arg);
@@ -249,7 +261,9 @@ fn parseList(args: anytype, auto_all: bool) ParsedCommand {
     var flags: ListFlags = .{ .all = auto_all };
 
     while (args.next()) |arg| {
-        if (std.mem.eql(u8, arg, "--all") or std.mem.eql(u8, arg, "-a")) {
+        if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
+            return @unionInit(ParsedCommand, "help", .list);
+        } else if (std.mem.eql(u8, arg, "--all") or std.mem.eql(u8, arg, "-a")) {
             flags.all = true;
         } else if (std.mem.eql(u8, arg, "--vmu")) {
             flags.vmu = true;
@@ -261,13 +275,19 @@ fn parseList(args: anytype, auto_all: bool) ParsedCommand {
 
 fn parseUninstall(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     const version = args.next() orelse return error.MissingArgument;
+    if (std.mem.eql(u8, version, "--help") or std.mem.eql(u8, version, "-h")) {
+        return @unionInit(ParsedCommand, "help", .uninstall);
+    }
     return .{ .uninstall = .{
         .version = try allocator.dupe(u8, version),
     } };
 }
 
 fn parseRun(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     const version = args.next() orelse return error.MissingArgument;
+    if (std.mem.eql(u8, version, "--help") or std.mem.eql(u8, version, "-h")) {
+        return @unionInit(ParsedCommand, "help", .run);
+    }
 
     var run_args: std.ArrayList([]const u8) = .empty;
     errdefer run_args.deinit(allocator);
@@ -284,6 +304,9 @@ fn parseRun(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
 
 fn parseVmu(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     const subcmd = args.next() orelse return error.MissingArgument;
+    if (std.mem.eql(u8, subcmd, "--help") or std.mem.eql(u8, subcmd, "-h")) {
+        return @unionInit(ParsedCommand, "help", .vmu);
+    }
     const value = args.next() orelse return error.MissingArgument;
 
     const target: VmuTarget = if (std.mem.eql(u8, subcmd, "zig"))
@@ -301,20 +324,44 @@ fn parseVmu(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
 
 fn parseMirrorlist(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     const url = args.next();
-    return .{ .mirrorlist = .{
-        .url = if (url) |u| try allocator.dupe(u8, u) else null,
-    } };
+    if (url) |u| {
+        if (std.mem.eql(u8, u, "--help") or std.mem.eql(u8, u, "-h")) {
+            return @unionInit(ParsedCommand, "help", .mirrorlist);
+        }
+        return .{ .mirrorlist = .{
+            .url = try allocator.dupe(u8, u),
+        } };
+    }
+    return .{ .mirrorlist = .{ .url = null } };
 }
 
 fn parseProxy(allocator: std.mem.Allocator, args: anytype) !ParsedCommand {
     const url = args.next();
-    return .{ .proxy = .{
-        .url = if (url) |u| try allocator.dupe(u8, u) else null,
-    } };
+    if (url) |u| {
+        if (std.mem.eql(u8, u, "--help") or std.mem.eql(u8, u, "-h")) {
+            return @unionInit(ParsedCommand, "help", .proxy);
+        }
+        return .{ .proxy = .{
+            .url = try allocator.dupe(u8, u),
+        } };
+    }
+    return .{ .proxy = .{ .url = null } };
+}
+
+fn parseProbe(args: anytype) ParsedCommand {
+    if (args.next()) |arg| {
+        if (std.mem.eql(u8, arg, "--help") or std.mem.eql(u8, arg, "-h")) {
+            return @unionInit(ParsedCommand, "help", .probe);
+        }
+    }
+    return ParsedCommand.probe;
 }
 
 fn parseCompletion(args: anytype) !ParsedCommand {
     const shell_str = args.next() orelse return error.MissingArgument;
+    if (std.mem.eql(u8, shell_str, "--help") or std.mem.eql(u8, shell_str, "-h")) {
+        return @unionInit(ParsedCommand, "help", .completion);
+    }
     const shell: ShellType = if (std.mem.eql(u8, shell_str, "zsh"))
         .zsh
     else if (std.mem.eql(u8, shell_str, "bash"))
@@ -343,6 +390,7 @@ pub fn printHelp(writer: *std.Io.Writer) !void {
         \\  vmu               Set version map source (zig/zls)
         \\  mirrorlist        Set mirror distribution server
         \\  proxy             Set HTTP/HTTPS proxy for downloads
+        \\  probe             Test mirror speeds without installing
         \\  completion        Generate shell completion script
         \\  version           Print zvm version
         \\  help              Print this help message
@@ -371,6 +419,7 @@ pub fn printCommandHelp(writer: *std.Io.Writer, cmd: Command) !void {
             \\  --zls         Also install ZLS (Zig Language Server)
             \\  --full        Install ZLS with full compatibility mode
             \\  --nomirror    Skip community mirror downloads
+            \\  --test, -t    Force re-probe mirrors (ignore cache)
             \\
             \\Examples:
             \\  zvm install master     Install latest nightly
@@ -470,6 +519,27 @@ pub fn printCommandHelp(writer: *std.Io.Writer, cmd: Command) !void {
             \\  zvm proxy                           Show current proxy setting
             \\
         ),
+        .probe => try writer.writeAll(
+            \\Test mirror download speeds without installing anything.
+            \\
+            \\Downloads data from each mirror for 5 seconds and measures
+            \\throughput. Results are displayed in real-time.
+            \\
+            \\Usage:
+            \\  zvm probe
+            \\
+        ),
+        .completion => try writer.writeAll(
+            \\Generate shell completion script.
+            \\
+            \\Usage:
+            \\  zvm completion <shell>
+            \\
+            \\Examples:
+            \\  zvm completion zsh
+            \\  zvm completion bash
+            \\
+        ),
         .version, .help => printHelp(writer) catch {},
     }
     try writer.flush();

src/command/install.zig

@@ -4,14 +4,15 @@
 //! Optionally installs ZLS (Zig Language Server) alongside Zig.
 
 const std = @import("std");
-const zvm_mod = @import("../core/zvm.zig");
+
 const cli = @import("../cli.zig");
-const platform = @import("../core/platform.zig");
 const Console = @import("../core/Console.zig");
-const version_map = @import("../network/version_map.zig");
+const crypto = @import("../core/crypto.zig");
+const platform = @import("../core/platform.zig");
+const zvm_mod = @import("../core/zvm.zig");
 const http_client = @import("../network/http_client.zig");
+const version_map = @import("../network/version_map.zig");
 const archive = @import("archive.zig");
-const crypto = @import("../core/crypto.zig");
 
 /// Main entry point for the `zvm install` command.
 /// Resolves the requested version, checks if already installed,
@@ -110,7 +111,7 @@ fn installVersion(
         try http_client.downloadToFileWithProxy(allocator, zvm.io, zvm.environ_map, tar_url, archive_path, zvm.settings.proxy, stdout);
         break :blk tar_url;
     } else blk: {
-        const mirror_url = http_client.attemptMirrorDownload(allocator, zvm.io, zvm.environ_map, zvm.settings.mirror_list_url, tar_url, archive_path, stdout, stdout, &zvm.settings) catch {
+        const mirror_url = http_client.attemptMirrorDownload(allocator, zvm.io, zvm.environ_map, zvm.settings.mirror_list_url, tar_url, archive_path, stdout, stdout, &zvm.settings, flags.reprobe) catch {
             try http_client.downloadToFileWithProxy(allocator, zvm.io, zvm.environ_map, tar_url, archive_path, zvm.settings.proxy, stdout);
             break :blk tar_url;
         };

src/command/probe.zig

@@ -0,0 +1,106 @@
+//! Probe command — test mirror download speeds without installing.
+//! Fetches the version map and mirror list, probes all mirrors for
+//! latency and throughput, and displays sorted results.
+
+const std = @import("std");
+
+const Console = @import("../core/Console.zig");
+const platform = @import("../core/platform.zig");
+const zvm_mod = @import("../core/zvm.zig");
+const http_client = @import("../network/http_client.zig");
+const mirror_probe = @import("../network/mirror_probe.zig");
+const version_map = @import("../network/version_map.zig");
+
+pub fn run(
+    zvm: *zvm_mod.ZVM,
+    allocator: std.mem.Allocator,
+    console: Console,
+) !void {
+    const stdout = console.stdout.writer;
+    const proxy = zvm.settings.proxy;
+
+    // 1. Fetch version map to get a real tar URL for probing
+    console.plain("Fetching version map...", .{});
+    const parsed_map = version_map.fetchVersionMap(allocator, zvm.io, zvm.environ_map, zvm.settings.version_map_url, proxy) catch {
+        console.err("Failed to fetch version map", .{});
+        return;
+    };
+    defer parsed_map.deinit();
+    const vmap = &parsed_map.value.object;
+
+    // 2. Get master tar URL for the current platform
+    const sys_info = platform.zigStyleSystemInfo();
+    var plat_buf: [128]u8 = undefined;
+    const target = platform.platformTarget(&plat_buf, sys_info);
+
+    const tar_url = version_map.getTarPath("master", target, vmap) catch {
+        console.err("Failed to find download for your platform", .{});
+        return;
+    };
+
+    const filename = if (std.mem.lastIndexOfScalar(u8, tar_url, '/')) |idx| tar_url[idx + 1 ..] else tar_url;
+
+    // 3. Fetch mirror list
+    if (zvm.settings.mirror_list_url.len == 0) {
+        console.err("No mirror list configured. Use 'zvm mirrorlist <url>' to set one.", .{});
+        return;
+    }
+
+    const mirror_list_content = http_client.downloadToMemoryWithProxy(allocator, zvm.io, zvm.environ_map, zvm.settings.mirror_list_url, proxy) catch {
+        console.err("Failed to fetch mirror list", .{});
+        return;
+    };
+    defer allocator.free(mirror_list_content);
+
+    // 4. Parse mirrors (one URL per line)
+    var mirrors: std.ArrayList([]const u8) = .empty;
+    defer mirrors.deinit(allocator);
+
+    var lines = std.mem.splitSequence(u8, mirror_list_content, "\n");
+    while (lines.next()) |line| {
+        const trimmed = std.mem.trim(u8, line, " \r");
+        if (trimmed.len == 0) continue;
+        try mirrors.append(allocator, trimmed);
+    }
+
+    if (mirrors.items.len == 0) {
+        console.err("No mirrors found in mirror list", .{});
+        return;
+    }
+
+    // 5. Probe all mirrors
+    var candidates: std.ArrayList(mirror_probe.MirrorCandidate) = .empty;
+    defer {
+        for (candidates.items) |c| {
+            if (c.owned) allocator.free(c.url);
+        }
+        candidates.deinit(allocator);
+    }
+
+    try mirror_probe.probeAll(allocator, zvm.io, zvm.environ_map, tar_url, &mirrors, filename, proxy, &candidates, stdout);
+
+    // 6. Sort by bandwidth (with latency tiebreaker)
+    std.mem.sort(mirror_probe.MirrorCandidate, candidates.items, {}, mirror_probe.greaterThanByBandwidth);
+
+    // 7. Display sorted summary
+    if (candidates.items.len == 0) {
+        console.plain("  No mirrors responded.", .{});
+        return;
+    }
+
+    try stdout.print("\n  Summary (sorted by speed):\n", .{});
+    for (candidates.items, 1..) |candidate, rank| {
+        var latency_buf: [64]u8 = undefined;
+        var speed_buf: [64]u8 = undefined;
+        const lat_str = if (candidate.latency_ns > 0)
+            mirror_probe.formatLatency(&latency_buf, candidate.latency_ns)
+        else
+            "?";
+        const spd_str = mirror_probe.formatThroughput(&speed_buf, candidate.bandwidth_bps);
+        const marker = if (rank == 1) " <-- fastest" else "";
+        try stdout.print("    {d:>3}. {s:<32} latency: {s:<10} speed: {s}/s{s}\n", .{
+            rank, mirror_probe.shortUrl(candidate.url), lat_str, spd_str, marker,
+        });
+    }
+    try stdout.flush();
+}