$ show basecamp/fizzy-cli
This repository implements a comprehensive Go CLI client for Fizzy, a kanban/project-management SaaS platform. The binary (`fizzy`) provides full CRUD operations on boards, columns, cards, comments, steps, tags, reactions, notifications, webhooks, and users via a structured command tree built with Cobra. It supports multiple output formats (JSON, styled, markdown, IDs-only, count) with a built-in jq filter for JSON processing. The CLI also includes interactive signup flows, board migration between accounts, a doctor health check, and a Model Context Protocol (MCP) server for AI agent integration. Architecturally, the codebase is well-layered: a generated SDK (`fizzy-sdk`) handles typed API interactions, while a legacy HTTP client manages file uploads/downloads and multipart. Configuration follows a strict precedence chain (flags → environment variables → saved profiles → local project YAML → global config). Every command returns a consistent envelope with breadcrumbs and context for guided usage. The repo includes an embedded agent skill (`SKILL.md`) that is distributed to Claude Code and other coding agents, and a hand-written MCP catalog that mirrors the Fizzy public API surface. The project demonstrates strong engineering practices: extensive unit and end-to-end tests with mock clients, fuzz testing, surface snapshot gates, CI/CD with security scanning (gitleaks, scorecard, govulncheck), and a sophisticated release pipeline (GoReleaser, Homebrew, AUR, Scoop, macOS signing). Several components are designed for reuse, including the mock client testing pattern, atomic profile state management, and the typed MCP catalog definition system. Maintenance is active with frequent commits and issue triage, though the coexistence of two HTTP clients and the hand-crafted API catalog present minor drift risks.
The LLM identified 4 files worth highlighting for reuse:
Implements `MockClient` that satisfies `client.API` with path-based response registration, call recording, and error injection. This pattern enables isolated unit testing of CLI commands without a real API server, and can be extracted for testing any Cobra-based CLI that communicates via a similar client interface.
Provides atomic profile state operations with snapshot and restore capabilities. Used during auth login/logout and board configuration to ensure credential changes are rolled back on failure. This is a reusable pattern for managing multi-account configurations with consistency guarantees.
Defines typed `Domain`, `Operation`, and `Param` structs for describing an API surface in a way that can be validated for consistency (duplicate actions, path/param mismatches, readonly/method conflicts). This catalog pattern can be reused to generate MCP tool definitions or documentation from hand-written specs.
Wraps the standard output writer to intercept JSON output and apply a compiled `gojq` filter before writing. Supports error envelopes passing through unfiltered and integrates with the CLI's output format system. This pattern is reusable for adding built-in JSON querying to any CLI that produces JSON output.