Happier GitHub Ops (bot gh wrapper)

This repo provides yarn ghops as a thin wrapper around the GitHub CLI (gh) that forces authentication via the bot Personal Access Token. HAPPIER_GITHUB_BOT_TOKEN has highest priority; on macOS, the wrapper otherwise reads the validated token from Keychain service happier/ghops, account happier-bot.

Prerequisites

• gh is installed on the host and reachable on PATH.
• Either environment variable HAPPIER_GITHUB_BOT_TOKEN is set to the bot's fine-grained PAT, or the token was stored on macOS with yarn ghops auth store.

Contract / Safety

• yarn ghops ... refuses to run if neither the environment override nor the macOS Keychain credential is available.
• Runs non-interactively (GH_PROMPT_DISABLED=1).
• Uses an isolated repo-local GH_CONFIG_DIR by default.
• Never falls back to personal gh, GH_TOKEN, or GITHUB_TOKEN credentials.
• Forces GH_HOST=github.com so an inherited host override cannot redirect the bot token.
• auth store validates that the token belongs to happier-bot before persisting it.

Bot credential lifecycle

On macOS, configure the bot once without echoing the token:

bash
yarn ghops auth store

The command prompts securely when HAPPIER_GITHUB_BOT_TOKEN is absent. If the environment variable is present, it validates and stores that value without printing it.

Verify the resolved identity and source:

bash
yarn ghops auth status

Remove only the stored Keychain credential:

bash
yarn ghops auth clear

On non-macOS platforms, continue providing HAPPIER_GITHUB_BOT_TOKEN; Keychain lifecycle commands fail closed until a native credential-store adapter exists.

What to write (LLM guidelines)

When creating/updating public issues, keep it useful but minimal:

• Prefer user impact, repro steps, expected vs actual, and acceptance criteria.
• Link to PRs/commits by URL when available.
• Avoid internal-only detail: no private logs, no secrets, no tokens, and no stack dumps from private environments.
• If you need to share sensitive debugging context, summarize it and keep the raw detail local.

Suggested comment format for progress updates:

• What changed (1–3 bullets)
• Why (brief)
• Next step / what’s blocked (one line)
• Links (PR/commit/issues)

Common commands

Verify identity (must be the bot user):

bash
yarn ghops api user

Project conventions (Happier roadmap)

Canonical public roadmap project:

• Owner: happier-dev
• Project number: 1
• URL: https://github.com/orgs/happier-dev/projects/1

Labels (conventions)

These labels are intended to keep the public roadmap curated and consistent:

• roadmap (triage-owned): include this item on the public roadmap project
• priority:p0, priority:p1, priority:p2, priority:p3 (triage-owned)
• stage:not-shipped, stage:experimental, stage:beta, stage:ga (optional; rollout state)
• type: bug, type: feature, type: task (recommended)
• source: bug-report (applied automatically by the bug-report service)

When asked to “create an issue and put it on the roadmap with P0”, do:

1) Create the issue 2) Apply roadmap and priority:p0 (and a type:* label) 3) Ensure it lands on the roadmap project (automation should add it; if not, add explicitly)

When you create or meaningfully update an issue/PR, ensure it’s visible on the roadmap:

• Prefer GitHub Project automation (auto-add when roadmap label is present).
• If you’re not sure it will be auto-added, explicitly add it:

bash
yarn ghops project item-add 1 --owner happier-dev --url https://github.com/happier-dev/happier/issues/123

Create an issue (repo explicit is recommended):

bash
yarn ghops issue create -R happier-dev/happier --title "..." --body "..." --label "type: bug"

For CLI-created issues, format the body like the templates:

• Bug: summary + what happened + expected behavior + (optional) repro + (optional) frequency/severity + (optional) environment
• Feature: problem + proposal + acceptance criteria

For scripting / machine-readable output, prefer gh api:

bash
yarn ghops api repos/happier-dev/happier/issues \
  -f title="..." \
  -f body="..." \
  --jq '{number: .number, url: .html_url}'

Comment on an issue:

bash
yarn ghops api repos/happier-dev/happier/issues/123/comments -f body="Update: ..."

Apply labels (example):

bash
yarn ghops api repos/happier-dev/happier/issues/123/labels -f labels[]="roadmap" -f labels[]="priority:p0"

Titles (guidelines)

Prefer short, descriptive titles without noisy prefixes:

• Good: Sessions flicker online/inactive
• Good: CLI: doctor fails when daemon is stopped
• Avoid: P0: ... (priority belongs in the project/labels, not the title)
• Avoid: long bracket stacks like [Bug][iOS][P0] ...

Add an issue/PR to the org project (Project v2):

bash
yarn ghops project item-add 1 --owner happier-dev --url https://github.com/happier-dev/happier/issues/123

List project fields/items (JSON):

bash
yarn ghops project field-list 1 --owner happier-dev --format json
yarn ghops project item-list 1 --owner happier-dev --format json