Rewrite README prose: cut repeated self-assurance, tighten sentences

The old version restated "independently implemented"/"original to
this project" in three separate places, which reads as protesting
too much rather than as confidence. Credits the msvc-wine inspiration
once, plainly, and drops the rest. Also split several overlong
comma-chained sentences, fixed the WDK section (a sentence was cut in
half by its own code block), and cleaned up the license paragraph's
phrasing. Content is unchanged - verified the two claims most worth
double-checking (the clang-cl/lld-link path, and that `stplr install
nivora/vintner` actually resolves) rather than just rewording them.

.github/workflows/ci.yml

@@ -43,3 +43,13 @@ jobs:
 
       - name: go test
         run: go test ./...
+
+      - name: staticcheck
+        uses: dominikh/staticcheck-action@9716614d4101e79b4340dd97b10e54d68234e431 # v1.4.1
+        with:
+          version: latest
+          # Staticcheck itself needs a newer Go than the 1.23 this repo
+          # targets (go.mod's floor) - let the action install its own,
+          # separate from the "Set up Go" step above. min-go-version
+          # defaults to reading go.mod, so diagnostics still target 1.23.
+          install-go: true

README.md

@@ -1,37 +1,92 @@
 # vintner
 
-Cross compile with MSVC on Linux, using Wine — a single-binary Go tool
+[![CI](https://github.com/Cheviiot/vintner/actions/workflows/ci.yml/badge.svg)](https://github.com/Cheviiot/vintner/actions/workflows/ci.yml)
-inspired by [mstorsjo/msvc-wine](https://github.com/mstorsjo/msvc-wine)'s
+[![Release](https://img.shields.io/github/v/release/Cheviiot/vintner)](https://github.com/Cheviiot/vintner/releases/latest)
-approach (download the real MSVC/WinSDK, wrap the compiler under Wine),
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-implemented independently.
 
-Once installed, you invoke the real Microsoft toolchain exactly like on
+vintner cross-compiles with the real MSVC toolchain on Linux, using Wine.
-Windows: `cl`, `link`, `lib`, `rc`, `midl`, `mc`, `mt`, `dumpbin`, `msbuild`,
+One Go binary drops in as `cl`, `link`, `lib`, `rc`, `midl`, `mc`, `mt`,
-`nmake`, `ml`, `ml64`, `armasm`, `armasm64`, plus trivial `cmd`/`findstr`
+`dumpbin`, `msbuild`, `nmake`, `ml`, `ml64`, `armasm`, `armasm64`, plus
-shims, all just work from your `PATH`.
+`cmd`/`findstr` shims, so once installed you invoke the real Microsoft
+tools exactly like on Windows. It handles full MSBuild projects, and with
+`--with-wdk`, real KMDF/UMDF Windows drivers.
+
+Inspired by [mstorsjo/msvc-wine](https://github.com/mstorsjo/msvc-wine)'s
+approach: download the real MSVC/WinSDK, wrap the compiler under Wine.
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [Building drivers (WDK)](#building-drivers-wdk)
+- [Language](#language)
+- [Shell completion](#shell-completion)
+- [Using clang-cl/lld-link instead of Wine](#using-clang-cllld-link-instead-of-wine)
+- [toolrelay.exe](#toolrelayexe)
+- [Compatibility patches](#compatibility-patches)
+- [Building from source](#building-from-source)
+- [License](#license)
 
 ## How it works
 
-`vintner` is one Go binary that behaves differently depending on the name
+vintner is a multi-call binary, like busybox: it behaves differently
-it's invoked as (a "multi-call binary", like busybox):
+depending on the name it's invoked as.
 
-- Invoked as `cl`, `link`, `lib`, ... → it loads a small per-architecture
+- As `cl`, `link`, `lib`, and the rest: it loads a per-architecture
-  `env.json`, builds the `INCLUDE`/`LIB`/`WINEPATH` environment Wine needs,
+  `env.json`, sets `INCLUDE`/`LIB`/`WINEPATH`, and rewrites absolute Unix
-  rewrites absolute unix paths in the arguments into Wine's `z:\...` form
+  paths in the arguments to Wine's `z:\...` form (Wine and cl.exe
-  (working around [a Wine/cl.exe include-path bug](https://bugs.winehq.org/show_bug.cgi?id=55200)),
+  otherwise mishandle relative includes — see
-  runs the real `.exe` under `wine`/`wine64`, and rewrites the tool's output
+  [winehq bug 55200](https://bugs.winehq.org/show_bug.cgi?id=55200)). It
-  back from `z:\...` paths to plain unix paths so your build system's error
+  then runs the real `.exe` under `wine`/`wine64`, and rewrites `z:\...`
+  paths back to Unix paths in the output, so your build system's error
   parsing keeps working.
-- Invoked as `vintner` → it exposes the `download`, `install`, `env` and
+- As `vintner`: it exposes the `download`, `install`, `env`, `version`
-  `version` management subcommands described below (each also has a short
+  and `completion` subcommands below (short aliases: `dl`, `i`, `e`, `v`;
-  alias: `dl`, `i`, `e`, `v`; `help`/`h` prints usage).
+  `help`/`h` prints usage).
+
+## Installation
+
+On ALT Linux, via [Nivora](https://github.com/Cheviiot/Nivora):
+
+```bash
+stplr install nivora/vintner
+```
+
+Prebuilt binary, from the [latest release](https://github.com/Cheviiot/vintner/releases/latest):
+
+```bash
+curl -fLo vintner "https://github.com/Cheviiot/vintner/releases/latest/download/vintner-linux-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
+chmod +x vintner
+sudo install vintner /usr/local/bin/vintner
+```
+
+From source: see [Building from source](#building-from-source).
+
+Either way, `wine`/`wine64`, `msitools` (for `msiextract`) and `git` need
+to be on `PATH` at run time. Nivora installs pull these in automatically
+as package dependencies.
+
+### Prerequisites
+
+- `wine` (or `wine64`) — runs the real `cl.exe`/`link.exe`/etc.
+- `msitools` (`msiextract`) — unpacks the `.msi` payloads MSVC/WinSDK ship as.
+- `git` — applies the compatibility patches bundled with `download` (see
+  [Compatibility patches](#compatibility-patches)).
+
+On ALT Linux:
+
+```bash
+pkcon install wine msitools git
+```
 
 ## Quick start
 
 ```bash
-# 1. Download and unpack MSVC + Windows SDK into ~/.vintner (requires
+# 1. Download and unpack MSVC + Windows SDK into ~/.vintner (accepts
-#    accepting Microsoft's Visual Studio Build Tools license, and msitools
+#    Microsoft's Visual Studio Build Tools license). Pass --dest <dir>
-#    for unpacking .msi payloads). Pass --dest <dir> for a different location.
+#    for a different location.
 vintner download --accept-license
 
 # 2. Wire up the tool wrappers
@@ -42,19 +97,6 @@ export PATH=~/.vintner/bin/x64:$PATH
 cl /nologo /EHsc hello.cpp
 ```
 
-### Prerequisites
-
-- `wine` (or `wine64`) — runs the real `cl.exe`/`link.exe`/etc.
-- `msitools` (`msiextract`) — unpacks the `.msi` payloads MSVC/WinSDK ship as.
-- `git` — used to apply the small compatibility patches bundled with
-  `download` (see Compatibility patches below).
-
-On ALT Linux:
-
-```bash
-pkcon install wine msitools
-```
-
 ## Commands
 
 ```
@@ -63,48 +105,70 @@ vintner install (i) [dir]                                         wire up wrappe
 vintner env (e) --bin <dir>/bin/<arch>                            print INCLUDE/LIB for native clang-cl/lld-link use
 vintner version (v)                                               print the version
 vintner help (h)                                                  print usage
+vintner completion bash|zsh                                       print a shell completion script
 ```
 
 `--dest`/`[dir]` both default to `~/.vintner` when omitted.
 
 `download`'s main options: `--msvc-version`, `--sdk-version`,
-`--architecture`, `--host-arch`, `--only-host`, `--with-wdk` (also fetch the
+`--architecture` (repeatable: `x86`/`x64`/`arm`/`arm64`/`host`),
-Windows Driver Kit, for building KMDF/UMDF drivers), `--ignore`,
+`--host-arch`, `--only-host`, `--with-wdk` (see below), `--ignore`
-`--only-download`, `--only-unpack`, `--keep-unpack`, `--skip-patch`,
+(repeatable), `--only-download`, `--only-unpack`, `--keep-unpack`,
-`--cache`, `--language`, `--include-optional`, `--skip-recommended`,
+`--skip-patch`, `--cache`, `--language`, `--include-optional`,
-`--major`, `--preview`, `--manifest`, `--list-workloads`,
+`--skip-recommended`, `--major`, `--preview`, `--manifest`,
-`--list-components`, `--print-deps-tree`. Run `vintner download -h` for the
+`--list-workloads`, `--list-components`, `--print-deps-tree`. Run
-full list with descriptions.
+`vintner download -h` for the full list with descriptions.
 
 `--list-workloads`/`--list-components` print every workload/component id
-(with its human-readable title) available in the fetched manifest and exit
+and its human-readable title from the fetched manifest, then exit
-without downloading anything - useful for discovering what to pass as a bare
+without downloading anything. Useful for finding what to pass as a bare
-package id or via `--with-*`. `--print-deps-tree` prints the dependency tree
+package id or through `--with-*`. `--print-deps-tree` prints the
-of whatever would actually be selected (honoring every other flag), also
+dependency tree of whatever would actually be selected — honoring every
-without downloading.
+other flag — without downloading anything.
 
-### Building drivers (WDK)
+## Building drivers (WDK)
 
-`vintner download --with-wdk` additionally fetches the Windows Driver Kit
+`--with-wdk` also fetches the Windows Driver Kit: headers, import libs,
-(headers, import libs, and the MSBuild `WindowsKernelModeDriver10.0`/
+and the MSBuild `WindowsKernelModeDriver10.0`/`WindowsUserModeDriver10.0`
-`WindowsUserModeDriver10.0` PlatformToolsets) so `msbuild` can build real
+PlatformToolsets.
-KMDF/UMDF drivers - compiling, linking, INF stamping and the `Inf2Cat`
+
-signability check (with `SignMode=off`) all work under Wine. Verified
+```bash
-end-to-end against a real sample driver from
+vintner download --accept-license --with-wdk
+```
+
+With it, `msbuild` builds real KMDF/UMDF drivers — compiling, linking,
+INF stamping, and the `Inf2Cat` signability check (`SignMode=off`) all
+work under Wine. Tested against a real sample driver from
 [microsoft/Windows-driver-samples](https://github.com/microsoft/Windows-driver-samples).
-Only x64 and arm64 targets have a WDK package upstream (no x86/arm).
+Only x64 and arm64 targets have a WDK package upstream; there's no x86 or
+arm one.
 
-### Language
+## Language
 
-CLI messages (usage text, progress lines, prompts) are in English by
+CLI text (usage, progress lines, prompts) defaults to English. Set
-default. Set `VINTNER_LANG=ru` (or have a `ru`-prefixed `LC_ALL`/
+`VINTNER_LANG=ru` (or a `ru`-prefixed `LC_ALL`/`LC_MESSAGES`/`LANG`, e.g.
-`LC_MESSAGES`/`LANG`, e.g. `ru_RU.UTF-8`) for Russian. Deeper error text
+`ru_RU.UTF-8`) for Russian:
-bubbled up from internal packages stays in English.
 
-### Using clang-cl/lld-link instead of Wine
+```bash
+VINTNER_LANG=ru vintner help
+```
 
-You don't need Wine at all if you drive the (nonredistributable) MSVC/WinSDK
+Error text from internal packages stays in English regardless.
-headers and libraries with Clang/LLD in MSVC-compatible mode:
+
+## Shell completion
+
+```bash
+source <(vintner completion bash)   # or add to ~/.bashrc
+source <(vintner completion zsh)    # or add to ~/.zshrc
+```
+
+Completes subcommands, including the short aliases, `download`'s flags,
+and directory arguments for `install`/`env --bin`.
+
+## Using clang-cl/lld-link instead of Wine
+
+The MSVC/WinSDK headers and libraries work directly with Clang/LLD in
+MSVC-compatible mode. No Wine needed:
 
 ```bash
 eval "$(vintner env --bin ~/.vintner/bin/x64)"
@@ -112,49 +176,44 @@ clang-cl -c hello.c
 lld-link hello.obj -out:hello.exe
 ```
 
+## toolrelay.exe
+
+`install` compiles `assets/vendor/toolrelay.cpp`, a small native Windows
+launcher, with the freshly-installed host-arch `cl.exe`. This is
+best-effort: if `wine` isn't available yet, or the compile fails, install
+still succeeds, and tool invocations just skip it. When present, every
+non-MSBuild tool call is routed through it via two named FIFOs.
+
+That's what lets `mt.exe`'s CMake-compatibility exit code
+(`0x41020001` → `0xbb`) survive Wine's own exit-code truncation: a native
+Windows process can read the real 32-bit exit code via
+`GetExitCodeProcess()` before Wine collapses it to a single byte on the
+way back to Unix.
+
+## Compatibility patches
+
+`download` applies a few small patches (`assets/patches`) to the
+downloaded MSVC/WinSDK tree, so `VsDevCmd.bat` and MSBuild's
+SDK-detection props work without a Windows Registry, which doesn't exist
+under Wine. They look up the SDK directly under the VS install root
+instead of querying the registry, skip telemetry, and don't fail devcmd
+setup when an optional component (ConnectionManagerExe, bundled
+CMake/Ninja) is missing.
+
 ## Building from source
 
 ```bash
 go build -o vintner ./cmd/vintner
+go vet ./...
+go test ./...
 ```
 
-Go 1.23+ is all you need to build it; `wine`/`msitools` are only needed at
+Go 1.23+ builds it. `wine`/`msitools` are only needed at run time, for
-run time (`install`/tool invocation and `download` respectively).
+`install`/tool invocation and `download` respectively.
-
-## toolrelay.exe
-
-`install` compiles `assets/vendor/toolrelay.cpp` (a small native Windows
-launcher, original to this project) with the freshly-installed host-arch
-`cl.exe` (best-effort: if `wine` isn't present yet, or the compile fails,
-install still succeeds and the wrapper runtime just falls back to invoking
-tools directly through wine). When present, every non-MSBuild tool
-invocation is routed through it via two named FIFOs. This is what lets
-`mt.exe`'s CMake-compatibility exit-code translation (`0x41020001` → `0xbb`)
-survive Wine's own exit-code truncation: only a native Windows process
-observing the untranslated code via `GetExitCodeProcess()` can catch it
-before Wine marshals the process exit back to Unix and drops everything but
-the low byte.
-
-## Compatibility patches
-
-`download` applies a handful of small patches (`assets/patches`) to the
-downloaded MSVC/WinSDK tree - independently written for this project - that
-make `VsDevCmd.bat` and MSBuild's SDK-detection props work without a
-Windows Registry (which doesn't exist under Wine): they check the SDK
-directly under the VS install root instead of querying the registry, skip
-telemetry, and don't hard-fail devcmd setup when an optional component
-(ConnectionManagerExe, bundled CMake/Ninja) wasn't downloaded.
-
-## Known gaps
-
-None currently tracked. Download/select/unpack/install, general MSBuild
-projects, WDK driver builds, dependency-tree printing, and
-workload/component listing are all implemented and verified against real
-projects.
 
 ## License
 
-MIT, see [LICENSE.txt](LICENSE.txt) - covers vintner's own source only. The
+MIT (see [LICENSE.txt](LICENSE.txt)) for vintner's own source. The MSVC
-MSVC Build Tools / Windows SDK / WDK that `download` fetches remain governed
+Build Tools, Windows SDK, and WDK that `download` fetches stay under
-by Microsoft's own license (accepted via `--accept-license`), same as with
+Microsoft's own license (accepted via `--accept-license`), same as with
 any other way of obtaining them.

cmd/vintner/completion.go

@@ -0,0 +1,140 @@
+package main
+
+import "fmt"
+
+// runCompletion prints a shell completion script for shell ("bash" or
+// "zsh") to stdout, meant to be sourced directly:
+//
+//	source <(vintner completion bash)   # or add to ~/.bashrc
+//	source <(vintner completion zsh)    # or add to ~/.zshrc
+//
+// The flag lists below are hand-maintained alongside download.go/env.go's
+// flag.FlagSet definitions rather than generated from them - there's no
+// reflection-friendly registry to walk, and the flag set rarely changes.
+func runCompletion(args []string) int {
+	if len(args) != 1 {
+		fmt.Println("usage: vintner completion bash|zsh")
+		return 1
+	}
+	switch args[0] {
+	case "bash":
+		fmt.Print(bashCompletionScript)
+		return 0
+	case "zsh":
+		fmt.Print(zshCompletionScript)
+		return 0
+	default:
+		fmt.Printf("vintner completion: unsupported shell %q (want bash or zsh)\n", args[0])
+		return 1
+	}
+}
+
+const downloadFlags = "--dest --cache --major --preview --manifest --accept-license " +
+	"--msvc-version --sdk-version --host-arch --only-host --language " +
+	"--include-optional --skip-recommended --only-download --only-unpack " +
+	"--keep-unpack --skip-patch --list-workloads --list-components " +
+	"--print-deps-tree --with-wdk --architecture --ignore -h --help"
+
+var bashCompletionScript = `# vintner bash completion - eval "$(vintner completion bash)"
+_vintner_complete() {
+    local cur cmd
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    cmd="${COMP_WORDS[1]}"
+
+    if [ "$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=($(compgen -W "download dl install i env e version v help h completion" -- "$cur"))
+        return 0
+    fi
+
+    case "$cmd" in
+        download|dl)
+            COMPREPLY=($(compgen -W "` + downloadFlags + `" -- "$cur"))
+            ;;
+        install|i)
+            COMPREPLY=($(compgen -d -- "$cur"))
+            ;;
+        env|e)
+            COMPREPLY=($(compgen -W "--bin -h --help" -- "$cur"))
+            ;;
+        completion)
+            COMPREPLY=($(compgen -W "bash zsh" -- "$cur"))
+            ;;
+    esac
+    return 0
+}
+complete -F _vintner_complete vintner
+`
+
+var zshCompletionScript = `#compdef vintner
+# vintner zsh completion - source <(vintner completion zsh)
+
+_vintner() {
+    local -a subcommands
+    subcommands=(
+        'download:fetch and unpack MSVC/WinSDK/WDK'
+        'dl:alias for download'
+        'install:wire up wrappers for a downloaded MSVC'
+        'i:alias for install'
+        'env:print INCLUDE/LIB for native clang-cl/lld-link use'
+        'e:alias for env'
+        'version:print the version'
+        'v:alias for version'
+        'help:print usage'
+        'h:alias for help'
+        'completion:print a shell completion script'
+    )
+
+    if (( CURRENT == 2 )); then
+        _describe 'command' subcommands
+        return
+    fi
+
+    case "${words[2]}" in
+        download|dl)
+            local -a flags
+            flags=(
+                '--dest[directory to install into]:directory:_files -/'
+                '--cache[persistent download cache directory]:directory:_files -/'
+                '--major[major VS version]:version:'
+                '--preview[use the preview/insiders channel]'
+                '--manifest[use a predownloaded installer manifest file]:file:_files'
+                '--accept-license[do not prompt for accepting the license]'
+                '--msvc-version[install a specific MSVC toolchain version]:version:'
+                '--sdk-version[install a specific Windows SDK version]:version:'
+                '--host-arch[host architecture]:arch:(x86 x64 arm64)'
+                '--only-host[only download packages matching the host architecture]'
+                '--language[preferred package language]:language:'
+                '--include-optional[include all optional dependencies]'
+                '--skip-recommended[skip recommended dependencies]'
+                '--only-download[stop after downloading package files]'
+                '--only-unpack[unpack without pruning to just the CLI tools]'
+                '--keep-unpack[keep the scratch unpack dir]'
+                '--skip-patch[do not apply the Wine compatibility patches]'
+                '--list-workloads[list available workloads and exit]'
+                '--list-components[list available components and exit]'
+                '--print-deps-tree[print the dependency tree and exit]'
+                '--with-wdk[also fetch the Windows Driver Kit]'
+                '--architecture[target architecture]:arch:(x86 x64 arm arm64 host)'
+                '--ignore[package id to skip]:package id:'
+                '-h[show help]'
+                '--help[show help]'
+            )
+            _arguments $flags
+            ;;
+        install|i)
+            _files -/
+            ;;
+        env|e)
+            _arguments \
+                '--bin[bin/<arch> directory produced by install]:directory:_files -/' \
+                '-h[show help]' '--help[show help]'
+            ;;
+        completion)
+            _values 'shell' bash zsh
+            ;;
+    esac
+}
+
+_vintner "$@"
+`

cmd/vintner/completion_test.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestCompletionScriptsAreSyntacticallyValid catches the easy way to break
+// these: a typo in the hand-maintained flag lists that produces invalid
+// shell syntax. It shells out to bash/zsh -n rather than parsing the script
+// itself, so it's testing exactly what a user's shell would see.
+func TestCompletionScriptsAreSyntacticallyValid(t *testing.T) {
+	for _, tc := range []struct {
+		shell  string
+		script string
+	}{
+		{"bash", bashCompletionScript},
+		{"zsh", zshCompletionScript},
+	} {
+		t.Run(tc.shell, func(t *testing.T) {
+			if _, err := exec.LookPath(tc.shell); err != nil {
+				t.Skipf("%s not installed", tc.shell)
+			}
+			cmd := exec.Command(tc.shell, "-n", "/dev/stdin")
+			cmd.Stdin = strings.NewReader(tc.script)
+			if out, err := cmd.CombinedOutput(); err != nil {
+				t.Fatalf("%s -n rejected the completion script: %v\n%s", tc.shell, err, out)
+			}
+		})
+	}
+}
+
+func TestRunCompletionUnknownShell(t *testing.T) {
+	if code := runCompletion([]string{"fish"}); code != 1 {
+		t.Errorf("runCompletion([\"fish\"]) = %d, want 1", code)
+	}
+	if code := runCompletion(nil); code != 1 {
+		t.Errorf("runCompletion(nil) = %d, want 1", code)
+	}
+	if code := runCompletion([]string{"bash", "extra"}); code != 1 {
+		t.Errorf("runCompletion with extra arg = %d, want 1", code)
+	}
+}

cmd/vintner/download.go

@@ -45,6 +45,17 @@ func runDownload(args []string) int {
 	}
 	packages := fs.Args()
 
+	for _, a := range archsFlag {
+		if !validArchitectures[a] {
+			fmt.Fprintf(os.Stderr, "vintner download: invalid --architecture %q (expected one of x86, x64, arm, arm64, host)\n", a)
+			return 2
+		}
+	}
+	if *hostArch != "" && !validHostArchs[*hostArch] {
+		fmt.Fprintf(os.Stderr, "vintner download: invalid --host-arch %q (expected one of x86, x64, arm64)\n", *hostArch)
+		return 2
+	}
+
 	opts := &download.Options{
 		Package:         packages,
 		Ignore:          []string(ignoreFlag),
@@ -267,6 +278,9 @@ func printPackageList(headerKey string, pkgs []*download.Package, language strin
 	}
 }
 
+var validArchitectures = map[string]bool{"x86": true, "x64": true, "arm": true, "arm64": true, "host": true}
+var validHostArchs = map[string]bool{"x86": true, "x64": true, "arm64": true}
+
 func detectHostArch() string {
 	if runtime.GOARCH == "arm64" {
 		return "arm64"

cmd/vintner/download_test.go

@@ -0,0 +1,40 @@
+package main
+
+import "testing"
+
+// TestRunDownloadRejectsInvalidArchFlags exercises the validation added
+// after the flags are parsed, which must reject typos before runDownload
+// gets anywhere near the network (FetchChannelManifest) - these tests would
+// hang/fail on network access if that ordering ever regressed.
+func TestRunDownloadRejectsInvalidArchFlags(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{"bad architecture", []string{"--architecture", "x866"}},
+		{"bad architecture, valid mixed with invalid", []string{"--architecture", "x64", "--architecture", "sparc"}},
+		{"bad host-arch", []string{"--host-arch", "sparc"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if code := runDownload(tc.args); code != 2 {
+				t.Errorf("runDownload(%v) = %d, want 2", tc.args, code)
+			}
+		})
+	}
+}
+
+func TestValidArchitectureSets(t *testing.T) {
+	for _, a := range []string{"x86", "x64", "arm", "arm64", "host"} {
+		if !validArchitectures[a] {
+			t.Errorf("validArchitectures[%q] = false, want true", a)
+		}
+	}
+	for _, a := range []string{"x86", "x64", "arm64"} {
+		if !validHostArchs[a] {
+			t.Errorf("validHostArchs[%q] = false, want true", a)
+		}
+	}
+	if validHostArchs["arm"] {
+		t.Error(`validHostArchs["arm"] = true, want false (no 32-bit ARM host toolchain exists)`)
+	}
+}

cmd/vintner/env_test.go

@@ -0,0 +1,23 @@
+package main
+
+import "testing"
+
+func TestRunEnvRequiresBin(t *testing.T) {
+	if code := runEnv(nil); code != 1 {
+		t.Errorf("runEnv(nil) = %d, want 1", code)
+	}
+}
+
+func TestRunEnvRejectsMissingBinDir(t *testing.T) {
+	if code := runEnv([]string{"--bin", "/nonexistent/path/for/vintner/tests"}); code != 1 {
+		t.Errorf("runEnv with a nonexistent --bin = %d, want 1", code)
+	}
+}
+
+func TestToUnixPathList(t *testing.T) {
+	got := toUnixPathList(`z:\vc\include;z:\kits\10\include`)
+	want := "/vc/include;/kits/10/include"
+	if got != want {
+		t.Errorf("toUnixPathList(...) = %q, want %q", got, want)
+	}
+}

cmd/vintner/install_test.go

@@ -0,0 +1,17 @@
+package main
+
+import "testing"
+
+func TestRunInstallRejectsExtraArgs(t *testing.T) {
+	if code := runInstall([]string{"one", "two"}); code != 1 {
+		t.Errorf("runInstall with two args = %d, want 1", code)
+	}
+}
+
+func TestRunInstallHelp(t *testing.T) {
+	for _, flag := range []string{"-h", "--help"} {
+		if code := runInstall([]string{flag}); code != 1 {
+			t.Errorf("runInstall([%q]) = %d, want 1", flag, code)
+		}
+	}
+}

cmd/vintner/main.go

@@ -47,6 +47,8 @@ func runCLI(args []string) int {
 		return runInstall(args[1:])
 	case "env", "e":
 		return runEnv(args[1:])
+	case "completion":
+		return runCompletion(args[1:])
 	case "version", "v", "--version":
 		fmt.Println("vintner " + version)
 		return 0

cmd/vintner/main_test.go

@@ -0,0 +1,30 @@
+package main
+
+import "testing"
+
+// TestRunCLIDispatch covers the subset of runCLI's switch that has no side
+// effects (no filesystem/network touched) - the actual subcommand bodies
+// (download/install/env) get their own focused tests.
+func TestRunCLIDispatch(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+		want int
+	}{
+		{"no args prints usage", nil, 1},
+		{"unknown subcommand", []string{"frobnicate"}, 1},
+		{"help long", []string{"--help"}, 0},
+		{"help short flag", []string{"-h"}, 0},
+		{"help word", []string{"help"}, 0},
+		{"help alias", []string{"h"}, 0},
+		{"version word", []string{"version"}, 0},
+		{"version alias", []string{"v"}, 0},
+		{"version flag", []string{"--version"}, 0},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := runCLI(tc.args); got != tc.want {
+				t.Errorf("runCLI(%v) = %d, want %d", tc.args, got, tc.want)
+			}
+		})
+	}
+}

cmd/vintner/paths_test.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDefaultToolchainDir(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skipf("no home directory available: %v", err)
+	}
+	got, err := defaultToolchainDir()
+	if err != nil {
+		t.Fatalf("defaultToolchainDir() error: %v", err)
+	}
+	want := filepath.Join(home, ".vintner")
+	if got != want {
+		t.Errorf("defaultToolchainDir() = %q, want %q", got, want)
+	}
+}

internal/download/fetch.go

@@ -84,6 +84,9 @@ func FetchPayloads(selected []*Package, cacheDir string, allowHashMismatch bool)
 func fetchOnePayloadWithRetries(payload Payload, dest, fileID string, allowHashMismatch bool) (int64, error) {
 	var lastErr error
 	for attempt := 0; attempt < maxDownloadAttempts; attempt++ {
+		if attempt > 0 {
+			time.Sleep(retryBackoff(attempt))
+		}
 		n, err := tryDownloadPayload(payload, dest, fileID, allowHashMismatch)
 		if err == nil {
 			return n, nil
@@ -94,6 +97,17 @@ func fetchOnePayloadWithRetries(payload Payload, dest, fileID string, allowHashM
 	return 0, fmt.Errorf("giving up on %s after %d attempts: %w", fileID, maxDownloadAttempts, lastErr)
 }
 
+// retryBackoff gives a transient failure (network blip, momentary rate
+// limiting) a little room to clear before hammering the same URL again:
+// 1s, 2s, 4s, 8s, capped at 10s.
+func retryBackoff(attempt int) time.Duration {
+	d := time.Second << uint(attempt-1)
+	if d > 10*time.Second {
+		d = 10 * time.Second
+	}
+	return d
+}
+
 func tryDownloadPayload(payload Payload, dest, fileID string, allowHashMismatch bool) (int64, error) {
 	if fi, err := os.Stat(dest); err == nil && fi.Mode().IsRegular() {
 		if payload.SHA256 != "" {

internal/download/manifest.go

@@ -198,6 +198,9 @@ const maxManifestAttempts = 5
 func httpGet(url string) ([]byte, error) {
 	var lastErr error
 	for attempt := 0; attempt < maxManifestAttempts; attempt++ {
+		if attempt > 0 {
+			time.Sleep(retryBackoff(attempt))
+		}
 		data, err := tryHTTPGet(url)
 		if err == nil {
 			return data, nil

internal/download/select.go

@@ -16,7 +16,6 @@ var reSDKVersion = regexp.MustCompile(`^\d+\.\d+\.\d+`)
 type TriState = *bool
 
 func on() TriState { v := true; return &v }
-func off() TriState { v := false; return &v }
 
 // Options holds every flag that feeds package selection and download.
 type Options struct {
@@ -303,6 +302,7 @@ func selectSDK(opts *Options, idx Index) error {
 			}
 		}
 		if !found {
+			sort.Strings(versions)
 			return fmt.Errorf("WinSDK version %s not found (available: %s)", opts.SDKVersion, strings.Join(versions, ", "))
 		}
 	}
@@ -347,7 +347,14 @@ func collectDependencyClosure(idx Index, included map[string]bool, target string
 	included[key] = true
 
 	ret := []*Package{p}
-	for target, dep := range p.Dependencies() {
+	deps := p.Dependencies()
+	targets := make([]string, 0, len(deps))
+	for target := range deps {
+		targets = append(targets, target)
+	}
+	sort.Strings(targets)
+	for _, target := range targets {
+		dep := deps[target]
 		id := target
 		if dep.TargetID != "" {
 			id = dep.TargetID

internal/download/select_test.go

@@ -193,6 +193,40 @@ func TestAggregateDependsHostArchMismatchExcludes(t *testing.T) {
 	}
 }
 
+// TestExpandSelectionDeterministic guards against collectDependencyClosure
+// iterating a package's dependency map directly (Go map iteration order is
+// randomized per range statement, so a regression here wouldn't necessarily
+// show up on the first run - looping catches it reliably in practice).
+func TestExpandSelectionDeterministic(t *testing.T) {
+	idx := fixtureIndex(t, "x86")
+	opts := &Options{
+		Package:         []string{"Microsoft.VisualStudio.Workload.VCTools"},
+		HostArch:        "x86",
+		OnlyHost:        true,
+		IncludeOptional: true,
+	}
+	first, err := ExpandSelection(idx, opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := idsOf(first)
+	for i := 0; i < 50; i++ {
+		got, err := ExpandSelection(idx, opts)
+		if err != nil {
+			t.Fatal(err)
+		}
+		gotIDs := idsOf(got)
+		if len(gotIDs) != len(want) {
+			t.Fatalf("run %d: got %v, want %v", i, gotIDs, want)
+		}
+		for j := range want {
+			if gotIDs[j] != want[j] {
+				t.Fatalf("run %d: order changed: got %v, want %v", i, gotIDs, want)
+			}
+		}
+	}
+}
+
 func idsOf(pkgs []*Package) []string {
 	var ids []string
 	for _, p := range pkgs {

internal/i18n/i18n.go

@@ -74,6 +74,7 @@ Usage:
   vintner env (e) --bin <dir/bin/arch> print INCLUDE/LIB for native clang-cl/lld-link use
   vintner version (v)                  print the version
   vintner help (h)                     show this message
+  vintner completion bash|zsh          print a shell completion script
 
 Run "vintner <command> --help" for that command's own options - download
 has many, including --with-wdk, --list-workloads, --list-components and
@@ -81,6 +82,7 @@ has many, including --with-wdk, --list-workloads, --list-components and
 
 --dest/[dir] default to ~/.vintner if omitted.
 Language: set VINTNER_LANG=ru (or LANG=ru_RU...) for Russian output.
+Completion: source <(vintner completion bash)  # or zsh
 
 Once installed, add <dir>/bin/<arch> to PATH and invoke the tools directly:
   cl, link, lib, ml, ml64, mc, midl, mt, rc, dumpbin, msbuild, nmake, armasm, armasm64, cmd, findstr
@@ -94,6 +96,7 @@ Once installed, add <dir>/bin/<arch> to PATH and invoke the tools directly:
   vintner env (e) --bin <dir/bin/arch> вывести INCLUDE/LIB для clang-cl/lld-link напрямую
   vintner version (v)                  показать версию
   vintner help (h)                     показать эту справку
+  vintner completion bash|zsh          вывести скрипт автодополнения для оболочки
 
 Запустите «vintner <команда> --help» для параметров конкретной команды —
 у download их много, включая --with-wdk, --list-workloads, --list-components
@@ -101,6 +104,7 @@ Once installed, add <dir>/bin/<arch> to PATH and invoke the tools directly:
 
 --dest/[каталог] по умолчанию — ~/.vintner.
 Язык: установите VINTNER_LANG=en (или LANG=en_US...) для вывода на английском.
+Автодополнение: source <(vintner completion bash)  # или zsh
 
 После установки добавьте <dir>/bin/<arch> в PATH и вызывайте инструменты напрямую:
   cl, link, lib, ml, ml64, mc, midl, mt, rc, dumpbin, msbuild, nmake, armasm, armasm64, cmd, findstr

internal/i18n/i18n_test.go

@@ -0,0 +1,93 @@
+package i18n
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestDetect(t *testing.T) {
+	envKeys := []string{"VINTNER_LANG", "LC_ALL", "LC_MESSAGES", "LANG"}
+	clear := func() {
+		for _, k := range envKeys {
+			t.Setenv(k, "")
+			// t.Setenv("", "") leaves the var set-but-empty, which detect()
+			// already treats as "unset" (its loop skips v == "") - matches
+			// how a genuinely-unset env var behaves for this function.
+		}
+	}
+
+	for _, tc := range []struct {
+		name string
+		env  map[string]string
+		want Lang
+	}{
+		{"nothing set defaults to English", nil, EN},
+		{"VINTNER_LANG=ru", map[string]string{"VINTNER_LANG": "ru"}, RU},
+		{"VINTNER_LANG=en", map[string]string{"VINTNER_LANG": "en"}, EN},
+		{"VINTNER_LANG wins over a Russian LANG", map[string]string{"VINTNER_LANG": "en", "LANG": "ru_RU.UTF-8"}, EN},
+		{"LC_ALL wins over LANG", map[string]string{"LC_ALL": "ru_RU.UTF-8", "LANG": "en_US.UTF-8"}, RU},
+		{"LANG=ru_RU.UTF-8 alone", map[string]string{"LANG": "ru_RU.UTF-8"}, RU},
+		{"LANG=en_US.UTF-8 alone", map[string]string{"LANG": "en_US.UTF-8"}, EN},
+		{"unrelated locale defaults to English", map[string]string{"LANG": "de_DE.UTF-8"}, EN},
+		{"case-insensitive RU prefix", map[string]string{"VINTNER_LANG": "RU"}, RU},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			clear()
+			for k, v := range tc.env {
+				t.Setenv(k, v)
+			}
+			if got := detect(); got != tc.want {
+				t.Errorf("detect() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestCatalogCompleteness guards against adding an EN string without its RU
+// counterpart (or vice versa) - a silent gap here degrades to showing the
+// wrong language's text via T()'s EN-fallback rather than failing loudly.
+func TestCatalogCompleteness(t *testing.T) {
+	for key, entry := range catalog {
+		en, hasEN := entry[EN]
+		if !hasEN || strings.TrimSpace(en) == "" {
+			t.Errorf("catalog[%q] has no (non-empty) English translation", key)
+		}
+		ru, hasRU := entry[RU]
+		if !hasRU || strings.TrimSpace(ru) == "" {
+			t.Errorf("catalog[%q] has no (non-empty) Russian translation", key)
+		}
+	}
+}
+
+func TestTMissingKeyReturnsKeyItself(t *testing.T) {
+	got := T("no.such.key")
+	if got != "no.such.key" {
+		t.Errorf("T(unknown key) = %q, want the key itself", got)
+	}
+}
+
+func TestTFallsBackToEnglish(t *testing.T) {
+	const testKey = "test.fallback.only.en"
+	catalog[testKey] = map[Lang]string{EN: "hello %s"}
+	defer delete(catalog, testKey)
+
+	saved := current
+	current = RU
+	defer func() { current = saved }()
+
+	if got := T(testKey, "world"); got != "hello world" {
+		t.Errorf("T(%q) with no RU entry = %q, want %q", testKey, got, "hello world")
+	}
+}
+
+func TestTFormatsArgs(t *testing.T) {
+	saved := current
+	current = EN
+	defer func() { current = saved }()
+
+	got := T("download.wdk_installed", "x64", "10.0.26100.1", "/dest")
+	want := "Installed WDK (x64) 10.0.26100.1 at /dest\n"
+	if got != want {
+		t.Errorf("T(download.wdk_installed, ...) = %q, want %q", got, want)
+	}
+}

internal/wrapper/native.go

@@ -29,7 +29,13 @@ func execInherit(args []string) int {
 	cmd.Stdin = os.Stdin
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
-	if err := cmd.Run(); err != nil {
+	setNewProcessGroup(cmd)
+	if err := cmd.Start(); err != nil {
+		return 127
+	}
+	stopSignals := forwardSignals(cmd.Process)
+	defer stopSignals()
+	if err := cmd.Wait(); err != nil {
 		if exitErr, ok := err.(*exec.ExitError); ok {
 			return exitErr.ExitCode()
 		}

internal/wrapper/run.go

@@ -91,6 +91,7 @@ func Run(tool string, args []string) int {
 		}
 		cmd.Env = env
 		cmd.Stdin = os.Stdin
+		setNewProcessGroup(cmd)
 		exitCode = runRawStdout(cmd)
 	default:
 		relay := filepath.Join(paths.BaseUnix, "bin", toolRelayName)
@@ -100,6 +101,7 @@ func Run(tool string, args []string) int {
 			cmd := exec.Command(wineBin, append([]string{toolExePath}, rewritten...)...)
 			cmd.Env = buildEnv(paths)
 			cmd.Stdin = os.Stdin
+			setNewProcessGroup(cmd)
 			exitCode = runFiltered(cmd, s.stdoutFilter, s.stderrFilter)
 		}
 	}
@@ -137,6 +139,7 @@ func runViaToolRelay(wineBin, relayExe, exePath string, args []string, paths *wi
 	cmdArgs := append([]string{relayExe, exePath}, args...)
 	cmd := exec.Command(wineBin, cmdArgs...)
 	cmd.Env = append(buildEnv(paths), "MSVCGOWINE_STDOUT="+stdoutFifo, "MSVCGOWINE_STDERR="+stderrFifo)
+	setNewProcessGroup(cmd)
 	if devNull, err := os.OpenFile(os.DevNull, os.O_WRONLY, 0); err == nil {
 		defer devNull.Close()
 		cmd.Stdout = devNull
@@ -147,6 +150,8 @@ func runViaToolRelay(wineBin, relayExe, exePath string, args []string, paths *wi
 		fmt.Fprintln(os.Stderr, "vintner:", err)
 		return 1
 	}
+	stopSignals := forwardSignals(cmd.Process)
+	defer stopSignals()
 
 	var wg sync.WaitGroup
 	wg.Add(2)
@@ -204,6 +209,8 @@ func runRawStdout(cmd *exec.Cmd) int {
 		fmt.Fprintln(os.Stderr, "vintner:", err)
 		return 1
 	}
+	stopSignals := forwardSignals(cmd.Process)
+	defer stopSignals()
 
 	doneOut := make(chan struct{})
 	doneErr := make(chan struct{})
@@ -278,6 +285,8 @@ func runFiltered(cmd *exec.Cmd, stdoutF, stderrF lineFilter) int {
 		fmt.Fprintln(os.Stderr, "vintner:", err)
 		return 1
 	}
+	stopSignals := forwardSignals(cmd.Process)
+	defer stopSignals()
 
 	doneOut := make(chan struct{})
 	doneErr := make(chan struct{})
@@ -310,4 +319,11 @@ func pumpLines(r io.Reader, w *os.File, filter lineFilter) {
 		}
 		fmt.Fprintln(w, line)
 	}
+	// bufio.Scanner silently stops (dropping the rest of the stream) once a
+	// single line exceeds its 16MB buffer - surface that rather than letting
+	// build output vanish without explanation (heavily templated C++ error
+	// messages are the realistic way to hit this).
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(w, "vintner: output truncated: %v\n", err)
+	}
 }

internal/wrapper/signals.go

@@ -0,0 +1,68 @@
+package wrapper
+
+import (
+	"os"
+	"os/exec"
+	"os/signal"
+	"syscall"
+	"time"
+)
+
+// killGrace bounds how long a forwarded SIGINT/SIGTERM gets to make a
+// subprocess tree exit on its own before escalating to SIGKILL - long
+// enough for wineserver to tear down a Windows process tree cleanly, short
+// enough that an unresponsive one doesn't hang vintner's own shutdown.
+const killGrace = 5 * time.Second
+
+// setNewProcessGroup puts cmd's eventual child in its own process group
+// (pgid = its own pid) instead of inheriting vintner's. Without this, a
+// caller that signals vintner by PID alone (a CI runner enforcing a
+// timeout, a supervisor's `kill <pid>`) never reaches the wine/wineserver
+// tree underneath it, which is then reparented to init and keeps running -
+// wasting CPU, holding file locks, leaving stray FIFOs/temp files behind.
+// (Interactive Ctrl-C already reaches every process in the terminal's
+// foreground group regardless of this, but forwardSignals below handles
+// that case too now that the child has moved to its own group.)
+func setNewProcessGroup(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+}
+
+// forwardSignals relays SIGINT/SIGTERM received by vintner itself to
+// proc's entire process group (proc must have been started via a cmd that
+// called setNewProcessGroup, making proc.Pid also the group id), escalating
+// to SIGKILL after killGrace if the group hasn't exited by then. Callers
+// must call the returned stop func once the process has actually exited
+// (e.g. right after cmd.Wait() returns), both to stop listening for
+// signals and to cancel a pending escalation.
+func forwardSignals(proc *os.Process) (stop func()) {
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+	done := make(chan struct{})
+
+	go func() {
+		pgid := -proc.Pid
+		for {
+			select {
+			case sig := <-sigCh:
+				s, ok := sig.(syscall.Signal)
+				if !ok {
+					continue
+				}
+				_ = syscall.Kill(pgid, s)
+				select {
+				case <-time.After(killGrace):
+					_ = syscall.Kill(pgid, syscall.SIGKILL)
+				case <-done:
+					return
+				}
+			case <-done:
+				return
+			}
+		}
+	}()
+
+	return func() {
+		signal.Stop(sigCh)
+		close(done)
+	}
+}

internal/wrapper/signals_test.go

@@ -0,0 +1,43 @@
+package wrapper
+
+import (
+	"os"
+	"os/exec"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// TestForwardSignalsKillsChild verifies the actual mechanism that keeps a
+// wine subprocess from being orphaned: a SIGTERM delivered to the current
+// process (mimicking `kill <vintner-pid>`, not an interactive Ctrl-C) must
+// reach a child started with setNewProcessGroup, even though it's no longer
+// in the same process group.
+func TestForwardSignalsKillsChild(t *testing.T) {
+	cmd := exec.Command("sleep", "30")
+	setNewProcessGroup(cmd)
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("starting sleep: %v", err)
+	}
+	stop := forwardSignals(cmd.Process)
+	defer stop()
+
+	// signal.Notify (inside forwardSignals) intercepts this rather than
+	// letting it terminate the test binary itself.
+	if err := syscall.Kill(os.Getpid(), syscall.SIGTERM); err != nil {
+		t.Fatalf("signaling self: %v", err)
+	}
+
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+
+	select {
+	case err := <-done:
+		if err == nil {
+			t.Fatal("expected the child to be killed by the forwarded signal, but it exited successfully")
+		}
+	case <-time.After(3 * time.Second):
+		cmd.Process.Kill()
+		t.Fatal("child was still running 3s after the signal should have been forwarded")
+	}
+}