diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 09320651..330f06de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,6 +63,15 @@ jobs: if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } go test ./internal/sdk -run '^TestInstall' -count=1 -v if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + - name: Activate vfox in PowerShell with a non-ASCII PATH + shell: pwsh + env: + # The test changes nothing in the registry, but its fixture selects SDKs + # like the build job does, so it needs the same runner. + VFOX_TEST_WINDOWS_REGISTRY: '1' + run: | + go test ./cmd/commands -run '^TestPowerShellSessionKeepsNonASCIIPath$' -count=1 -v + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } nushell: name: Nushell integration diff --git a/AGENTS.md b/AGENTS.md index 53278e3b..d7f5cacf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,7 +75,7 @@ Keep imports acyclic. Shared utilities must not depend on SDK, plugin, environme - Register command definitions in [cmd/cmd.go](cmd/cmd.go). Helpers and platform-specific files may share a command implementation. - Use `CategorySDK` or `CategoryPlugin` for commands belonging to those groups. Utility commands may be uncategorized. - Keep `activate` hidden unless CLI visibility changes are part of the task. Users still invoke `vfox activate ` during shell setup. -- Activation and environment output is evaluated by the shell; keep unrelated output out of generated shell code. Diagnostics belong to `use` and `doctor`, never to `activate` or `env`; `env` runs at every prompt, so it gets no new checks. +- Activation and environment output is evaluated by the shell; keep unrelated output out of generated shell code. PowerShell output stays ASCII (`PowerShellEscape` in [powershell.go](internal/shell/powershell.go)): PowerShell decodes a native command's output with the console's code page before the hook can switch the console to UTF-8. Diagnostics belong to `use` and `doctor`, never to `activate` or `env`; `env` runs at every prompt, so it gets no new checks. - SDK argument parsing is command-specific. Check the relevant parser before changing version prefixes, `@latest`, or `exec` arguments and its `--` separator. - `link` registers an SDK that already exists (`@ `, or `--detect` through the plugin's `Detect` hook); the version name is used as written. `doctor` prints findings or `--json` and exits with status 1 only for error findings; `doctor --adopt` writes missing receipts. `alias` edits only the `aliases` key of the user config through `config.AliasFile`, which is built on `config.File` (the YAML-document editor that `vfox config` uses for any key): never save a whole `Config` for that, which would write every default as a section the user declared, and keep sections the file does not declare undeclared so they follow the shared config. `install --reinstall` needs the exact installed version and refuses linked ones. - Aliases are resolved for command-line input only (`use`, `uninstall`, `info`, `exec`, `doctor`), through `Manager.ResolveAlias`: an installed version of the same name wins. Never resolve them in version files or in `env`/`activate`. diff --git a/cmd/commands/activate_test.go b/cmd/commands/activate_test.go index 18b31bf4..eca58f54 100644 --- a/cmd/commands/activate_test.go +++ b/cmd/commands/activate_test.go @@ -44,6 +44,27 @@ func TestRenderActivateScriptForIDEEnvironmentResolutionSkipsHookSessionState(t } } +func TestRenderActivateScriptPowerShellIsASCII(t *testing.T) { + path := `C:\用户\bin;C:\Windows` + got, err := renderActivateScript("pwsh", "C:/用户/vfox.exe", nil, env.Vars{ + "PATH": &path, + env.OrigPathFlag: &path, + }, false) + if err != nil { + t.Fatalf("renderActivateScript() failed: %v", err) + } + // PowerShell reads what `vfox activate` prints with the console's code page, + // which is not UTF-8 on a Chinese Windows, before the script can change it. + for i := 0; i < len(got); i++ { + if got[i] >= 0x80 { + t.Fatalf("the PowerShell activation script has a non-ASCII byte at %d:\n%s", i, got) + } + } + if !strings.Contains(got, "$env:PATH=") { + t.Fatalf("the PowerShell activation script does not set PATH:\n%s", got) + } +} + func TestRenderActivateScriptPassesNushellConfigPath(t *testing.T) { configDir := t.TempDir() diff --git a/cmd/commands/nushell_cli_test.go b/cmd/commands/nushell_cli_test.go index f7a94a85..09b400fb 100644 --- a/cmd/commands/nushell_cli_test.go +++ b/cmd/commands/nushell_cli_test.go @@ -56,7 +56,12 @@ func buildVfox(t *testing.T) string { if err != nil { t.Fatalf("the go command is needed to build vfox for this test: %v", err) } - bin := filepath.Join(t.TempDir(), "vfox") + name := "vfox" + if runtime.GOOS == "windows" { + // go build takes an explicit -o name as it is, and Windows runs only .exe files. + name += ".exe" + } + bin := filepath.Join(t.TempDir(), name) ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) defer cancel() cmd := exec.CommandContext(ctx, goTool, "build", "-buildvcs=false", "-o", bin, ".") diff --git a/cmd/commands/powershell_cli_test.go b/cmd/commands/powershell_cli_test.go new file mode 100644 index 00000000..78cb4c31 --- /dev/null +++ b/cmd/commands/powershell_cli_test.go @@ -0,0 +1,107 @@ +package commands + +import ( + "context" + "encoding/base64" + "os" + "os/exec" + "path/filepath" + "runtime" + "slices" + "strings" + "testing" + "time" + + "github.com/version-fox/vfox/internal/shared/util" +) + +// powerShellProbe runs in PowerShell with its console reading native output as +// code page 936, the one Simplified Chinese Windows uses. It activates vfox the +// way the README does, then prints the session as base64, so that the report +// does not depend on the code page either. The errors come last: they may span +// lines. +const powerShellProbe = ` +$ErrorActionPreference = 'Continue' +try { [System.Text.Encoding]::RegisterProvider([System.Text.CodePagesEncodingProvider]::Instance) } catch { } +[Console]::OutputEncoding = [System.Text.Encoding]::GetEncoding(936) +$codePage = [Console]::OutputEncoding.CodePage +$Error.Clear() +Invoke-Expression "$(& $env:VFOX_TEST_VFOX activate pwsh)" +$nl = [char]10 +$hookErrors = ($Error | ForEach-Object { $_.ToString() }) -join $nl +$report = 'CP=' + $codePage + $nl + 'PATH=' + $env:PATH + $nl + 'INITIALIZED=' + $env:__VFOX_INITIALIZED + $nl + 'ERRORS=' + $hookErrors +[Console]::Out.Write([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($report))) +` + +// powerShells returns the PowerShells that run the session test: Windows +// PowerShell and PowerShell 7, whichever is installed. +func powerShells(t *testing.T) []string { + t.Helper() + var found []string + for _, name := range []string{"powershell", "pwsh"} { + if path, err := exec.LookPath(name); err == nil { + found = append(found, path) + } + } + if len(found) == 0 { + t.Skip("neither powershell nor pwsh is installed") + } + return found +} + +// probeFields decodes the report that powerShellProbe prints. +func probeFields(t *testing.T, r cliResult) (codePage, path, initialized, hookErrors string) { + t.Helper() + raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(r.stdout)) + if err != nil { + t.Fatalf("the probe printed no base64 report (%v)\nstdout: %q\nstderr: %s", err, r.stdout, r.stderr) + } + lines := strings.SplitN(string(raw), "\n", 4) + if len(lines) != 4 { + t.Fatalf("the probe report has %d lines, want 4:\n%s\nstderr: %s", len(lines), raw, r.stderr) + } + return strings.TrimPrefix(lines[0], "CP="), strings.TrimPrefix(lines[1], "PATH="), + strings.TrimPrefix(lines[2], "INITIALIZED="), strings.TrimPrefix(lines[3], "ERRORS=") +} + +// TestPowerShellSessionKeepsNonASCIIPath activates vfox in PowerShell whose +// console reads native output with a Chinese code page, and checks that the +// session starts with the non-ASCII PATH entry it was given. The vfox executable +// lives below a non-ASCII directory too, as it does for a user whose name is not +// ASCII. Windows only: the console code page is a Windows setting. +func TestPowerShellSessionKeepsNonASCIIPath(t *testing.T) { + if runtime.GOOS != "windows" { + t.Skip("the console code page that garbles the output is a Windows setting") + } + f := newCLIFixture(t, false) + vfox := buildVfox(t) + vfoxDir := filepath.Join(f.root, "中文", "bin") + must(t, os.MkdirAll(vfoxDir, 0755)) + vfoxExe := filepath.Join(vfoxDir, "vfox.exe") + must(t, os.Rename(vfox, vfoxExe)) + entry := filepath.Join(f.root, "用户工具", "bin") + must(t, os.MkdirAll(entry, 0755)) + f.env["PATH"] = pathList(entry, f.system) + f.env["VFOX_TEST_VFOX"] = vfoxExe + + for _, shell := range powerShells(t) { + t.Run(filepath.Base(shell), func(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + r := runCommand(t, f.command(ctx, shell, "-NoProfile", "-NonInteractive", "-EncodedCommand", util.PowerShellEncodedCommand(powerShellProbe))) + codePage, path, initialized, hookErrors := probeFields(t, r) + if codePage != "936" { + t.Fatalf("the console took code page %q, not 936, so the output is not read the way a Chinese Windows reads it\nstderr: %s", codePage, r.stderr) + } + if !slices.Contains(strings.Split(path, string(os.PathListSeparator)), entry) { + t.Errorf("the session starts with PATH %q, which lost the entry %q", path, entry) + } + if initialized != "1" { + t.Errorf("the hook did not finish (__VFOX_INITIALIZED = %q)", initialized) + } + if hookErrors != "" { + t.Errorf("activating vfox reported errors:\n%s", hookErrors) + } + }) + } +} diff --git a/internal/shell/powershell.go b/internal/shell/powershell.go index 5cbb3f79..8112fb6d 100644 --- a/internal/shell/powershell.go +++ b/internal/shell/powershell.go @@ -17,8 +17,10 @@ package shell import ( + "encoding/base64" "fmt" "regexp" + "strings" "github.com/version-fox/vfox/internal/env" ) @@ -29,13 +31,16 @@ type pwsh struct{} // Pwsh shell instance var Pwsh Shell = pwsh{} +// hook is a template. {{.EnvContent}} is the export of the environment, and +// {{.SelfPath}} stands for the vfox executable: Activate puts that in as a +// PowerShell expression, see PowerShellEscape. const hook = ` {{.EnvContent}} <# Due to a bug in PowerShell, we have to cleanup first when the shell open. #> -& '{{.SelfPath}}' env --cleanup 2>$null | Out-Null; +& {{.SelfPath}} env --cleanup 2>$null | Out-Null; $env:__VFOX_PID = $pid; $env:__VFOX_SHELL = 'pwsh'; @@ -46,7 +51,7 @@ if (-not $env:__VFOX_INITIALIZED) { $env:__VFOX_INITIALIZED = '1'; $originalPrompt = $function:prompt; function prompt { - $export = &"{{.SelfPath}}" env -s pwsh; + $export = & {{.SelfPath}} env -s pwsh; if ($export) { Invoke-Expression -Command $export; } @@ -54,13 +59,19 @@ if (-not $env:__VFOX_INITIALIZED) { } Register-EngineEvent -SourceIdentifier VfoxCleanup -Action { - &"{{.SelfPath}}" env --cleanup + & {{.SelfPath}} env --cleanup } | Out-Null; } ` func (sh pwsh) Activate(config ActivateConfig) (string, error) { - return hook, nil + // text/template reads "{{" in a path as the start of an action. A path that + // has it takes the encoded form, which has no braces. + self := PowerShellEscape(config.SelfPath) + if strings.Contains(config.SelfPath, "{{") { + self = powerShellUTF8(config.SelfPath) + } + return strings.ReplaceAll(hook, "{{.SelfPath}}", self), nil } func (sh pwsh) Export(e env.Vars) (out string) { @@ -75,103 +86,55 @@ func (sh pwsh) Export(e env.Vars) (out string) { } func (sh pwsh) export(key, value string) string { - value = sh.escape(value) - if !regexp.MustCompile(`'.*'`).MatchString(value) { - value = fmt.Sprintf("'%s'", value) + if !isEnvName(key) { + return fmt.Sprintf("[System.Environment]::SetEnvironmentVariable(%s,%s);", PowerShellEscape(key), PowerShellEscape(value)) } - return fmt.Sprintf("$env:%s=%s;", sh.escape(key), value) + return fmt.Sprintf("$env:%s=%s;", key, PowerShellEscape(value)) } func (sh pwsh) unset(key string) string { - return fmt.Sprintf("Remove-Item -Path 'env:/%s';", sh.escape(key)) + if !isEnvName(key) { + // From PowerShell 7.5 on, a $null value only empties the variable; + // [NullString]::Value removes it. + return fmt.Sprintf("[System.Environment]::SetEnvironmentVariable(%s,[NullString]::Value);", PowerShellEscape(key)) + } + return fmt.Sprintf("Remove-Item -Path 'env:/%s';", key) } -func (pwsh) escape(str string) string { - return PowerShellEscape(str) +// envName matches the names that $env: can spell without quotes. +var envName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`) + +func isEnvName(key string) bool { + return envName.MatchString(key) } +// PowerShellEscape returns a PowerShell expression that evaluates to str. +// +// PowerShell decodes the output of a native command with the console's code +// page, and the hook can switch the console to UTF-8 only after the output of +// `vfox activate` has been decoded. On many Windows systems that page is not +// UTF-8, so the output must be ASCII. Printable ASCII becomes a single-quoted +// literal, in which the only escape is a doubled quote. Anything else becomes +// the base64 of its UTF-8 bytes, which PowerShell decodes when the expression runs. func PowerShellEscape(str string) string { - if str == "" { - return "''" - } - in := []byte(str) - out := "" - i := 0 - l := len(in) - escape := false - - hex := func(char byte) { - escape = true - out += fmt.Sprintf("\\x%02x", char) - } - - backslash := func(char byte) { - escape = true - out += string([]byte{BACKTICK, char}) - } - - escaped := func(str string) { - escape = true - out += str - } - - quoted := func(char byte) { - escape = true - out += string([]byte{char}) + if isPrintableASCII(str) { + return "'" + strings.ReplaceAll(str, "'", "''") + "'" } + return powerShellUTF8(str) +} - literal := func(char byte) { - out += string([]byte{char}) - } +// powerShellUTF8 is the expression that decodes the base64 of the UTF-8 bytes of str. +func powerShellUTF8(str string) string { + return "([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('" + + base64.StdEncoding.EncodeToString([]byte(str)) + "')))" +} - for i < l { - char := in[i] - switch { - case char == ACK: - hex(char) - case char == TAB: - escaped("`t") - case char == LF: - escaped("`n") - case char == CR: - escaped("`r") - case char <= US: - hex(char) - // case char <= AMPERSTAND: - // quoted(char) - case char == SINGLE_QUOTE: - backslash(char) - case char <= PLUS: - quoted(char) - case char <= NINE: - literal(char) - // case char <= QUESTION: - // quoted(char) - case char <= UPPERCASE_Z: - literal(char) - // case char == OPEN_BRACKET: - // quoted(char) - // case char == BACKSLASH: - // quoted(char) - case char == UNDERSCORE: - literal(char) - // case char <= CLOSE_BRACKET: - // quoted(char) - // case char <= BACKTICK: - // quoted(char) - // case char <= TILDA: - // quoted(char) - case char == DEL: - hex(char) - default: - quoted(char) +// isPrintableASCII reports whether every byte of str is a printable ASCII character. +func isPrintableASCII(str string) bool { + for i := 0; i < len(str); i++ { + if str[i] < 0x20 || str[i] > 0x7e { + return false } - i++ } - - if escape { - out = "'" + out + "'" - } - - return out + return true } diff --git a/internal/shell/powershell_test.go b/internal/shell/powershell_test.go new file mode 100644 index 00000000..57c5fa2e --- /dev/null +++ b/internal/shell/powershell_test.go @@ -0,0 +1,199 @@ +package shell + +import ( + "bytes" + "context" + "encoding/base64" + "os/exec" + "path/filepath" + "strings" + "testing" + "text/template" + "time" + + "github.com/version-fox/vfox/internal/env" + "github.com/version-fox/vfox/internal/shared/util" +) + +// powerShellValue evaluates an expression the way PowerShell reads it, for the +// two forms PowerShellEscape returns: a single-quoted literal, whose only escape +// is a doubled quote, and the decoding of base64 UTF-8. Anything else fails the +// test. +func powerShellValue(t *testing.T, expr string) string { + t.Helper() + const decodePrefix = "([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('" + const decodeSuffix = "')))" + switch { + case strings.HasPrefix(expr, decodePrefix) && strings.HasSuffix(expr, decodeSuffix): + raw, err := base64.StdEncoding.DecodeString(strings.TrimSuffix(strings.TrimPrefix(expr, decodePrefix), decodeSuffix)) + if err != nil { + t.Fatalf("%q does not decode: %v", expr, err) + } + return string(raw) + case len(expr) >= 2 && strings.HasPrefix(expr, "'") && strings.HasSuffix(expr, "'"): + body := expr[1 : len(expr)-1] + if strings.Contains(strings.ReplaceAll(body, "''", ""), "'") { + t.Fatalf("%q has a quote that does not close the literal", expr) + } + return strings.ReplaceAll(body, "''", "'") + } + t.Fatalf("%q is neither a single-quoted literal nor the decoding of base64", expr) + return "" +} + +// isASCIIText reports whether s holds only ASCII bytes. +func isASCIIText(s string) bool { + for i := 0; i < len(s); i++ { + if s[i] >= 0x80 { + return false + } + } + return true +} + +// PowerShell reads the output of a native command with the console's code page, +// so what vfox prints for it has to be ASCII, and it has to mean the value. +func TestPowerShellEscapeIsASCIIAndMeansTheValue(t *testing.T) { + for _, value := range []string{ + "", + `C:\bin`, + "C:/Program Files (x86)/vfox", + "it's a 'quoted' value", + "a$b`c\"d", + "{{ not an action }}", + "tab\tand\nnewline\rand control \x01", + "C:\\用户\\bin", + "emoji 😀 and a typographic quote’s", + } { + expr := PowerShellEscape(value) + if !isASCIIText(expr) { + t.Errorf("PowerShellEscape(%q) = %q is not ASCII", value, expr) + } + if got := powerShellValue(t, expr); got != value { + t.Errorf("PowerShellEscape(%q) = %q, which PowerShell reads as %q", value, expr, got) + } + } +} + +func TestPwshExportIsASCII(t *testing.T) { + path := "C:\\用户\\bin;C:\\Windows" + version := "1.0.0" + out := Pwsh.Export(env.Vars{ + "PATH": &path, + "ALPHA_VERSION": &version, + "WITH.DOT": &version, + "GONE": nil, + }) + if !isASCIIText(out) { + t.Fatalf("Export returned text that is not ASCII:\n%s", out) + } + for _, want := range []string{ + "$env:ALPHA_VERSION='1.0.0';", + "$env:PATH=" + PowerShellEscape(path) + ";", + // A name that $env: cannot spell goes through the .NET API. + "[System.Environment]::SetEnvironmentVariable('WITH.DOT','1.0.0');", + "Remove-Item -Path 'env:/GONE';", + } { + if !strings.Contains(out, want) { + t.Errorf("Export is missing %q:\n%s", want, out) + } + } + if got := Pwsh.Export(env.Vars{"WITH.DOT": nil}); got != "[System.Environment]::SetEnvironmentVariable('WITH.DOT',[NullString]::Value);" { + t.Errorf("unset of a name that $env: cannot spell = %q", got) + } +} + +func TestPwshActivateHookIsASCIIAndStillATemplate(t *testing.T) { + for _, self := range []string{ + "C:/Users/张三/scoop/apps/vfox/current/vfox.exe", // a user name that is not ASCII + "C:/Users/O'Brien/vfox.exe", + "C:/{{odd}}/vfox.exe", // text/template would read {{ as the start of an action + } { + script, err := Pwsh.Activate(ActivateConfig{SelfPath: self}) + if err != nil { + t.Fatalf("Activate(%q): %v", self, err) + } + if !isASCIIText(script) { + t.Errorf("Activate(%q) is not ASCII:\n%s", self, script) + } + // renderActivateScript executes the script as a template, with the export as EnvContent. + tmpl, err := template.New("hook").Parse(script) + if err != nil { + t.Fatalf("Activate(%q) is not a template: %v", self, err) + } + var buf bytes.Buffer + if err := tmpl.Execute(&buf, struct{ SelfPath, EnvContent string }{self, "$env:ALPHA_VERSION='1.0.0';"}); err != nil { + t.Fatalf("executing the hook for %q: %v", self, err) + } + hook := buf.String() + if !strings.Contains(hook, "$env:ALPHA_VERSION='1.0.0';") { + t.Errorf("the hook for %q does not hold the export:\n%s", self, hook) + } + // The first line of the hook runs vfox by the path it was given. + end := strings.Index(hook, " env --cleanup 2>$null") + if end < 0 { + t.Fatalf("the hook for %q has no cleanup call:\n%s", self, hook) + } + head := hook[:end] + start := strings.LastIndex(head, "& ") + if start < 0 { + t.Fatalf("the cleanup call of the hook for %q is not a call operator:\n%s", self, hook) + } + if got := powerShellValue(t, head[start+len("& "):]); got != self { + t.Errorf("the hook runs %q for %q", got, self) + } + } +} + +// powerShells returns the PowerShells on this machine: Windows PowerShell and +// PowerShell 7, whichever is installed. The native test skips without one. +func powerShells(t *testing.T) []string { + t.Helper() + var found []string + for _, name := range []string{"powershell", "pwsh"} { + if path, err := exec.LookPath(name); err == nil { + found = append(found, path) + } + } + if len(found) == 0 { + t.Skip("neither powershell nor pwsh is installed") + } + return found +} + +// TestPwshUnsetRemovesVariableInPowerShell runs the export of a value and then +// its unset, as Export writes them, in each PowerShell on this machine, and +// checks what the session holds afterwards. The text assertions cannot show the +// difference: from PowerShell 7.5 on, SetEnvironmentVariable(name, $null) only +// empties the variable, so a name that $env: cannot spell must be unset with +// [NullString]::Value instead. +func TestPwshUnsetRemovesVariableInPowerShell(t *testing.T) { + shells := powerShells(t) + for _, name := range []string{"PLAIN_NAME", "WITH.DOT"} { + value := "present" + script := "$ErrorActionPreference = 'Stop';\n" + + Pwsh.Export(env.Vars{name: &value}) + "\n" + + "$before = [System.Environment]::GetEnvironmentVariable('" + name + "');\n" + + Pwsh.Export(env.Vars{name: nil}) + "\n" + + "$exists = Test-Path -LiteralPath 'Env:" + name + "';\n" + + "$after = [System.Environment]::GetEnvironmentVariable('" + name + "');\n" + + "Write-Output ('set=' + $before + ' exists=' + $exists + ' null=' + ($null -eq $after));\n" + for _, shell := range shells { + t.Run(name+" in "+filepath.Base(shell), func(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + cmd := exec.CommandContext(ctx, shell, "-NoProfile", "-NonInteractive", "-EncodedCommand", util.PowerShellEncodedCommand(script)) + var stderr bytes.Buffer + cmd.Stderr = &stderr + out, err := cmd.Output() + if err != nil { + t.Fatalf("%s: %v\nstdout: %s\nstderr: %s", shell, err, out, stderr.String()) + } + const want = "set=present exists=False null=True" + if got := strings.TrimSpace(strings.ReplaceAll(string(out), "\r\n", "\n")); got != want { + t.Errorf("%s reports %q after the unset of %s, want %q\nstderr: %s", shell, got, name, want, stderr.String()) + } + }) + } + } +}