BREAKING: replace XSH_GIT_HUB_ACCOUNT_MAP with XSH_GIT_HUB_ACCOUNTS; add hub/ssh

The env var schema changes from a flat email=account map to a list of
account profile records, each describing one gh account:

    <account> : <email> : <org>[,<org>...]

This unifies what were two conceptually-coupled mappings (email->account
for identity, org->account for SSH routing) into one record-per-account
table that's plug-and-play per org file. There is no compatibility shim:
0.3.0 reads XSH_GIT_HUB_ACCOUNTS, not the previous variable. Update the
shell rc files seeding the var when bumping to this release.

New utilities:

  hub/account-for-org   New sibling of account-for-email; returns the
                        account that defaults for a given GitHub org.
                        First-match-wins for orgs claimed by more than
                        one record.

  hub/ssh               New script (under scripts/, symlinked into
                        /usr/local/bin/git-hub-ssh on xsh imports).
                        Designed for core.sshCommand: parses the org
                        from git's git-{upload,receive}-pack arg,
                        looks it up in XSH_GIT_HUB_ACCOUNTS, exec's
                        ssh with -i ~/.ssh/github-<account> and
                        IdentitiesOnly=yes. Falls through to plain ssh
                        for non-github hosts and unmapped orgs.

The router lets bare git@github.com:<org>/<repo>.git URLs work directly
without needing url.<base>.insteadOf rewrites in gitconfig — cloned
remote stays as the natural bare URL.

Tests cover the new record format, the new utilities, and the
fake-ssh-on-PATH harness for git/hub/ssh.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: alexzhangs

README.md

