suuntool CLAUDE.md

CLAUDE.md — developer orientation

Audience: senior engineers (and LLM agents) joining this repo. Read this once, then read the code.

What this is

suuntool is a Go CLI for the unofficial Suunto / Sports-Tracker HTTP API. It is meant to be used by humans and by agents driving a terminal — every UX decision flows from that dual audience.

Internal reference material (endpoint inventory, signing scheme, Python reference client, golden-vector diagnostics) lives in handoff/. That directory is excluded via .git/info/exclude — not .gitignore — so it stays local but is never committed. Treat it as load-bearing reference material; don't delete it.

Layering — strict, one-way

main.go
└── cmd/                 Cobra commands. Knows about session+api+output, nothing else.
    ├── root.go          persistent flags, exit codes, helpers (baseURL, authedClient, emit, pickTimeout, parseSince, useTTYColor)
    ├── login.go logout.go whoami.go profile.go doctor.go endpoints.go version.go
    ├── workouts.go      workouts list/get/count/stats/sml/fit/export/comments/react/edit/upload/delete (+ --summary, --stream, --since)
    ├── guides.go        guides list/download/upload/update/pin/unpin/priority/delete (+ --yes). Transport only — no guide.json parsing.
    ├── wellness.go      wellness sleep/activity/recovery/sleepstages NDJSON streams
    ├── wellness_sleep_pretty.go   TTY-only sleep table renderer (writeSleepFooter)
    ├── mcp.go           `suuntool mcp` stdio MCP server entry (--allow-write / --allow-destructive)
    └── login_test.go, root_test.go, wellness_sleep_pretty_test.go    end-to-end via httptest
internal/
├── auth/                signing pipeline. Zero net/http imports.
│   ├── keys.go          embedded signing constants (login parts, TOTP parts, package name, user-agent)
│   ├── obfuscator.go    KeyObfuscator XOR + lossy-UTF-8 replace; DeriveLoginSecret / DeriveTOTPMasterSecret
│   ├── totp.go          PBKDF2-HmacSHA1 + RFC 6238 HOTP → GenerateTOTP(salt, offsetMS)
│   └── signer.go        SignParams(path, []Param) → base64url(SHA-256), RandomSalt, NowMS
├── api/                 HTTP transport.
│   ├── client.go        Client + Do()/DoStream() — injects STTAuthorization + User-Agent, maps HTTP status → typed errors, transparent gzip
│   ├── envelope.go      generic AskoResponse[T] + DecodeAsko[T]
│   ├── errors.go        *Error{Code, Message, Hint, HTTP, Exit} — ExitCode() drives os.Exit
│   └── endpoints/       per-resource wrappers — add a file here for each new resource
│       ├── session.go   Login (POST /login2), Logout, RemoteUserSession + Pretty()
│       ├── user.go      Whoami, Settings, Follow, UserByName + Prettier impls
│       ├── workouts.go  List/Get/Count/Stats/SML/FIT/Delete + WorkoutList.Summary / SummaryWithWoW
│       ├── comments.go reactions.go edit.go share.go extensions.go upload.go   workout writes (x-totp via cmd layer)
│       ├── guides.go    List/Download/Create/Update/Delete/SetGuidePinned/GuidePriority — raw zip body, no x-totp, no guide.json parsing (see the file's own package doc)
│       ├── wellness.go  NDJSON stream decoders (sleep/activity/recovery/sleepstages)
│       ├── format.go    formatKm / formatDuration / renderTable(Styled) shared by Pretty()
├── session/             session.go — XDG-aware persistence, 0600 perms, ErrNoSession (+ TOTPHeaders helper)
├── output/              the single render boundary
│   ├── output.go        Render / RenderToFile, Opts, Prettier interface, resolveFormat
│   └── tty.go           IsStdoutTTY (respects NO_COLOR)
└── mcp/                 Model Context Protocol adapter (stdio server)
    ├── server.go        Run(ctx, Opts), registerAll, deps (api.Client + session)
    ├── registry.go      tier + toolRegistrar shape; per-tool registrars elsewhere
    ├── tools_read.go    read-tier registrars (whoami, profile_*, workouts_*, wellness_*, doctor, activity_type_name, guides_list, guides_download, guides_priority)
    ├── tools_write.go   --allow-write registrars (comment, react, edit, batch_update, share, extensions, upload, guides_upload, guides_update, guides_pin, guides_unpin)
    ├── tools_destructive.go  --allow-destructive registrars (delete, uncomment, unreact, guides_delete)
    ├── activity.go      activityId → activityName enrichment shared by workouts_list/get/stats
    └── errors.go        mapError / mapErrorToCallToolResult (preserves *api.Error structure for the LLM)