Skip to content
sdlc

Typed GitHub client over gh CLI

State: open/verified · Kind: module · Audience: system

Summary

Section titled “Summary”
  • A typed GitHub client for TypeScript over the gh CLI: a total PullRequest/Review/CheckRun model, pure argv builders and parsers, and a tri-modal client where queries return parsed values, mutations throw, and raw() is the escape hatch.
  • Uses gh’s own stored credentials; reads no token itself.

Statement

Section titled “Statement”

The system can query and mutate GitHub pull-request state (list, view, review status, check runs) through a typed client that never leaves a field undefined — absent and unknowable both collapse to an explicit not-known value (UNKNOWN, null, [] only meaning empty) so callers can’t mistake a field they never requested for a fact. It normalizes the two shape hazards gh exposes directly: author logins that differ between GraphQL and REST transports, and the two node types (CheckRun/StatusContext) folded onto one verdict axis. It also settles the lazily-computed merge state (prViewSettled, up to 3 re-asks) rather than trusting a cold UNKNOWN.

What it provides

Section titled “What it provides”
  • A Gh client class taking an injectable CommandRunner (from @sksizer/command-seam) so tests run offline.
  • Pure, side-effect-free verb builders and parsers usable directly by async fan-out callers without duplicating parsing logic.
  • A closed three-mode failure contract: queries return the absence value and never throw, mutations throw CommandFailed carrying argv, raw(argv) hands back the unprocessed result.

Underlying implementation

Section titled “Underlying implementation”
  • packages/ts/easy-gh/index.ts, verbs.ts, parse.ts, repo.ts, sync.ts, types.ts

Locations

Section titled “Locations”
  • packages/ts/easy-gh/

← Back to Capabilities