project-personas: unified multi-account wrangling across CLI tools (gh, wrangler, …)

[LTSCommerce]

Problem

This repo has a battle-tested multi-account pattern for GitHub:

• github_accounts: {alias: username} map in localhost.yml
• play-github-cli-multi.yml generates per-alias bash functions
  (gh-<alias>, git-<alias>, clone-<alias>, gh-token-<alias>, …)
• Per-account OAuth scope audit + programmatic gh ssh-key add
• Auto-detection in a git() wrapper via git-account-helper

That pattern landed via Plans 00034 and 00035 and is the canonical way
the daily-driver talks to multiple GitHub identities without crossing wires.

We now need the same shape on Cloudflare — multiple accounts, each
needing their own wrangler auth context, with wrangler-<alias>
aliases routing every invocation to the correct account. And the same
pain is coming for npm publish accounts, aws profiles, gcloud configs,
supabase, fly.io, etc.

Proposal

A top-level project_personas map in localhost.yml:

project_personas:
  <alias-a>:
    name: \"<Display Name A>\"
    tools:
      gh:
        username: <gh-username-a>
      wrangler:
        account_id: \"<cloudflare-account-id-a>\"
        account_name: \"<CF Display Name A>\"
  <alias-b>:
    name: \"<Display Name B>\"
    tools:
      gh:
        username: <gh-username-b>
      # no wrangler — this persona has no Cloudflare account

Each per-tool playbook reads that map directly, filters to personas
declaring its tool, and generates the bash function family in the
established `-` shape.

KISS migration: fail-fast, no compat shim

`play-github-cli-multi.yml` is updated to consume
`project_personas` directly. If it sees only the legacy
`github_accounts` map, it fail-fasts with a copy-pasteable
migration YAML — the user makes the one-line edit. No two
sources of truth, no silent derivation, no `set_fact`
gymnastics. The fail-fast message IS the migration guide.

Wrangler: explicit env-var injection + GNOME Keyring secrets

Wrangler is fundamentally unlike gh — it has no per-config-dir
OAuth, so the `-` model uses explicit env-var
export per invocation:

function wrangler-<alias>() {
    local token
    if ! token=\$(secret-tool lookup persona <alias> tool wrangler attr api-token 2>/dev/null); then
        echo \"ERROR: no wrangler API token stored for persona '<alias>'.\" >&2
        echo \"Run: persona-setup.bash --set-token=<alias> wrangler\" >&2
        return 1
    fi
    CLOUDFLARE_API_TOKEN=\"\$token\" \\
    CLOUDFLARE_ACCOUNT_ID=\"<from project_personas>\" \\
        command wrangler \"\$@\"
}

Secret storage: tokens live in the GNOME Keyring via
`secret-tool` — encrypted at rest, unlocked at GNOME login (no
per-call password prompt), per-user isolation enforced by the
keyring daemon, never written to disk in plaintext, never on
the command line where `ps` could see them. Same mechanism
`gh` itself uses on this machine.

Alternatives considered and rejected: plaintext 0600 files
(backups grab plaintext), `pass`/GPG (extra dep), ansible-vault
(awkward at bash-function call time, `vault-pass.secret` on
disk anyway).

Decision gate

Phase 1 is a research gate. The remaining unknowns:

1. Wrangler API token scopes — confirm minimum scopes for
   Workers / Pages / KV / R2 / D1.
2. `secret-tool` availability — confirm libsecret is
   reliably present and the keyring is unlocked at function
   call time. Fallback to 0600 files if not.

Implementation phases are blocked on user approval after Phase 1.

Plan

Full plan with phases, tasks, technical decisions (incl.
Decision 4 on secret storage), and success criteria lives at
`CLAUDE/Plan/00045-project-personas-multi-tool-accounts/PLAN.md`
(committed once user approves).

Out of scope

