Imported from openclaw/gogcli (AGENTS.md). Install upstream with npx skills add openclaw/gogcli. Copyright stays with the author.

Repository Guidelines

Project Structure

• cmd/gog/: CLI entrypoint.
• internal/: implementation (cmd/, Google API/OAuth, config/secrets, output/UI).
• Tests: *_test.go next to code; opt-in integration suite in internal/integration/ (build-tagged).
• bin/: build outputs; docs/: specs/releasing; scripts/: release helpers + scripts/gog.mjs.

Build, Test, and Development Commands

• make / make build: build bin/gog.
• make tools: install pinned dev tools into .tools/.
• make fmt / make lint / make test / make ci: format, lint, test, full local gate.
• Optional: pnpm gog …: build + run in one step.
• Hooks: lefthook install enables pre-commit/pre-push checks.

Coding Style & Naming Conventions

• Formatting: make fmt (goimports local prefix github.com/openclaw/gogcli + gofumpt).
• Output: keep stdout parseable (--json / --plain); send human hints/progress to stderr.
• Gmail labels: treat label IDs as case-sensitive opaque tokens; only case-fold label names for name lookup.

Testing Guidelines

• Unit tests: stdlib testing (and httptest where needed).
• Integration tests (local only):
  • GOG_IT_ACCOUNT=you@gmail.com go test -tags=integration ./internal/integration
  • Requires OAuth client credentials + a stored refresh token in your keyring.

Commit & Pull Request Guidelines

• Create commits with committer "<msg>" <file...>; avoid manual staging.
• Follow Conventional Commits + action-oriented subjects (e.g. feat(cli): add --verbose to send).
• Group related changes; avoid bundling unrelated refactors.
• PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
• PR review flow: when given a PR link, review via gh pr view / gh pr diff and do not change branches.
• Maintain CHANGELOG.md: add user-visible changes to Unreleased as fixes and features land, with PR/issue references and contributor thanks. Finalize that section at release; do not put later work under an already published version. The release-time-only changelog exception for openclaw/openclaw does not apply to this repository.

PR Workflow (Review vs Land)

• Review mode (PR link only): read gh pr view/diff; do not switch branches; do not change code.
• Landing mode: temp branch from main; bring in PR (squash default; rebase/merge when needed); fix; update CHANGELOG.md (PR #/issue + thanks); run make ci; final commit; merge to main; delete temp; end on main.
• If landing contributor work, always add Co-authored-by: trailers for PR authors, even when we partially rewrite, group, or manually apply their changes; leave a PR comment with what landed + SHAs.
• New contributor: thank in CHANGELOG.md (and update README contributors list if present).

Security & Configuration Tips

• Never commit OAuth client credential JSON files or tokens.
• Prefer OS keychain backends; use GOG_KEYRING_BACKEND=file + GOG_KEYRING_PASSWORD only for headless environments.