tweak documentation, usage, and friendly responses

README.md

@@ -1,6 +1,6 @@
 # `gh-role`
 
-This simple extension allows you to check the current user's role on a repo.  It's especially useful for scripts in shared repositories.
+This simple extension allows you to check the current user's role on a repo or org.  It's especially useful for scripts in shared repositories.
 
 For example, if you have a script that adds a protected tag to a commit then pushes it to the repo, you can use this command to ensure that the user has the necessary permissions to do so.
 
@@ -10,8 +10,6 @@ __Notes:__
 
 - This extension is not meant to be used as a security measure.  It is meant to be used as a convenience for scripts that need to check the user's role.
 
-- This extension does __not__ currently check the user's role in an __organization__.  It __only__ checks the user's role in a __repository__.
-
 ## Installation
 
 ```bash
@@ -26,15 +24,23 @@ Without listing role names, `gh role` simply returns the current user's role. Th
 
     ```bash
     gh role
-    // ADMIN
+    // admin
+    // Exits with code 0
+
+    gh role -r nedredmond/gh-role -f
+    // User has admin role on nedredmond/gh-role.
+    // Exits with code 0
+
+    gh role -r nedredmond/gh-role -f maintain friend lover
+    // 2022/11/20 01:01:00 user does not have roles in nedredmond/gh-role: maintain, friend, lover; found admin
     // Exits with code 0
     ```
 
 - For a repo that the user has nothing to do with:
 
     ```bash
     gh role -r canada-ca/ore-ero
-    // READ
+    // read
     // Exits with code 0
     ```
 
@@ -44,16 +50,38 @@ If roles are listed (after all flags), the command will exit with exit code 1 if
 
     ```bash
     gh role -r canada-ca/ore-ero write admin
-    // 2022/11/20 01:01:00 User does not have permissions on canada-ca/ore-ero: write, admin; found READ
+    // 2022/11/20 01:01:00 user does not have roles in canada-ca/ore-ero: write, admin; found read
     // Exits with error code 1
     ```
 
+For organizations, the command will exit with exit code 1 if the user is not a member of the organization.
+
+- To check for membership:
+
+    ```bash
+    gh role -o canada-ca
+    // 2022/11/20 01:01:00 user has no role in canada-ca
+    // Exits with error code 1
+    ```
+
+- To check for specific roles:
+
+    ```bash
+    gh role -o my-org admin
+    // 2022/11/20 01:01:00 user does not have role in my-org: admin; found member
+    // Exits with error code 1
+
+    gh role -o my-org admin member
+    // member
+    // Exits with code 0
+    ```
+
 - Available roles in order of increading permissions are: `READ`, `TRIAGE`, `WRITE`, `MAINTAIN`, `ADMIN`. For more information, see [GitHub's documentation on repository roles](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization).
 
 ### Flags
 
-- `-h` Prints available flags and usage to the CLI.
-- `-r` The repo to check permissions on.  Defaults to the current repo.
-- `-f` Prints a friendly message instead of the permission constant.
-  - i.e., `Current user has ADMIN permission on gh-role.`
-- After any flags, list the permissions you want to check, separated by spaces. If none are provided, the command will print your current permission instead.
+- __`-h`__ Prints available flags and usage to the CLI.
+- __`-r`__ The repo to check roles on.  Defaults to the current repo.
+- __`-f`__ Prints a friendly message instead of the machine-readable role.
+  - i.e., `User has admin role in nedredmond/gh-role.`
+- After any flags, list the roles you want to verify, separated by spaces. If none are provided, the command will print your current role instead.

main.go

@@ -8,8 +8,8 @@ import (
 func main() {
 	// Flags for the command
 	repo := flag.String("r", "", "The repo for which to check roles. If blank, the current repo is used.")
-	org := flag.String("o", "", "The org for which to check roles. If blank, defaults to repo check. If present, `-r` flag will be ignored.")
-	friendly := flag.Bool("f", false, "Prints a friendly message. Otherwise, prints a machine-readable string.")
+	org := flag.String("o", "", "The org for which to check roles. If blank, defaults to repo check. If present, repo flag will be ignored.")
+	friendly := flag.Bool("f", false, "Prints a friendly message. Otherwise, prints a machine-readable role name.")
 	// Overrides default help message to inform about args
 	defaultUsage := flag.Usage
 	flag.Usage = func() {

utils.go

@@ -27,7 +27,7 @@ func evaluate(entity string, userRole string, roles []string, friendly bool) {
 func succeed(entity string, userRole string, friendly bool) {
 	roleString := strings.ToLower(userRole)
 	if friendly {
-		fmt.Printf("Current user has %s role in %s.\n", roleString, entity)
+		fmt.Printf("User has %s role in %s.\n", roleString, entity)
 	} else {
 		fmt.Println(roleString)
 	}