• npm / aws / gcloud / supabase / fly support (follow-up plans
  each using this plan's persona schema + keyring pattern)
• Renaming SSH keys (`~/.ssh/github_` stays)
• GUI/wizard (CLI-only, consistent with `run.bash`)
• Touching `play-cloudflare-warp.yml` (that's the VPN client,
  unrelated to wrangler)

[LTSCommerce]

Refinements (2026-05-29): schema rules, use_for_orgs, smart git/gh, expanded platform scope

Four rounds of refinement folded into one comment, all landing in a single fail-fast migration message for the user.

1. Schema rules (rewrites the YAML shape in the parent proposal)

Three sub-rules, all settled together:

1a. No tools: wrapper — flat platform keys at persona top level.

The tools: level is YAGNI nesting. Platform names (github, cloudflare, amazon_web_services, …) don't collide with metadata fields (name, future email, future default). The playbook enumerates platforms by treating any persona-level key not in a small known-metadata list as a platform. One fewer level of indirection in every YAML edit, every Jinja expression, every diff hunk.

1b. Platform keys use the platform, not the CLI binary.

gh and git and clone-<alias> all authenticate as the same GitHub identity — that identity is one thing. Keying by CLI binary fractures it. Keying by platform makes the abstraction match reality.

1c. Use the FULL platform name. No abbreviations.

Per the rule (2026-05-29): "a few tokens = much greater clarity for humans + LLMs". aws reads as "AWS the company / the CLI / a region / an account" depending on context; amazon_web_services is unambiguous one-glance.

✅ Use	❌ Don't use	Covers (CLIs sharing this identity)
github	gh, git	gh, git, SSH key, clone-<alias>, gh-token-<alias>
cloudflare	wrangler, cf	wrangler, future cloudflared, future flarectl
amazon_web_services	aws, aws-cli	aws, cdk, sam
google_cloud_platform	gcp, gcloud	gcloud, gsutil, bq
microsoft_azure	azure, az	az, azd
npm_registry	npm	npm, pnpm, yarn (publish auth)
docker_hub	docker	docker login, podman login against hub
fly_io	fly	flyctl

When in doubt: write the platform's full marketing/legal name as snake_case. github and cloudflare are already the full brand names — no expansion needed.

2. use_for_orgs per-persona for declared GitHub org ownership

project_personas:
  <alias-a>:
    name: "<Display Name A>"
    github:
      username: <gh-username-a>
      use_for_orgs:
        - <org-x>
        - <org-y>
    cloudflare:
      account_id: "<cf-account-id-a>"
      account_name: "<CF Display Name A>"
  <alias-b>:
    name: "<Display Name B>"
    github:
      username: <gh-username-b>
      use_for_orgs:
        - <org-z>
    # no `cloudflare` key — this persona has no Cloudflare account

github.use_for_orgs (optional list of org names) declares which GitHub orgs the persona owns. Drives the smart-router in section 3. Absent or empty → persona is reachable only via explicit git-<alias> / gh-<alias> or by personal-repo namespace match (<gh-username>/* is implicit).

3. Smart top-level git and gh — the payoff

Once use_for_orgs exists, the per-alias wrappers (git-<alias>, gh-<alias>, clone-<alias>) become escape hatches, not the primary interface. The default git and gh you type a thousand times a day become smart shell functions that auto-route:

function git() {
    local org alias
    org=$(_persona_extract_org_from_cwd_remote)   # parse $(command git remote get-url origin)
    if [ -n "$org" ]; then
        alias=$(_persona_lookup_alias_for_org github "$org")
        if [ -n "$alias" ]; then
            command git-"$alias" "$@"
            return
        fi
    fi
    command git "$@"   # no match → default behaviour, no surprises
}

function gh() {
    # same shape: detect org from cwd remote OR from `gh` argv positional
    # (e.g. `gh repo view <org>/<repo>`) → delegate to gh-<alias>
}

Effects:

• cd ~/Projects/<org-x>/repo && git pull → silently uses git-<alias-a>. Zero mental overhead.
• gh issue list --repo <org-z>/anything → silently uses gh-<alias-b>.
• Repo in an unclaimed org → falls through to the currently-active gh account.
• Explicit git-<alias> / gh-<alias> still available to force a persona.

Smart routing is GitHub-only. Other platforms (cloudflare, fly_io, supabase, aws, gcp) have no equivalent of "remote URL → persona". The custom-file approach (a .persona marker file per directory) was considered and rejected — "no random files". For non-GitHub platforms, the user explicitly invokes the per-alias wrapper when working with that persona.

Future option for non-GitHub per-cwd routing: direnv. Already a widely-used upstream project, no invention needed. Users would write .envrc files in project directories that pull from the keyring:

# example .envrc in a Cloudflare Worker project directory
export CLOUDFLARE_API_TOKEN=$(secret-tool lookup persona <alias> platform cloudflare attr api_token)
export CLOUDFLARE_ACCOUNT_ID=<account-id>

Not implemented in this plan — shelved as a future option if the need arises. The project_personas schema is already compatible with this pattern.

4. Expanded platform scope — six platforms in one go

Original plan: github + cloudflare, with everything else deferred to follow-up plans. New scope (per "if we're going to do this, lets wire in tools for common platforms like this, i guess we may as well do them all in one go"): six platforms in this plan.

Platform	Pattern	Status in this plan
github	OAuth + SSH (native multi-account)	✅ in scope (was already)
cloudflare	API token, env-var-per-call	✅ in scope (was already)
fly_io	API token, env-var-per-call	✅ in scope (NEW)
supabase	Access token, env-var-per-call	✅ in scope (NEW)
amazon_web_services	Named profile + AWS_PROFILE	✅ in scope (NEW)
google_cloud_platform	Named config + env var	✅ in scope (NEW)
npm_registry	.npmrc per-scope + token	⬜ deferred (follow-up)
microsoft_azure	Multiple auth modes (device/SP/MI)	⬜ deferred (follow-up)
docker_hub	Single-active ~/.docker/config.json	⬜ deferred (follow-up)

The token-env-var-per-call platforms (cloudflare, fly_io, supabase) all reuse the existing Phase 4 template architecture as-is. The named-profile platforms (AWS, GCP) introduce a thinner variant — no keyring, env var sets the active profile, credentials live in the CLI's native config file.

Why defer the bottom three:

• npm_registry: .npmrc per-scope handling doesn't fit the env-var-per-call template cleanly.
• microsoft_azure: env-var combos differ per auth mode; non-trivial playbook; only worth doing if actively used.
• docker_hub: single-active config is fiddly (rewrite-on-call has races; per-alias config dir breaks docker compose UX). Worth its own design plan.

Wrappers reframed (post-smart-router)

Wrapper	Role
git (smart)	Default. Auto-routes to git-<alias> when cwd remote-org is claimed.
gh (smart)	Default. Auto-routes to gh-<alias> based on cwd remote or gh arg parsing.
git-<alias> / gh-<alias>	Explicit override. Use when forcing a persona that doesn't own the org.
wrangler-<alias>	Explicit per-call wrapper (cloudflare) — no smart routing.
flyctl-<alias>	Explicit per-call wrapper (fly_io).
supabase-<alias>	Explicit per-call wrapper (supabase).
aws-<alias>	Explicit per-call wrapper (amazon_web_services) — sets AWS_PROFILE.
gcloud-<alias>	Explicit per-call wrapper (google_cloud_platform) — sets CLOUDSDK_ACTIVE_CONFIG_NAME.
clone-<alias>	Initial clone (no cwd remote yet); warn if cloning from an unclaimed org.
persona-here	Diagnostic: prints which persona would be used for the cwd. Debugs "wrong user pushed".

Edge cases the playbook must handle

• Personal repos (<gh-username>/*): github.username already declares ownership of that namespace, no use_for_orgs entry needed.
• Org-list collisions: two personas claiming the same org → fail-fast at playbook deployment time (preferred — catches before misroute) AND at function-call time (defence in depth).
• No git remote in cwd: smart git passes through unchanged (e.g. git init, git config --global).
• gh calls without a repo argument: e.g. gh auth status, gh api user. Fall through to command gh.
• Auto-discovery rejected: don't derive use_for_orgs from gh api user/orgs. Membership ≠ "this is the right persona for that org" — explicit opt-in is the whole point.

Migration

All four refinements (de-nest, full-name rename, use_for_orgs, expanded platform set) land in the same fail-fast playbook message. The user makes a single YAML edit per persona, copy-pasteable from the playbook's error output. Existing github_accounts migration path is unaffected — the same message replaces it with the new shape.

Full plan with phase-by-phase task list at CLAUDE/Plan/00045-project-personas-multi-tool-accounts/PLAN.md.