fix(formatter): improve table output for API responses

[platinummonkey]

Summary

Enhances the formatter to properly handle JSON:API responses and timeseries data when using --output=table, fixing incorrect table formatting across multiple commands.

Changes

Formatter Improvements (pkg/formatter/formatter.go)

• JSON:API Support: Added detection and flattening of JSON:API format responses (objects with attributes and relationships fields) for better table display
• Timeseries Table Format: Implemented formatTimeseriesAsTable() to extract and display actual timeseries data from metrics query responses
  • Detects timeseries responses (responses with times and values arrays)
  • Formats as table with Timestamp and Series columns instead of showing envelope structure
  • Supports multiple series with separate columns
• Priority Field Ordering: Enhanced table column ordering to prioritize common fields (id, name, title, status, etc.)
• Relationship Extraction: Added support for extracting relationship IDs and types from JSON:API responses

CLI Output Enhancement (cmd/*.go)

• Updated 28 command files to use formatter.FormatOutput() instead of hardcoded formatter.ToJSON()
• Enables --output flag support (json, yaml, table) across all commands
• Improved error handling with status codes in error messages

Documentation (CLAUDE.md)

• Clarified project scope: "28 command groups with 200+ subcommands across 33 API domains"

Testing

Before

./pup metrics query --query="avg:system.cpu.user{*}" --from="1h" --output=table

Output showed JSON:API envelope:

┌────────────┬─────────────────────┐
│   FIELD    │        VALUE        │
├────────────┼─────────────────────┤
│ attributes │ {3 fields}          │
│ id         │ 0                   │
│ type       │ timeseries_response │
└────────────┴─────────────────────┘

After

Same command now shows actual timeseries data:

┌───────────────┬──────────┐
│   TIMESTAMP   │ SERIES 0 │
├───────────────┼──────────┤
│ 1770664900000 │ 22.43    │
│ 1770664920000 │ 22.70    │
│ 1770664940000 │ 22.45    │
...

Commands Tested

• ✅ pup metrics query --output=table - now displays timeseries data
• ✅ pup monitors list --output=table - displays monitor list
• ✅ pup logs search --output=table - displays log entries
• ✅ All output formats (json, yaml, table) work across all commands

Files Changed

• pkg/formatter/formatter.go - Core formatter improvements
• cmd/*.go - 28 command files updated for consistent output handling
• CLAUDE.md - Documentation clarity

---

🤖 Generated with Claude Code

[github-actions]

📊 Test Coverage Report

Overall Coverage: 75.1%

Threshold: 80% ❌

Coverage by Package

## Coverage by Package

- github.com/DataDog/pup/pkg/auth/callback/server.go:40: 81.2%
- github.com/DataDog/pup/pkg/auth/dcr/client.go:28: 100.0%
- github.com/DataDog/pup/pkg/auth/dcr/types.go:24: 100.0%
- github.com/DataDog/pup/pkg/auth/oauth/client.go:22: 100.0%
- github.com/DataDog/pup/pkg/auth/oauth/pkce.go:24: 85.7%
- github.com/DataDog/pup/pkg/auth/storage/factory.go:53: 94.7%
- github.com/DataDog/pup/pkg/auth/storage/keychain.go:44: 42.9%
- github.com/DataDog/pup/pkg/auth/storage/storage.go:58: 71.4%
- github.com/DataDog/pup/pkg/auth/types/types.go:23: 100.0%
- github.com/DataDog/pup/pkg/client/client.go:28: 94.1%
- github.com/DataDog/pup/pkg/config/config.go:22: 100.0%
- github.com/DataDog/pup/pkg/formatter/formatter.go:31: 100.0%
- github.com/DataDog/pup/pkg/util/time.go:20: 95.8%

## Summary

total:								(statements)		75.1%

---

📈 Coverage Status: ❌ FAILED - Coverage below minimum threshold

_{Updated for commit f6966f9}