feat(analytics): export usage data

[awsl233777]

Summary

Extracts the analytics export implementation for #139 from the broader desktop/analytics PR #172 into a focused standalone PR.

Changes:

• Adds analytics export argument parsing for CSV/JSON, date range, model, and output path options.
• Adds /analytics export handling in the CLI.
• Adds session usage export generation for CSV and JSON, including empty-data behavior.
• Adds unit coverage for export argument parsing and backend export output.

Closes #139

Validation

• npm run test:unit -- --match analytics — passed; test runner reported all 535 unit tests passed.

Scope note

This PR intentionally excludes the unrelated desktop/Tauri packaging changes from #172.

Summary by CodeRabbit

• New Features

  • Session usage analytics can now be exported via CLI command with support for date range filtering, model selection, and output format options (JSON or CSV).
  • Export results can be written to a specified file or sent to stdout.

• Chores

  • Version bump to 0.0.38.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d90734be-c4ed-4071-becc-9b2c958c6f02

📥 Commits

Reviewing files that changed from the base of the PR and between 4285a6e and 272d28d.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (7)

• cli.js
• cli/analytics-export-args.js
• cli/session-usage.js
• package.json
• tests/unit/analytics-export-args.test.mjs
• tests/unit/run.mjs
• tests/unit/session-usage-backend.test.mjs

---

📝 Walkthrough

Walkthrough

Adds analytics export feature allowing users to export session usage data (token counts, session aggregates) as CSV or JSON, filtered by date range and model type. Includes argument parsing, export aggregation and serialization logic, CLI command codexmate analytics export, and API endpoint /api?action=export-sessions-usage with comprehensive unit test coverage.

Changes

Analytics Usage Export

Layer / File(s)	Summary
Analytics Export Argument Parser cli/analytics-export-args.js, tests/unit/analytics-export-args.test.mjs, tests/unit/run.mjs	New parseAnalyticsExportArgs function parses and validates CLI flags (--format, --source, --from, --to, --model, --output/-o, --force-refresh, --help), accumulating unknown-argument and validation errors into a semicolon-delimited error string. Unit tests verify correct option extraction, error reporting, and test runner registration.
Session Usage Export Core and Aggregation cli/session-usage.js, tests/unit/session-usage-backend.test.mjs	New utility functions parse/normalize export inputs (dates with YYYY-MM-DD and boundary support, format selection, model filters with comma-separated and case-insensitive parsing). buildUsageExportRows filters sessions by date range and model, groups by (day, model), accumulates token totals and session counts. exportSessionUsageCore orchestrates session fetching, row building, and serialization to CSV (with cell escaping) or JSON. Unit tests validate CSV/JSON output correctness and empty-data handling.
CLI Command and API Endpoint Integration cli.js, package.json	cmdAnalytics command handler parses export arguments, invokes exportSessionUsage, and writes output to file or stdout. New API endpoint export-sessions-usage validates source parameter and returns export results. Help text documents codexmate analytics export ... and main command router routes analytics subcommand to cmdAnalytics. Version bumped to 0.0.38.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• ymkiux

Poem

🐰 Data exports hop along the way,
CSV rows and JSON's play,
Token tallies grouped by day and mind,
Analytics trails for all to find! 🌟

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/analytics-export-issue-139

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}