feat: CLI reports command group
Summary
Add postgresai reports CLI commands and MCP tools for retrieving checkup reports.
CLI Commands
reports list [options]
List checkup reports with filtering and pagination.
postgresai reports list
postgresai reports list --project-id 10 --status completed --limit 5
postgresai reports list --before 2026-01-15 # filter by date (YYYY-MM-DD)
postgresai reports list --before "15.01.2026" # DD.MM.YYYY also supported
postgresai reports list --before "15.01.2026 10:30" # with time
postgresai reports list --all # fetch all reports| Option | Description |
|---|---|
--project-id <id> |
Filter by project ID |
--status <status> |
Filter by status (e.g., completed) |
--limit <n> |
Max reports to return (default: 20) |
--before <date> |
Show reports created before this date |
--all |
Fetch all reports (paginated automatically, capped at 10,000) |
--json |
JSON output |
--debug |
Enable debug output |
Supported date formats for --before:
| Format | Example |
|---|---|
YYYY-MM-DD |
2025-01-15 |
YYYY-MM-DD HH:mm |
2025-01-15 10:30 |
YYYY-MM-DDTHH:mm:ss |
2025-01-15T10:30:00 |
DD.MM.YYYY |
15.01.2025 |
DD.MM.YYYY HH:mm |
15.01.2025 10:30 |
DD.MM.YYYY HH:mm:ss |
15.01.2025 10:30:45 |
All dates are treated as UTC. --all and --before cannot be used together.
reports files [reportId] [options]
List files in a checkup report (metadata only, no content).
postgresai reports files 958
postgresai reports files 958 --type md --check-id H002
postgresai reports files --check-id H002 # across all reports| Option | Description |
|---|---|
--type <type> |
Filter by file type: json, md
|
--check-id <id> |
Filter by check ID (e.g., H002, F004) |
--json |
JSON output |
--debug |
Enable debug output |
reports data [reportId] [options]
Get checkup report file content (includes actual data).
postgresai reports data 958 # markdown output (default)
postgresai reports data 958 --type json # json data
postgresai reports data 958 --check-id H002 --json # full JSON output (all types)
postgresai reports data 958 -o ./reports # save all files to directory
postgresai reports data --check-id H002 -o ./reports # save across all reports
postgresai reports data 958 --formatted # ANSI styled (experimental)| Option | Description |
|---|---|
--type <type> |
Filter by file type: json, md
|
--check-id <id> |
Filter by check ID (e.g., H002) |
-o, --output <dir> |
Save files to directory (uses original filenames) |
--formatted |
Render markdown with ANSI styling (experimental) |
--json |
Full JSON output |
--debug |
Enable debug output |
Default output behavior: Terminal output defaults to type=md (human-readable markdown). --json and --output modes fetch all file types unless --type is explicitly specified.
MCP Tools
| Tool | Description |
|---|---|
list_reports |
List checkup reports with date filter (before_date) and all mode |
list_report_files |
List files in a report (metadata only) |
get_report_data |
Get report file content (markdown or JSON) |
All tools support report_id, check_id, type filters. Either report_id or check_id must be provided for list_report_files and get_report_data.
before_date in MCP accepts the same flexible date formats as the CLI --before option.
Security
-
--outputusespath.basename()to prevent path traversal from API-returned filenames
Test Coverage
- reports.ts: 100% functions, 100% lines
- 59 unit tests (lib + parseFlexibleDate), 29 CLI integration tests, 12 MCP tests
- 500 total tests pass, 0 failures
Closes #131 (closed)