diff --git a/AI.dev/SKILLS/README.md b/AI.dev/SKILLS/README.md index 404af3df..d7fd2dc3 100644 --- a/AI.dev/SKILLS/README.md +++ b/AI.dev/SKILLS/README.md @@ -66,21 +66,22 @@ Each skill follows a consistent format: ## Quick Reference -| Need | Skill | Location | -| -------------------------- | ---------------------------------------------------- | -------------------------------- | -| Fix a failing service | [Debug Service](./debug-service.md) | ๐Ÿ”ง Development Workflows | -| Prepare for release | [Production Readiness](./production-readiness.md) | ๐Ÿงช Testing & Quality | -| Start all services locally | [Local Development Setup](./local-development.md) | ๐Ÿ”ง Development Workflows | -| Backup main branch | [Backup Main Branch](./backup-main-branch.md) | ๐Ÿ”ง Development Workflows | -| Release desktop app | [Desktop Release](./desktop-release.md) | ๐Ÿš€ Release & Deployment | -| Release iOS app | [iOS Release](./ios-release.md) | ๐Ÿš€ Release & Deployment | -| Generate store assets | [Generate Store Assets](./generate-store-assets.md) | ๐Ÿš€ Release & Deployment | -| Ensure mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | ๐Ÿ“ฑ Mobile Development | -| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | ๐Ÿ“š Documentation & Communication | -| Write tests | [Test Strategies](./test-strategies.md) | ๐Ÿงช Testing & Quality | -| Docker full stack | [Docker Compose](./docker-compose.md) | ๐Ÿ”ง Development Workflows | -| Security audit | [Security Auditing](./security-auditing.md) | ๐Ÿงช Testing & Quality | -| Architecture patterns | [Architecture Patterns](./architecture-patterns.md) | ๐Ÿ—๏ธ Architecture & Setup | +| Need | Skill | Location | +| ------------------------------- | ----------------------------------------------------- | -------------------------------- | +| Fix a failing service | [Debug Service](./debug-service.md) | ๐Ÿ”ง Development Workflows | +| Prepare for release | [Production Readiness](./production-readiness.md) | ๐Ÿงช Testing & Quality | +| Start all services locally | [Local Development Setup](./local-development.md) | ๐Ÿ”ง Development Workflows | +| Backup main branch | [Backup Main Branch](./backup-main-branch.md) | ๐Ÿ”ง Development Workflows | +| Release desktop app | [Desktop Release](./desktop-release.md) | ๐Ÿš€ Release & Deployment | +| Release iOS app | [iOS Release](./ios-release.md) | ๐Ÿš€ Release & Deployment | +| Generate store assets | [Generate Store Assets](./generate-store-assets.md) | ๐Ÿš€ Release & Deployment | +| Ensure mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | ๐Ÿ“ฑ Mobile Development | +| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | ๐Ÿ“š Documentation & Communication | +| Write tests | [Test Strategies](./test-strategies.md) | ๐Ÿงช Testing & Quality | +| Docker full stack | [Docker Compose](./docker-compose.md) | ๐Ÿ”ง Development Workflows | +| Security audit | [Security Auditing](./security-auditing.md) | ๐Ÿงช Testing & Quality | +| Architecture patterns | [Architecture Patterns](./architecture-patterns.md) | ๐Ÿ—๏ธ Architecture & Setup | +| Route `gh` CLI to right account | [GH Account Routing](./gh-account-routing.md) | ๐Ÿ”ง Development Workflows | ## Available Skills @@ -89,6 +90,7 @@ Each skill follows a consistent format: - [Debug Service](./debug-service.md) - Debug any service systematically - [Production Readiness](./production-readiness.md) - Complete pre-release validation - [Local Development Setup](./local-development.md) - Run all services locally +- [GH Account Routing](./gh-account-routing.md) - Auto-route `gh` CLI between personal and work GitHub accounts - [Docker Compose](./docker-compose.md) - Containerized full stack - [Backup Main Branch](./backup-main-branch.md) - Smart backup with duplicate detection - [Mobile Code Quality](./mobile-code-quality.md) - Cross-platform mobile standards diff --git a/AI.dev/SKILLS/gh-account-routing.md b/AI.dev/SKILLS/gh-account-routing.md new file mode 100644 index 00000000..b7604158 --- /dev/null +++ b/AI.dev/SKILLS/gh-account-routing.md @@ -0,0 +1,172 @@ +# GH CLI Account Routing โ€” Personal vs Work + +> **Purpose:** Document the local zsh setup that auto-routes the `gh` CLI (and any subprocess that calls `gh`) to the correct GitHub account based on the current working directory. + +## Tags + +`#beginner` `#setup` `#dotfiles` `#local-only` + +## Why this exists + +ByteLyst contributors often have **two GitHub accounts** authenticated via `gh auth login`: + +- A **work account** (e.g., corporate, used as default in `gh`'s keyring) +- A **personal account** (e.g., `saravanakumardb1`) that owns the ByteLyst repos under `~/code/mygh/` + +Without explicit routing, every `gh` call uses the keyring's "active account" โ€” which leads to confusing 404s when you operate on a personal repo (`gh api /repos/saravanakumardb1/foo` fails because the active account doesn't have access). + +The pattern below makes routing **automatic and invisible**: if you're inside `~/code/mygh/`, `gh` uses the personal account; outside, it uses the default. + +## When to use + +- New laptop / fresh shell setup, after running `gh auth login` for both accounts. +- Any time you find yourself running `gh auth switch -u ` repeatedly. +- When repo-local scripts (husky hooks, `scripts/*.sh`, `.windsurf/workflows/*`) need to call `gh` and you want them to "just work" regardless of which terminal launched them. + +## How it works + +`gh` checks the `GH_TOKEN` env var **before** consulting the keyring. So we use a `chpwd` zsh hook to export `GH_TOKEN` to the personal token whenever cwd is under `~/code/mygh/`, and unset it otherwise. Subprocesses inherit the env var, so any script that shells out to `gh` from inside a workspace repo gets the right account automatically. + +## Setup steps + +### 1. Authenticate both accounts with `gh` + +```bash +gh auth login # work account first +gh auth login # then personal โ€” gh keeps both in keyring +gh auth status # verify both are listed +``` + +### 2. Add a credential helper for git HTTPS pushes (one-time) + +This makes plain `git push` use the personal token when inside `~/code/mygh/`, regardless of which `gh` account is "active". It's independent of the zsh hook below. + +`~/.gitconfig-personal`: + +```ini +[user] + name = saravanakumardb1 + email = saravanakumardb1@users.noreply.github.com + +[credential "https://github.com"] + helper = + helper = !/Users/$USER/.git-credential-personal.sh +``` + +`~/.gitconfig` (append, replacing `$USER` with your username): + +```ini +[includeIf "gitdir:/Users/$USER/code/mygh/.path"] + path = ~/.gitconfig-personal +``` + +`~/.git-credential-personal.sh` (chmod +x): + +```bash +#!/bin/bash +# Always returns the personal-account GitHub token regardless of `gh` active account. +if [ "$1" = "get" ]; then + TOKEN=$(/opt/homebrew/bin/gh auth token --user saravanakumardb1 2>/dev/null) + if [ -n "$TOKEN" ]; then + echo "protocol=https" + echo "host=github.com" + echo "username=saravanakumardb1" + echo "password=$TOKEN" + fi +fi +``` + +### 3. Add the zsh chpwd hook for the `gh` CLI + +Append to `~/.zshrc`: + +```zsh +# === BEGIN: bytelyst-personal-gh-token (auto-managed) === +# Auto-route `gh` CLI + scripts to the personal account whenever cwd is +# inside ~/code/mygh/. Outside that tree, GH_TOKEN is unset so `gh` falls +# back to the keyring active account. +_bytelyst_gh_token="" +_set_personal_gh_token() { + case "$PWD" in + "$HOME/code/mygh"/*|"$HOME/code/mygh") + if [ -z "$_bytelyst_gh_token" ]; then + _bytelyst_gh_token="$(/opt/homebrew/bin/gh auth token --user saravanakumardb1 2>/dev/null)" + fi + [ -n "$_bytelyst_gh_token" ] && export GH_TOKEN="$_bytelyst_gh_token" + ;; + *) + unset GH_TOKEN + ;; + esac +} +autoload -U add-zsh-hook +add-zsh-hook chpwd _set_personal_gh_token +_set_personal_gh_token # run once at shell startup + +# One-shot personal-account gh call from anywhere: +# ghp repo list saravanakumardb1 +# ghp api /user +ghp() { + GH_TOKEN="$(/opt/homebrew/bin/gh auth token --user saravanakumardb1 2>/dev/null)" \ + /opt/homebrew/bin/gh "$@" +} +# === END: bytelyst-personal-gh-token === +``` + +Replace `saravanakumardb1` with your own personal account username if different. + +### 4. Reload and verify + +```bash +source ~/.zshrc + +# Should print: saravanakumardb1 +cd ~/code/mygh/learning_ai_common_plat && gh api /user --jq .login + +# Should print your work account login +cd /tmp && gh api /user --jq .login + +# ghp works from anywhere +cd /tmp && ghp api /user --jq .login # โ†’ saravanakumardb1 +``` + +## How agents and scripts benefit + +Once installed, the following all "just work": + +- **Manual `gh` commands** (`gh repo create`, `gh pr create`, `gh api`, `gh repo delete`). +- **Husky hooks** (`.husky/pre-commit`, `.husky/pre-push`) if any call `gh`. +- **Repo scripts** (`scripts/*.sh`) that invoke `gh`. +- **Windsurf workflows** (`.windsurf/workflows/*.md`) that include `gh` shell steps. +- **Agent automation** โ€” when Cascade / Claude Code / Codex shells out to `gh` from inside a workspace repo, it inherits the env and gets the right account. + +## Diagnostics + +```bash +# What account will `gh` use right now? +gh api /user --jq .login + +# Is GH_TOKEN currently set? +[ -n "$GH_TOKEN" ] && echo "YES (length: ${#GH_TOKEN})" || echo "NO" + +# Force a fresh token fetch (e.g., after `gh auth refresh`): +unset _bytelyst_gh_token; _set_personal_gh_token +``` + +## Common pitfalls + +- **Already-running shells** won't pick up changes to `~/.zshrc` โ€” `source ~/.zshrc` or open a new terminal. +- **`gh auth status` prints "GH_TOKEN env var is set"** when you're inside `~/code/mygh/`. That is **expected** โ€” it confirms the hook fired. +- **Don't put the token in `~/.zshrc` directly.** Always fetch it via `gh auth token --user ` so it stays in the keyring. +- **CI environments** typically set `GITHUB_TOKEN`, not `GH_TOKEN`. Using `GH_TOKEN` for this hook avoids interfering with CI. +- **Git HTTPS vs `gh` CLI are independent paths.** The `~/.gitconfig-personal` credential helper handles `git push`; the zsh hook handles `gh`. You need both for full coverage. + +## Why this is NOT in per-repo AGENTS.md + +This is **machine-local config**, not repo convention. A second contributor on a fresh laptop or a CI runner doesn't have `~/.zshrc` set up this way and shouldn't need to โ€” they'd authenticate however they prefer. AGENTS.md is for code/repo conventions; this skill doc is the right home for environment setup. + +## See also + +- [`dual-network-setup.md`](./dual-network-setup.md) โ€” corporate proxy + Gradle truststore (related: dual-environment routing) +- [`local-development.md`](./local-development.md) โ€” running services locally +- [`agent-behavior-guidelines.md`](./agent-behavior-guidelines.md) โ€” canonical agent rules diff --git a/AI.dev/SKILLS/index.md b/AI.dev/SKILLS/index.md index 6ba63f70..82e60c1c 100644 --- a/AI.dev/SKILLS/index.md +++ b/AI.dev/SKILLS/index.md @@ -9,6 +9,7 @@ - [Debug Service](./debug-service.md) - Systematic debugging methodology - [Local Development Setup](./local-development.md) - Starting services locally +- [GH Account Routing](./gh-account-routing.md) - Auto-route `gh` CLI to personal vs work account by directory - [Docker Compose](./docker-compose.md) - Full stack containerization - [Production Readiness](./production-readiness.md) - Pre-release validation - [Backup Main Branch](./backup-main-branch.md) - Smart backup with duplicate detection @@ -49,24 +50,25 @@ ## ๐Ÿ” Quick Reference -| Need | Skill | Location | -| --------------------- | ---------------------------------------------------- | -------------------------------- | -| Fix a failing service | [Debug Service](./debug-service.md) | ๐Ÿ”ง Development Workflows | -| Prepare for release | [Production Readiness](./production-readiness.md) | ๐Ÿงช Testing & Quality | -| Start all services | [Local Development Setup](./local-development.md) | ๐Ÿ”ง Development Workflows | -| Backup main branch | [Backup Main Branch](./backup-main-branch.md) | ๐Ÿ”ง Development Workflows | -| Release desktop app | [Desktop Release](./desktop-release.md) | ๐Ÿš€ Release & Deployment | -| Release iOS app | [iOS Release](./ios-release.md) | ๐Ÿš€ Release & Deployment | -| Generate store assets | [Generate Store Assets](./generate-store-assets.md) | ๐Ÿš€ Release & Deployment | -| Mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | ๐Ÿ“ฑ Mobile Development | -| Test desktop app | [Test Desktop App](./test-desktop-app.md) | ๐Ÿงช Testing & Quality | -| Test iOS app | [Test iOS App](./test-ios-app.md) | ๐Ÿงช Testing & Quality | -| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | ๐Ÿ“š Documentation & Communication | -| Scan repo for context | [Scan Repo Context](./scan-repo-context.md) | ๐Ÿ“š Documentation & Communication | -| Write tests | [Test Strategies](./test-strategies.md) | ๐Ÿงช Testing & Quality | -| Docker full stack | [Docker Compose](./docker-compose.md) | ๐Ÿ”ง Development Workflows | -| Security audit | [Security Auditing](./security-auditing.md) | ๐Ÿงช Testing & Quality | -| Architecture patterns | [Architecture Patterns](./architecture-patterns.md) | ๐Ÿ—๏ธ Architecture & Setup | +| Need | Skill | Location | +| ------------------------------- | ----------------------------------------------------- | -------------------------------- | +| Fix a failing service | [Debug Service](./debug-service.md) | ๐Ÿ”ง Development Workflows | +| Prepare for release | [Production Readiness](./production-readiness.md) | ๐Ÿงช Testing & Quality | +| Start all services | [Local Development Setup](./local-development.md) | ๐Ÿ”ง Development Workflows | +| Backup main branch | [Backup Main Branch](./backup-main-branch.md) | ๐Ÿ”ง Development Workflows | +| Release desktop app | [Desktop Release](./desktop-release.md) | ๐Ÿš€ Release & Deployment | +| Release iOS app | [iOS Release](./ios-release.md) | ๐Ÿš€ Release & Deployment | +| Generate store assets | [Generate Store Assets](./generate-store-assets.md) | ๐Ÿš€ Release & Deployment | +| Mobile code quality | [Mobile Code Quality](./mobile-code-quality.md) | ๐Ÿ“ฑ Mobile Development | +| Test desktop app | [Test Desktop App](./test-desktop-app.md) | ๐Ÿงช Testing & Quality | +| Test iOS app | [Test iOS App](./test-ios-app.md) | ๐Ÿงช Testing & Quality | +| Update AI docs | `../../.windsurf/workflows/repo_update-agent-docs.md` | ๐Ÿ“š Documentation & Communication | +| Scan repo for context | [Scan Repo Context](./scan-repo-context.md) | ๐Ÿ“š Documentation & Communication | +| Write tests | [Test Strategies](./test-strategies.md) | ๐Ÿงช Testing & Quality | +| Docker full stack | [Docker Compose](./docker-compose.md) | ๐Ÿ”ง Development Workflows | +| Security audit | [Security Auditing](./security-auditing.md) | ๐Ÿงช Testing & Quality | +| Architecture patterns | [Architecture Patterns](./architecture-patterns.md) | ๐Ÿ—๏ธ Architecture & Setup | +| Route `gh` CLI to right account | [GH Account Routing](./gh-account-routing.md) | ๐Ÿ”ง Development Workflows | ## Skill Levels @@ -75,6 +77,7 @@ - [Local Development Setup](./local-development.md) - [Debug Service](./debug-service.md) - [Test Strategies](./test-strategies.md) +- [GH Account Routing](./gh-account-routing.md) ### ๐ŸŸก Intermediate