@@ -35,7 +35,7 @@ This project is still at version `0.x` and should be considered immature.
    xsh load xsh-lib/core
    ```
 
-2. Some utilities have additional dependencies (e.g. `gh`, `w3m`,
+2. Some utilities have additional dependencies (e.g. `gh`, `ssh`, `w3m`,
    `collaborator`). See the per-utility help for details.
 
 
@@ -75,43 +75,87 @@ xsh help git/<package>/<util>
 
 | Utility                       | Kind     | Purpose                                                                                                          |
 |-------------------------------|----------|------------------------------------------------------------------------------------------------------------------|
-| `git/hub/account-for-email`   | function | Look up a `gh` account name for an email via `XSH_GIT_HUB_ACCOUNT_MAP`.                                          |
-| `git/hub/account-for-repo`    | function | Derive the `gh` account for the current repo from `git config user.email`, using the same mapping.               |
+| `git/hub/account-for-email`   | function | Walk `XSH_GIT_HUB_ACCOUNTS`, return the account whose email matches.                                             |
+| `git/hub/account-for-org`     | function | Walk `XSH_GIT_HUB_ACCOUNTS`, return the account that defaults for the given GitHub org. First-match-wins.        |
+| `git/hub/account-for-repo`    | function | Derive the account from `git config user.email` in the current repo (delegates to `account-for-email`).          |
 | `git/hub/run`                 | function | Run a command with a chosen `gh` account active, isolated from concurrent shell sessions via per-call `GH_CONFIG_DIR`. |
+| `git/hub/ssh`                 | script   | SSH wrapper for `core.sshCommand`: picks the right per-account key from the repo owner in git's command line.    |
 | `git/hub/collaborator`        | function | Add, remove, or list collaborators of the current GitHub repo. Requires `collaborator` and `w3m`.                |
 | `git/rebase-i-in-dumb-term`   | script   | Helper for running `git rebase -i` in dumb terminals.                                                             |
 
 
+### The account profile env var: `XSH_GIT_HUB_ACCOUNTS`
+
+The `git/hub/*` utilities read a single env var that describes every gh
+account you operate. Whitespace-separated records, each with three
+colon-separated fields:
+
+```
+<account> : <email> : <org>[,<org>...]
+```
+
+| Field | Cardinality | Meaning |
+|---|---|---|
+| `account` | required | gh account name; also the suffix in `~/.ssh/github-<account>`. |
+| `email`   | 0..1     | Email tied to this account by `~/.gitconfig` `includeIf` rules. Empty for bot-style accounts with no per-directory binding. |
+| `orgs`    | 0..N     | Comma-separated GitHub orgs this account defaults for. Read by `account-for-org` and `git/hub/ssh`. |
+
+Example:
+
+```bash
+export XSH_GIT_HUB_ACCOUNTS="alice:alice@example.com:alice,xsh-alice bob:bob@corp.io:bob-corp"
+```
+
+If two records list the same org, **first match wins** — the earlier
+record's account becomes the default for that org. The other account is
+still reachable via the explicit SSH alias URL
+`git@github-<account>:<org>/<repo>.git`.
+
+
 ### Multi-`gh`-account workflow
 
 If you operate multiple GitHub accounts simultaneously (e.g. personal +
 work) and rely on `~/.gitconfig`'s `includeIf "gitdir:..."` rules to switch
-identities per directory tree, the `git/hub/*` utilities make it transparent
-to push/PR/etc. against the right account without ever mutating the global
+identities per directory tree, this library makes it transparent to push,
+PR, and clone against the right account without ever mutating the global
 active account in `~/.config/gh`.
 
-1. Map your emails to `gh` account names via an env var:
-
-   ```bash
-   export XSH_GIT_HUB_ACCOUNT_MAP="alice@personal.com=alice alice@corp.io=alice-corp"
-   ```
+1. Map your accounts via the env var described above.
 
-2. Use `git/hub/run` as a transparent wrapper around any `git` or `gh`
-   command. The account is auto-derived from the current repo's
-   `user.email`:
+2. Use `git/hub/run` as a transparent wrapper around any `gh` command
+   (account auto-derived from the current repo's `user.email`):
 
    ```bash
-   xsh git/hub/run -- git push origin main
    xsh git/hub/run -- gh pr create --fill
    xsh git/hub/run -u alice-corp -- gh pr list   # explicit override
    ```
 
    Each call snapshots `~/.config/gh` to a private mode-700 tempdir,
-   `gh auth switch -u <account>` runs against the **copy**, and
-   `GH_CONFIG_DIR` is exported only for the wrapped command. The real
-   config is never mutated, so other shell sessions and credential-helper
-   invocations are unaffected — even when several `git/hub/run` calls are
-   in flight at the same time.
+   runs `gh auth switch -u <account>` against the **copy**, and exports
+   `GH_CONFIG_DIR` only for the wrapped command. The real config is never
+   mutated, so other shell sessions and credential-helper invocations are
+   unaffected — even when several `git/hub/run` calls are in flight at the
+   same time.
+
+3. Wire `git/hub/ssh` into git for transparent SSH routing on bare
+   `git@github.com:<org>/<repo>.git` URLs:
+
+   ```bash
+   xsh imports git/hub/ssh
+   git config --global core.sshCommand git-hub-ssh
+   ```
+
+   Now `git clone git@github.com:<org>/<repo>.git` (or `gh repo clone`,
+   or the web "Clone with SSH" copy-paste) auto-resolves to the right
+   `~/.ssh/github-<account>` key — without rewriting the URL stored in
+   the cloned `origin`. SSH key selection happens in the wrapper based on
+   the org parsed from git's `git-{upload,receive}-pack` command line.
+
+   The wrapper falls through to plain `ssh` for any host that isn't
+   `git@github.com` (CodeCommit, EC2, the per-account `github-<name>`
+   aliases, etc.) and for any org that isn't in
+   `XSH_GIT_HUB_ACCOUNTS` — letting your existing SSH config handle
+   those cases unchanged.
 
 
 ## Development

functions/hub/account-for-email.sh

@@ -1,13 +1,25 @@
 #? Description:
-#?   Print the gh account name mapped to the given email.
+#?   Print the gh account name associated with the given email.
 #?
-#?   The mapping is read from the environment variable
-#?   `XSH_GIT_HUB_ACCOUNT_MAP`, a whitespace-separated list of
-#?   "<email>=<account>" pairs. Example:
+#?   The data is read from the environment variable `XSH_GIT_HUB_ACCOUNTS`,
+#?   a whitespace-separated list of records, each in the format:
 #?
-#?     export XSH_GIT_HUB_ACCOUNT_MAP="alice@example.com=alice bob@corp.io=bob-corp"
+#?     <account>:<email>:<org>[,<org>...]
 #?
-#?   This util is the lookup primitive; it does not touch the repo or gh.
+#?   - <account>  gh account name; required.
+#?   - <email>    email tied to this account via ~/.gitconfig includeIf
+#?                rules. May be empty for bot-style accounts with no
+#?                per-directory email binding.
+#?   - <org>      GitHub org for which this account is the default. Zero
+#?                or more, comma-separated. Used by `account-for-org` and
+#?                `git/hub/ssh`; ignored here.
+#?
+#?   Example:
+#?
+#?     export XSH_GIT_HUB_ACCOUNTS="alice:alice@example.com:alice,xsh-alice bob:bob@corp.io:bob-corp"
+#?
+#?   This util is the email-lookup primitive; it does not touch the repo
+#?   or gh. Records whose email field is empty are skipped.
 #?
 #? Usage:
 #?   @account-for-email <EMAIL>
@@ -25,12 +37,11 @@
 #?
 function account-for-email () {
     declare email=${1:?missing EMAIL}
-    declare pair k v
-    for pair in $XSH_GIT_HUB_ACCOUNT_MAP; do
-        k=${pair%%=*}
-        v=${pair#*=}
-        if [[ $k == "$email" ]]; then
-            printf '%s\n' "$v"
+    declare record r_account r_email
+    for record in $XSH_GIT_HUB_ACCOUNTS; do
+        IFS=':' read -r r_account r_email _ <<< "$record"
+        if [[ -n $r_email && $r_email == "$email" ]]; then
+            printf '%s\n' "$r_account"
             return 0
         fi
     done

functions/hub/account-for-org.sh

@@ -0,0 +1,47 @@
+#? Description:
+#?   Print the gh account name that defaults for the given GitHub org.
+#?
+#?   The data is read from the environment variable `XSH_GIT_HUB_ACCOUNTS`,
+#?   a whitespace-separated list of records, each in the format:
+#?
+#?     <account>:<email>:<org>[,<org>...]
+#?
+#?   For details on the record format, see `xsh help git/hub/account-for-email`.
+#?
+#?   First match wins: if two records both list <ORG> in their orgs field,
+#?   the one earlier in XSH_GIT_HUB_ACCOUNTS is returned. The other account
+#?   stays reachable via the explicit SSH alias URL
+#?   `git@github-<account>:<ORG>/<repo>.git`.
+#?
+#?   This util is the org-lookup primitive; it does not touch the repo or
+#?   gh. Records whose orgs field is empty are skipped.
+#?
+#? Usage:
+#?   @account-for-org <ORG>
+#?
+#? Options:
+#?   <ORG>   The GitHub org name (e.g. `HyperSolidAPP`).
+#?
+#? Return:
+#?   0 on hit, with the account name printed to stdout.
+#?   1 on miss, with no output.
+#?
+#? Example:
+#?   @account-for-org HyperSolidAPP
+#?
+function account-for-org () {
+    declare org=${1:?missing ORG}
+    declare record r_account r_orgs_csv o
+    for record in $XSH_GIT_HUB_ACCOUNTS; do
+        IFS=':' read -r r_account _ r_orgs_csv <<< "$record"
+        [[ -z $r_orgs_csv ]] && continue
+        IFS=',' read -ra r_orgs <<< "$r_orgs_csv"
+        for o in "${r_orgs[@]}"; do
+            if [[ $o == "$org" ]]; then
+                printf '%s\n' "$r_account"
+                return 0
+            fi
+        done
+    done
+    return 1
+}

functions/hub/account-for-repo.sh

@@ -8,8 +8,8 @@
 #?
 #? Dependency:
 #?   1. xsh git/hub/account-for-email
-#?   2. The env var XSH_GIT_HUB_ACCOUNT_MAP must contain a mapping for the
-#?      repo's email. See `xsh help /git/hub/account-for-email`.
+#?   2. The env var XSH_GIT_HUB_ACCOUNTS must contain a record for the
+#?      repo's email. See `xsh help git/hub/account-for-email`.
 #?
 #? Usage:
 #?   @account-for-repo
@@ -31,7 +31,7 @@ function account-for-repo () {
     fi
     if ! account=$(xsh git/hub/account-for-email "$email"); then
         printf 'account-for-repo: no gh account mapped for %s\n' "$email" >&2
-        printf '  add "<email>=<account>" to XSH_GIT_HUB_ACCOUNT_MAP\n' >&2
+        printf '  add a record with this email to XSH_GIT_HUB_ACCOUNTS\n' >&2
         return 1
     fi
     printf '%s\n' "$account"

scripts/hub/ssh.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+#? Description:
+#?   SSH wrapper that picks the right per-account key from the repo owner
+#?   in the git command line. Invoked by git via core.sshCommand.
+#?
+#?   For each invocation, the script inspects argv to determine:
+#?     1. Is this an SSH to git@github.com? If not, fall through to plain
+#?        ssh unchanged. This preserves connections to other hosts
+#?        (CodeCommit, EC2, the per-account github-<name> aliases, etc.)
+#?     2. Does the git-{upload,receive}-pack command name an org we have
+#?        a default account for in $XSH_GIT_HUB_ACCOUNTS? If not, fall
+#?        through unchanged — the bare github.com URL will then hit the
+#?        loud-fail Host github.com block in ~/.ssh/config, surfacing the
+#?        missing routing entry as Permission denied instead of as a
+#?        silent wrong-account auth.
+#?     3. If yes, exec ssh with `-i ~/.ssh/github-<account>` and
+#?        IdentitiesOnly=yes prepended to the original args.
+#?
+#?   First-match-wins for the org lookup — see
+#?   `xsh help git/hub/account-for-org`.
+#?
+#?   This script is dependency-free at runtime: it does not require xsh to
+#?   be loaded in the shell that invokes git. Configure it once via
+#?   gitconfig and it works in every git context (terminal, IDE, cron):
+#?
+#?     git config --global core.sshCommand git-hub-ssh
+#?
+#?   (After `xsh imports git/hub/ssh`, the script is symlinked into
+#?   /usr/local/bin/git-hub-ssh, so the bare name works on PATH.)
+#?
+#? Dependency:
+#?   1. ssh
+#?   2. Env var XSH_GIT_HUB_ACCOUNTS — see `xsh help git/hub/account-for-email`.
+#?
+#? Usage:
+#?   git-hub-ssh [SSH_ARGS...]
+#?
+#?   Not normally invoked by hand. Set as `core.sshCommand` in gitconfig.
+#?
+#? Example:
+#?   git config --global core.sshCommand git-hub-ssh
+#?   git clone git@github.com:HyperSolidAPP/foo.git
+#?   # → router resolves HyperSolidAPP -> alex-hypersolid -> uses
+#?   #   ~/.ssh/github-alex-hypersolid. Cloned origin stays bare.
+#?
+
+set -e
+
+# Pass-through for everything not aimed at git@github.com.
+is_github=false
+for a in "$@"; do
+    if [[ $a == git@github.com ]]; then
+        is_github=true
+        break
+    fi
+done
+$is_github || exec ssh "$@"
+
+# git invokes us with e.g.  git-upload-pack 'HyperSolidAPP/foo.git'
+# Extract the org from the first single-quoted path.
+org=""
+for a in "$@"; do
+    case "$a" in
+        "git-upload-pack '"*"/"*"'"|"git-receive-pack '"*"/"*"'")
+            # strip the wrapping  git-*-pack '<path>'
+            tmp=${a#*\'}
+            tmp=${tmp%\'}
+            org=${tmp%%/*}
+            break
+            ;;
+    esac
+done
+[[ -z $org ]] && exec ssh "$@"
+
+# Look up org -> account in XSH_GIT_HUB_ACCOUNTS (account:email:orgs).
+# First match wins.
+account=""
+for record in $XSH_GIT_HUB_ACCOUNTS; do
+    IFS=':' read -r r_account _ r_orgs_csv <<< "$record"
+    [[ -z $r_orgs_csv ]] && continue
+    IFS=',' read -ra r_orgs <<< "$r_orgs_csv"
+    for o in "${r_orgs[@]}"; do
+        if [[ $o == "$org" ]]; then
+            account=$r_account
+            break 2
+        fi
+    done
+done
+[[ -z $account ]] && exec ssh "$@"
+
+exec ssh -i "$HOME/.ssh/github-$account" -o IdentitiesOnly=yes "$@"