feat(reports): scheduled analytics reports with trend snapshots (#7)

[LeoLin990405]

Summary

Implements Scheduled Analytics Reports (issue #7): recurring HTML/JSON reports over a configured time window, generated on a schedule, with a run history of downloadable artifacts. Trend numbers reuse the same computations as the in-app Analytics page (windowed), so they're consistent by construction. Zero new dependencies. Closes #7.

Changes

Backend (/api/reports)

• Report definitions (template, frequency, hour, timezone, formats, window) and run logs persisted in two additive tables; both survive Clear Data like alert_rules.
• Generator reuses the /api/analytics computations, windowed to the report period — session volume trend, daily events, agent status distribution, top tools + failure-prone operations, token usage + cost (via calculateCost). Window bounds are half-open [start, end) with the same tz_offset modifier convention as analytics.
• Formats — HTML + JSON server-side. The HTML artifact is a self-contained, print-friendly document (inline @media print), so Save-as-PDF works from the browser with no headless-Chrome dependency (I flagged this in the issue — happy to wire a real server-side PDF lib if you'd prefer the dep). Every dynamic value in the HTML is escaped.
• Scheduler — an unref'd, env-gated (DASHBOARD_REPORTS_DISABLED) next_run_at-driven tick that runs due definitions, persists each run, advances the schedule on success and error (a failing def can't wedge the tick), and broadcasts report_run. A failed generation becomes an error-status run with an actionable error string — never an unhandled throw.
• Frequency presets (daily / weekly+day / monthly + hour) instead of raw cron — covers the weekly/monthly-review use case without a cron-parser dep (flagged in the issue).
• Run-now + artifact-download endpoints (correct Content-Type, 404 for an ungenerated format). All queries parameterized; window_days bounded so an out-of-range value degrades to an error run instead of a RangeError.

Frontend

• Reports page: definition list (human schedule, next run, enabled toggle, last status), create/edit modal, Run now, and per-definition run history with status/error + View HTML (new tab → print-to-PDF) / Download JSON. Full en/zh/vi i18n.

Type of Change

• Bug fix
• New feature (non-breaking change that adds functionality)
• Breaking change
• Refactor
• Documentation update
• Infrastructure / CI / DevOps
• Dependency update

How to Test

1. npm run test:server — all pass (364), incl. server/__tests__/reports.test.js (20 tests: CRUD/validation, computeNextRun determinism, windowed-number consistency with analytics, run + artifact download, error-run capture, HTML escaping).
2. cd client && npm run build — clean tsc -b && vite build.
3. Manual: npm run dev → Reports in the sidebar → New report (pick a template + frequency + formats) → Run now → expand history → View HTML (opens the print-friendly artifact in a new tab; ⌘P → Save as PDF) / Download JSON.
4. Scheduling: the tick is next_run_at-driven and unref'd; set DASHBOARD_REPORTS_DISABLED=1 to turn it off.

Acceptance criteria

• Create and schedule recurring reports
• Reports generated for configured time windows reliably (windowed [start,end), explicit tz)
• Artifacts downloadable from UI and API (/api/reports/runs/:id/artifact?format=html|json)
• Failed runs include actionable error logs (error-status run + message; never crashes the tick)
• Trend calculations consistent with in-app analytics charts (same queries, windowed) — asserted by a consistency test

Checklist

• Read the contributing guidelines
• Code follows the project's standards
• Added tests proving the feature works
• All new and existing tests pass (npm test) — see note
• Code formatted (npm run format:check)
• Updated docs where necessary (self-describing /templates endpoint + i18n)

Two scope calls I flagged in the issue and want your nod on: (1) PDF is delivered as print-friendly HTML rather than a server-rendered binary (avoids a heavyweight headless-browser dep on a local-first tool); (2) frequency presets instead of raw cron expressions. Both are easy to extend if you'd prefer the heavier route.

Test note: npm run test:server is green (364/364) and cd client && npm run build is clean. No screen-snapshot baseline changed (Reports is a new page; existing pages untouched). npm run test:client otherwise shows only the pre-existing Dashboard/Tabby failures that reproduce on a clean master under Node 26 (jsdom 27 localStorage) — unrelated; CI runs Node 22 where the client suite passes.

[gemini-code-assist]

Code Review

This pull request introduces a new feature for scheduled analytics reports, including database schema updates, an Express router for managing report definitions and runs, a background scheduler, and a frontend management UI. The implementation includes robust error handling for report generation and artifact management. My review identified a high-severity input validation issue regarding timezone offsets, a missing foreign key constraint for referential integrity, and a need for database transactions during deletion to ensure atomicity.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The tz_offset parameter lacks range validation. If an extremely large integer is passed (e.g., via direct API request), computeNextRun will throw a RangeError when creating a new Date object. Because computeNextRun is called outside the try/catch block in runReportForDefinition, this will throw an unhandled error, preventing touchAfterRun from advancing the schedule. Consequently, the scheduler will repeatedly attempt to run the same failing definition on every tick, causing an infinite loop of failures. Adding a reasonable range check (e.g., between -1440 and 1440 minutes) prevents this.

Suggested change

	if (!Number.isInteger(tz_offset)) {
	return { ok: false, error: "tz_offset must be an integer (minutes from UTC)" };
	}
	if (!Number.isInteger(tz_offset) || tz_offset < -1440 || tz_offset > 1440) {
	return { ok: false, error: "tz_offset must be an integer between -1440 and 1440" };
	}

[gemini-code-assist]

The report_runs table references report_definitions(id) via definition_id but does not define a foreign key constraint. Adding a foreign key constraint with ON DELETE CASCADE ensures referential integrity at the database level and automatically cleans up associated runs when a definition is deleted.

Suggested change

	created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
	);
	created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
	FOREIGN KEY (definition_id) REFERENCES report_definitions(id) ON DELETE CASCADE
	);

[gemini-code-assist]

Deleting a report definition involves executing two separate delete queries (deleting associated runs and then deleting the definition itself). These queries should be wrapped in a database transaction to ensure atomicity and prevent orphaned records if one of the operations fails.

    db.transaction(() => {
      stmts.deleteRunsForDef.run(req.params.id);
      stmts.deleteDef.run(req.params.id);
    })();
    res.json({ ok: true });