create-hq 10.7.1 → 10.8.0

package/commands/invite.md

@@ -0,0 +1,215 @@
+# Invite a Team Member
+
+Send an invite for a new team member. Only org admins can invite — members are guided to contact their admin.
+
+**Usage:** `/invite`
+
+**Requires:** `gh` CLI authenticated (`gh auth status`)
+
+## Process
+
+1. Find team metadata from `companies/*/team.json`
+2. If multiple teams, ask which team
+3. Check if the current user is an org admin
+4. If admin: generate invite token + send GitHub org invite
+5. If not admin: show a message to contact the admin with a prepared email
+
+## Invite Token
+
+The token is a self-contained `hq_`-prefixed base64url string encoding:
+- org (GitHub org login)
+- repo (team repo name, e.g. hq-indigo)
+- slug (team slug for companies/{slug}/)
+- teamName (human-readable)
+- cloneUrl (HTTPS clone URL)
+- invitedBy (admin's GitHub login)
+
+## Steps
+
+### 1. Verify gh CLI
+
+Check that `gh` is installed and authenticated:
+```bash
+gh auth status 2>&1
+```
+
+If `gh` is not found:
+```
+GitHub CLI (gh) is required for team commands.
+Install it: https://cli.github.com
+```
+Stop here.
+
+If not authenticated:
+```
+GitHub CLI is not authenticated. Run:
+  gh auth login
+Then try /invite again.
+```
+Stop here.
+
+Get the current user's login:
+```bash
+gh api user --jq .login
+```
+
+Store as `{login}`.
+
+### 2. Discover teams
+
+Find all team.json files:
+```bash
+find companies/*/team.json -maxdepth 0 2>/dev/null
+```
+
+If no files found:
+```
+No teams found. Create a team first:
+  npx create-hq
+```
+Stop here.
+
+### 3. Select team
+
+If multiple teams exist, present a numbered list and ask the user to select one.
+
+If only one team exists, use it automatically.
+
+### 4. Extract team metadata
+
+Read the selected `companies/{slug}/team.json` and extract:
+- `team_name` — human-readable team name
+- `team_slug` — directory slug under `companies/`
+- `org_login` — GitHub org login (e.g. `indigoai-us`)
+- `created_by` — GitHub username of the team admin/creator
+
+Get the clone URL:
+```bash
+git -C companies/{slug} remote get-url origin
+```
+
+### 5. Check org role
+
+Check the current user's org membership:
+```bash
+gh api "orgs/{org_login}/memberships/{login}" --jq .role 2>&1
+```
+
+Parse the result:
+- If `"admin"` → continue to step 6 (admin flow)
+- If `"member"` → go to step 5a (non-admin flow)
+- If error (403 — not a member) → tell the user they're not a member of `{org_login}` and suggest `npx create-hq` to join
+- If error (404 or other) → go to step 5a (non-admin flow)
+
+### 5a. Non-admin: contact your admin
+
+If the user is not an org admin, they cannot send invitations.
+
+#### Find the admin's email
+
+Try these sources in order until an email is found:
+
+1. **Git log** — the admin created the team repo, so the first commit has their email:
+   ```bash
+   git -C companies/{slug} log --format='%ae' --reverse | head -1
+   ```
+
+2. **GitHub profile** — check public profile (often null, but worth trying):
+   ```bash
+   gh api "users/{created_by}" --jq .email 2>/dev/null
+   ```
+
+3. **Fallback** — if both return nothing, use `{created_by}@users.noreply.github.com`.
+
+Use the first non-null email found as `{admin_email}`.
+
+#### Show message and copy draft to clipboard
+
+Show:
+```
+Only org admins can invite new members to {team_name}.
+
+Your team admin is @{created_by} ({admin_email}).
+I've prepared an email draft and copied it to your clipboard.
+```
+
+Build the email draft:
+```
+Hey {created_by},
+
+Could you invite a new member to our {team_name} HQ team?
+You can run /invite from your HQ to generate an invite code,
+or go to https://github.com/orgs/{org_login}/people to add them directly.
+
+Thanks!
+```
+
+Copy the draft to the clipboard:
+```bash
+printf 'Hey {created_by},\n\nCould you invite a new member to our {team_name} HQ team?\nYou can run /invite from your HQ to generate an invite code,\nor go to https://github.com/orgs/{org_login}/people to add them directly.\n\nThanks!' | pbcopy 2>/dev/null || true
+```
+
+Then open a pre-populated mailto link (macOS):
+```bash
+open "mailto:{admin_email}?subject=HQ%20team%20invite%20request%20%E2%80%94%20{team_name}&body=Hey%20{created_by}%2C%0A%0ACould%20you%20invite%20a%20new%20member%20to%20our%20{team_name}%20HQ%20team%3F%0AYou%20can%20run%20%2Finvite%20from%20your%20HQ%20to%20generate%20an%20invite%20code%2C%0Aor%20go%20to%20https%3A%2F%2Fgithub.com%2Forgs%2F{org_login}%2Fpeople%20to%20add%20them%20directly.%0A%0AThanks!" 2>/dev/null || true
+```
+
+If `pbcopy` is not available (Linux), try `xclip -selection clipboard` or `xsel --clipboard` instead.
+
+**Stop here** — do not proceed to token generation.
+
+### 6. Ask for email (admin only)
+
+Ask: **"New member's email address? (leave blank to skip GitHub org invite)"**
+
+### 7. Send GitHub org invite (if email provided)
+
+If the user provided an email, send the org invitation:
+```bash
+gh api "orgs/{org_login}/invitations" -X POST -f email="{email}" -f role="direct_member" 2>&1
+```
+
+- On success (2xx): note that the invite was sent
+- On failure (403/404): fall back to manual instructions:
+  ```
+  Could not send org invite automatically.
+  Invite them manually: https://github.com/orgs/{org_login}/people
+  ```
+
+### 8. Generate invite token
+
+Build the token using python3:
+```bash
+python3 -c "
+import json, base64
+payload = {
+    'org': '{org_login}',
+    'repo': 'hq-{slug}',
+    'slug': '{slug}',
+    'teamName': '{team_name}',
+    'cloneUrl': '{clone_url}',
+    'invitedBy': '{login}'
+}
+token = 'hq_' + base64.urlsafe_b64encode(json.dumps(payload).encode()).decode().rstrip('=')
+print(token)
+"
+```
+
+### 9. Output results
+
+Display the invite code and a ready-to-share message block.
+
+If the GitHub org invite was sent, include a confirmation line.
+
+## Ready-to-Share Message Template
+
+```
+You've been invited to join {teamName} on HQ!
+
+Step 1: Accept the GitHub organization invite (check your email from GitHub)
+Step 2: Install Node.js if you don't have it: https://nodejs.org
+Step 3: Open your terminal and run: npx create-hq
+Step 4: When asked "Do you have an HQ Teams account?", choose Yes
+Step 5: Paste this invite code when prompted: {token}
+Step 6: Follow the remaining prompts to complete setup
+```

package/commands/promote.md

@@ -0,0 +1,161 @@
+# Promote a Team Member to Admin
+
+Give a team member org admin privileges so they can invite new members and manage the team.
+
+**Usage:** `/promote` or `/promote @username`
+
+**Requires:** `gh` CLI authenticated (`gh auth status`)
+
+## Steps
+
+### 1. Verify gh CLI
+
+Check that `gh` is installed and authenticated:
+```bash
+gh auth status 2>&1
+```
+
+If `gh` is not found:
+```
+GitHub CLI (gh) is required for team commands.
+Install it: https://cli.github.com
+```
+Stop here.
+
+If not authenticated:
+```
+GitHub CLI is not authenticated. Run:
+  gh auth login
+Then try /promote again.
+```
+Stop here.
+
+Get the current user's login:
+```bash
+gh api user --jq .login
+```
+
+Store as `{login}`.
+
+### 2. Discover teams
+
+Find all team.json files:
+```bash
+find companies/*/team.json -maxdepth 0 2>/dev/null
+```
+
+If no files found:
+```
+No teams found. Create a team first:
+  npx create-hq
+```
+Stop here.
+
+### 3. Select team
+
+If multiple teams exist, present a numbered list and ask the user to select one.
+
+If only one team exists, use it automatically.
+
+### 4. Extract team metadata
+
+Read the selected `companies/{slug}/team.json` and extract:
+- `team_name` — human-readable team name
+- `org_login` — GitHub org login (e.g. `indigoai-us`)
+
+### 5. Verify current user is an admin
+
+Check the org role:
+```bash
+gh api "orgs/{org_login}/memberships/{login}" --jq .role 2>&1
+```
+
+If `role` is not `"admin"`:
+```
+Only org admins can promote members.
+Your team admin is @{created_by} — ask them to run /promote.
+```
+Stop here.
+
+### 6. List org members
+
+Fetch current non-admin org members:
+```bash
+gh api "orgs/{org_login}/members?role=member&per_page=100" --jq '.[].login' 2>&1
+```
+
+If no non-admin members found:
+```
+No members to promote — everyone in {org_login} is already an admin.
+```
+Stop here.
+
+If the user provided a `@username` argument, look for that username in the list. If found, skip to step 7 with that user. If not found:
+```
+@{username} is not a member of {org_login}, or is already an admin.
+```
+Stop here.
+
+If no argument was provided, present a numbered list:
+```
+Members of {team_name} ({org_login}):
+
+  1. @alice
+  2. @bob
+  3. @charlie
+
+Which member should become an admin?
+```
+
+### 7. Confirm promotion
+
+Show what will happen:
+```
+Promote @{target_username} to admin of {org_login}?
+
+This will allow them to:
+  - Invite new members to the org
+  - Manage repository settings
+  - Promote other members
+
+Type "yes" to confirm:
+```
+
+Wait for explicit "yes" confirmation. Any other response cancels.
+
+### 8. Send promotion API call
+
+```bash
+gh api "orgs/{org_login}/memberships/{target_username}" -X PUT -f role="admin" 2>&1
+```
+
+Check the response:
+- If `role` is `"admin"` in response: success
+- If 403: insufficient permissions (the GitHub App may not have the required scope)
+- If 404: user not found in org
+
+### 9. Report result
+
+**On success:**
+```
+@{target_username} is now an admin of {org_login}.
+
+They can now:
+  - Run /invite to add new team members
+  - Run /promote to make other members admin
+```
+
+**On failure (403):**
+```
+Could not promote @{target_username} — insufficient permissions.
+
+You can promote them manually:
+  https://github.com/orgs/{org_login}/people
+  Find @{target_username} → Change role → Owner
+```
+
+**On failure (404):**
+```
+@{target_username} is not a member of {org_login}.
+Invite them first with /invite, then promote after they join.
+```