refactor(shell-proxy)!: rename env vars to `SHELLPROXY_*` and add usage message (#10456)

BREAKING CHANGE: the `DEFAULT_PROXY` setting has been renamed to `SHELLPROXY_URL`,
and `CONFIG_PROXY` has been renamed to `SHELLPROXY_CONFIG`. See the plugin README
for more information.

Co-authored-by: Marc Cornellà <hello@mcornella.com>

.github/actions/spelling/expect.txt

@@ -3456,6 +3456,7 @@ sheerun
 shellcheck
 shellinit
 shellperson
+SHELLPROXY
 shitload
 SHLVL
 shm

plugins/shell-proxy/README.md

@@ -1,42 +1,56 @@
-# Shell Proxy oh-my-zsh plugin
+# shell-proxy plugin
 
-This a pure user-space program, shell-proxy setter, written Python3 and Bash.
+This a pure user-space program, shell-proxy setter, written in Python3 and Zsh.
 
-100% only no side-effects, only effect **environment variables** and **aliases**
+To use it, add `shell-proxy` to the plugins array in your zshrc file:
 
-## Key feature
+```zsh
+plugins=(... shell-proxy)
+```
+
+## Key features
 
-- Support Ubuntu, Archlinux, etc (Linux)
-- Support macOS
-- Support git via based-`$GIT_SSH`
-- Support ssh, sftp, scp, slogin and ssh-copy-id via based-`alias`
-- Built-in Auto-complete
+- Supports macOS and Linux (Ubuntu, Archlinux, etc.)
+- Supports git via setting `$GIT_SSH`
+- Supports ssh, sftp, scp, slogin and ssh-copy-id via setting aliases
+- Built-in autocomplete
 
 ## Usage
 
-Method 1:
+### Method 1
 
-`$DEFAULT_PROXY` is the proxy URL you will set
+Set `SHELLPROXY_URL` environment variable to the URL of the proxy server:
 
-Method 2:
+```sh
+SHELLPROXY_URL="http://127.0.0.1:8123"
+proxy enable
+```
 
-Write a program to `$HOME/.config/proxy` in the file.
+### Method 2
 
-Example program:
+Write a program file in `$HOME/.config/proxy` so that the proxy URL is defined dynamically.
+Note that the program file must be executable.
 
-```bash
+Example:
+
+```sh
 #!/bin/bash
-# The file path: $HOME/.config/proxy
-if [[ "$OSTYPE" == "darwin"* ]]; then
+
+if [[ "$(uname)" = Darwin ]]; then
   echo "http://127.0.0.1:6152" # Surge Mac
 else
   echo "http://127.0.0.1:8123" # polipo
 fi
 ```
 
-Method 3:
+### Method 3
 
-The working path of **Method 2** can be changed via `$CONFIG_PROXY`
+Use [method 2](#method-2) but define the location of the program file by setting the
+`SHELLPROXY_CONFIG` environment variable:
+
+```sh
+SHELLPROXY_CONFIG="$HOME/.dotfiles/proxy-config"
+```
 
 ## Reference
 
@@ -45,8 +59,4 @@ The working path of **Method 2** can be changed via `$CONFIG_PROXY`
 
 ## Maintainer
 
-- <https://github.com/septs>
-
-## The oh-my-zsh plugin (shell-proxy)
-
-Public Domain
+- [@septs](https://github.com/septs)

plugins/shell-proxy/proxy.py

@@ -5,16 +5,22 @@ from subprocess import check_output, list2cmdline
 
 cwd = os.path.dirname(__file__)
 ssh_agent = os.path.join(cwd, "ssh-agent.py")
-user_proxy = os.environ.get("CONFIG_PROXY", os.path.expandvars("$HOME/.config/proxy"))
+proxy_env = "SHELLPROXY_URL"
+proxy_config = os.environ.get("SHELLPROXY_CONFIG") or os.path.expandvars("$HOME/.config/proxy")
 
+usage="""shell-proxy: no proxy configuration found.
+
+Set `{env}` or create a config file at `{config}`
+See the plugin README for more information.""".format(env=proxy_env, config=proxy_config)
 
 def get_http_proxy():
-    default_proxy = os.environ.get("DEFAULT_PROXY")
+    default_proxy = os.environ.get(proxy_env)
     if default_proxy:
         return default_proxy
-    if os.path.isfile(user_proxy):
-        return check_output(user_proxy).decode("utf-8").strip()
-    raise Exception("Not found, Proxy configuration")
+    if os.path.isfile(proxy_config):
+        return check_output(proxy_config).decode("utf-8").strip()
+    print(usage, file=sys.stderr)
+    sys.exit(1)
 
 
 def make_proxies(url: str):
@@ -53,8 +59,7 @@ class CommandSet:
             cmdline("echo", _)
 
     def usage(self):
-        cmdline("echo", "usage: proxy {enable,disable,status}")
-        self.status()
+        print("usage: proxy {enable,disable,status}", file=sys.stderr)
 
 
 def cmdline(*items):
@@ -65,7 +70,7 @@ def main():
     command = CommandSet()
     if len(sys.argv) == 1:
         command.usage()
-        sys.exit(-1)
+        sys.exit(1)
     getattr(command, sys.argv[1], command.usage)()
 
 

plugins/shell-proxy/shell-proxy.plugin.zsh

@@ -1,16 +1,37 @@
 #!/usr/bin/bash
-# shellcheck disable=SC1090
-
-__PROXY__="${0:A:h}/proxy.py"
+# shellcheck disable=SC1090,SC2154
 
 proxy() {
-	source <(env "DEFAULT_PROXY=$DEFAULT_PROXY" "$__PROXY__" "$1")
+  # deprecate $DEFAULT_PROXY, use SHELLPROXY_URL instead
+  if [[ -n "$DEFAULT_PROXY" && -z "$SHELLPROXY_URL" ]]; then
+    echo >&2 "proxy: DEFAULT_PROXY is deprecated, use SHELLPROXY_URL instead"
+    SHELLPROXY_URL="$DEFAULT_PROXY"
+    unset DEFAULT_PROXY
+  fi
+
+  # deprecate CONFIG_PROXY, use SHELLPROXY_CONFIG instead
+  if [[ -n "$CONFIG_PROXY" && -z "$SHELLPROXY_CONFIG" ]]; then
+    echo >&2 "proxy: CONFIG_PROXY is deprecated, use SHELLPROXY_CONFIG instead"
+    SHELLPROXY_CONFIG="$CONFIG_PROXY"
+    unset CONFIG_PROXY
+  fi
+
+  # the proxy.py script is in the same directory as this function
+  local proxy="${functions_source[$0]:A:h}/proxy.py"
+
+  # capture the output of the proxy script and bail out if it fails
+  local output
+  output="$(SHELLPROXY_URL="$SHELLPROXY_URL" SHELLPROXY_CONFIG="$SHELLPROXY_CONFIG" "$proxy" "$1")" ||
+    return $?
+
+  # evaluate the output generated by the proxy script
+  source <(echo "$output")
 }
 
 _proxy() {
-	local -r commands=('enable' 'disable' 'status')
-	compset -P '*,'
-	compadd -S '' "${commands[@]}"
+  local -r commands=('enable' 'disable' 'status')
+  compset -P '*,'
+  compadd -S '' "${commands[@]}"
 }
 
-compdef '_proxy' 'proxy'
+compdef _proxy proxy