How wakatime/wakatime-cli works
Project Type and Purpose
• This is a Go command‐line interface (CLI).
• Its sole purpose is to collect “heartbeats” (editor usage data) via subcommands, process or store them offline, then send them to the WakaTime API server. It also reads/writes a common INI config file and provides utility commands (e.g. offline, today, version, etc.) for plugin authors.
File Structure
• Top‐Level Entry: main.go + cmd/ subdirectories. The CLI framework (Cobra) is set up in cmd/root.go, with individual subcommands in cmd/<name>/.
• Domain Libraries: pkg/ contains all core logic, organized by concern:
• pkg/api – HTTP transport, authentication, request/response definitions
• pkg/heartbeat – heartbeat creation, sanitization, formatting
• pkg/project – project detection (Git, Hg, SVN, TFVC)
• pkg/language + pkg/lexer – language identification, syntax lexers
• pkg/offline + cmd/offline* – offline storage and replay
• pkg/fileexperts, pkg/filter, pkg/summary, pkg/log, pkg/metrics – auxiliary processing
• pkg/file, pkg/ini, pkg/version, etc. – configuration & I/O
• Build & CI: Makefile, GitHub Actions workflows, tests under *_test.go in each package.
README for Insights
• Confirms it is the shared CLI for editor plugins, driven by an INI config (~/.wakatime.cfg).
• Points to usage, troubleshooting, plugin author docs.
Components and Their Interactions
A. CLI Layer
• Entrypoint (main.go)
• Command Dispatcher (cmd/root.go + subcommands in cmd/*)
– Each subcommand invokes one or more domain services (e.g. heartbeat, offlinecount, today).
B. Configuration Manager
• Reads/Writes INI config (pkg/ini)
• Supplies API keys, base URL, offline settings to other modules
C. Domain Services
1. Heartbeat Service (pkg/heartbeat)
– Collects file metadata, language, project info
– Sanitizes and formats heartbeats
2. Project Detector (pkg/project)
– Inspects VCS dirs (Git, Hg, SVN, TFVC) to determine project name
3. Language & Lexer (pkg/language, pkg/lexer)
– Determines file’s programming language and other attributes
4. FileExperts (pkg/fileexperts)
– Calls external service to augment file metadata
5. Offline Store (pkg/offline)
– Saves heartbeats locally when API unreachable
– Replays them in batch later
D. Infrastructure
• HTTP Client (pkg/api/transport*) – makes REST calls to WakaTime API
• Logging & Metrics (pkg/log, pkg/metrics) – writes logs, collects internal metrics
• Error Handling (pkg/wakaerror, pkg/exitcode) – consistent error messages and exit codes
E. External Service
• WakaTime API Server – receives heartbeats, returns responses
Architectural Patterns and Principles
• Layered Architecture: Separation between CLI layer, domain services, infrastructure (HTTP, logging), and external API.
• Modular Packaging: Each pkg/* is an independent Go package with its own tests.
• Single‐Responsibility: Commands do not perform business logic—they delegate to pkg/ services.
• Resilience: Offline queuing and retry/backoff (pkg/backoff) ensure reliability.
Detailed Component Breakdown (suggest grouping rather than exhaustive listing)
• pkg/backoff attached to the HTTP Client, indicating retry logic.