Rewrite hubctl in Bun + TypeScript + Effect v4 (agent-first JSON envelope)

[jordangarrison]

Summary

Reimplements hubctl from Ruby/Thor to Bun + TypeScript + Effect v4 as an agent-first CLI: every command emits a structured JSON envelope by default, with an optional --pretty human renderer over the same envelope. Full feature parity with the Ruby tool (minus the stubbed server command), distributed as a Bun-compiled binary and a Nix flake.

⚠️ BREAKING CHANGE — the Ruby implementation is removed and the --format table|json|list flag is dropped (the envelope subsumes it). See docs/adrs/000002-agent-first-json-envelope.md.

Architecture

Layered Effect app: thin cli/ command modules → centralized output/ envelope renderer → services/ domain services (Context.Service) → a single github/ Octokit wrapper → Bun platform. Typed errors flow in the E channel; services resolve via Layers. The envelope is always built; pretty mode is a renderer over it, so the two views can't drift.

Command surface (parity with the Ruby CLI)

version · auth · config <get|set|list|init|path> · repos <list|show|create|clone|archive|topics> · orgs <list|show|members|repos|teams|info> · users <show|whoami|list|invite|remove> · teams <list|show|create|members|add|remove> · enterprise <show|orgs|members|owners|billing|licenses|audit-log|sso|stats|security-analysis>

• Root (no args) emits the full command tree as JSON for agent discovery.
• next_actions (HATEOAS) on success; error.code/message + plain-language fix on failure.
• Destructive ops require --yes in JSON mode (and prompt at a TTY).
• NDJSON streaming for long operations (e.g. enterprise audit-log); ~50-item result truncation for context-window discipline.

How it was built & verified

• TDD throughout — failing test → red → minimal impl → green → validate → commit, per task.
• Multi-agent code review before cutover (per-group parity vs the Ruby source + correctness/security/test-quality, with adversarial verification): 10 Critical + 24 Important findings fixed (missing config/auth groups, orgs repos/teams/info, teams show, enterprise show, a teams list decode bug, clone exit-code handling, --org fallback, and more).
• 32 deferred Minor findings tracked in docs/review-deferred-minor.md.

Robustness: decode hardening (no decode ever crashes the envelope)

Every GitHub payload was decoded with the throwing Schema.decodeUnknownSync, called inside Effect.map. A throw there is an uncaught defect — it escapes the typed E channel, so a real API response that didn't match the schema (a field absent on a list endpoint, a null where a string was assumed, a new/removed field) dumped a raw stack trace instead of the {ok,command,result,next_actions,error,fix} envelope. For an agent-first tool whose whole contract is "always emit a valid envelope," that's a contract violation. We hit four of these in orgs and hand-fixed them (95ae480); this makes the fix systemic.

• Shared helper (src/schema/decode.ts): decode(schema, label) wraps the effectful Schema.decodeUnknownEffect into Effect<A, DecodeError> — a mismatch now fails in the typed E channel instead of throwing. DecodeError (a Data.TaggedError) carries code:"decode_error", a message naming the failing field/path, and a "this looks like a hubctl bug — please report it" fix.
• Honest E channel, zero churn: DecodeError joined the GithubError union, so every Effect<…, GithubError> service signature gained it without edits. The existing emit → Output.fail path renders it as a standard ok:false envelope.
• All decode sites converted across repos/orgs/users/teams/enterprise/auth (Effect.map(decode) → Effect.flatMap(decode); data-first and inline-closure sites restructured to sequence the decode effectfully). The on-disk config file JSON parse is hardened the same way, so a corrupt config.json is a clean envelope, not a crash.
• Schemas are already structurally lenient — Schema.Struct ignores unknown keys in this Effect beta, so additive GitHub API changes never break decoding; only missing/null/wrong-type required fields do, and those now render cleanly.
• Left as-is (intentional): the Schema.encodeSync sites in output/render.ts, output/service.ts, and the config write path — they encode hubctl's own post-decode, JSON-safe data, never external input.
• TDD: each service got a test feeding a realistic-but-mismatched payload (one required field omitted/nulled — not an over-complete fixture, which is exactly what masked the original bugs) asserting a DecodeError in the E channel, plus a CLI-level regression asserting the full pipeline renders ok:false/decode_error. Verified end-to-end with a live-token smoke run across every command group — every output a single valid JSON envelope, success and error paths, zero stack traces.

Testing

• bun run validate (format → lint → typecheck via tsgo → 269 tests → ast-grep): green
• bun run test:e2e (compiled-binary smoke against a mock GitHub): green
• nix build .#hubctl produces a working binary

Notes for reviewers

• Nix packages a bun-wrapper over src/main.ts rather than the bun build --compile artifact: autoPatchelf rewrites the ELF and breaks Bun's detection of the bundle appended to the executable. The true standalone single-file binary still ships via bun run build:local / release artifacts.
• Config moved ~/.hubctl.yml (YAML) → ~/.config/hubctl/config.json (JSON) — an intentional design decision.
• users intentionally overlaps some org-membership routes with orgs (faithful to the Ruby users.rb).