feat(observability): optional error reporting to GlitchTip via Sentry

[OGtwelve]

Summary

Opt-in error reporting (issue #70). @sentry/node is an optional dependency, dynamically imported only when a DSN is configured — so the default path, and runtimes without the SDK (e.g. Deno), load nothing and pay nothing.

Changes

• src/observability/error-reporter.ts — dsnFromEnv (AITM_SENTRY_DSN > SENTRY_DSN, blank = unset) + initErrorReporter (dynamic @sentry/node, no-op fallback on missing SDK / init failure).
• src/cli/cli.ts — entrypoint captures + flushes an uncaught crash before exit.
• packages/aitm/package.json — @sentry/node in optionalDependencies.
• docs/observability.md — env vars + behaviour.

Testing

• src/observability/error-reporter.test.ts: DSN precedence/blank handling; no-DSN → safe no-op (never throws, never loads the SDK). Full suite green (675); build, biome, tsc clean.

Note

Live verification (an error landing in the GlitchTip project) is gated on the project + DSN from infrastructure#478.

Refs #70

Summary by CodeRabbit

• New Features

  • Added optional error reporting for uncaught CLI failures when a DSN is configured.
  • The app now supports sending error events to supported monitoring services, with safe fallback when not enabled.

• Bug Fixes

  • Improved CLI exit handling so reported errors are flushed before the process exits.
  • Missing or invalid monitoring configuration now degrades gracefully without interrupting normal execution.

• Documentation

  • Added usage notes for enabling observability and configuring environment variables.

• Tests

  • Added coverage for DSN selection and no-op behavior when reporting is disabled.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 44 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: f0a2f12d-bc7e-4a2c-a907-92a1aec0d4fa

📥 Commits

Reviewing files that changed from the base of the PR and between fb9a2ba and d1ba68d.

📒 Files selected for processing (1)

• packages/aitm/src/observability/error-reporter.ts

📝 Walkthrough

Walkthrough

Adds an optional Sentry/GlitchTip error reporting module (ErrorReporter interface, dsnFromEnv, initErrorReporter) that dynamically imports @sentry/node only when a DSN is configured, falling back silently to a no-op. The CLI entrypoint is reworked to initialize and flush the reporter around main(). Tests, optional dependency, and docs are included.

Changes

Optional Sentry Error Reporting

Layer / File(s)	Summary
ErrorReporter interface and initErrorReporter packages/aitm/src/observability/error-reporter.ts, packages/aitm/package.json	Exports ErrorReporter type, NOOP_REPORTER, dsnFromEnv (with AITM_SENTRY_DSN over SENTRY_DSN precedence and blank-as-unset handling), and initErrorReporter which dynamically imports @sentry/node when a DSN is present (tracing disabled), falling back to no-op on any failure. @sentry/node ^10.62.0 added as an optional dependency.
CLI entrypoint wiring packages/aitm/src/cli/cli.ts	Replaces .then(..., ...) flow with an async IIFE that initializes the reporter, runs main() in a try/catch, captures exceptions via the reporter, flushes before every process.exit.
Tests and docs packages/aitm/src/observability/error-reporter.test.ts, packages/aitm/docs/observability.md	Unit tests cover dsnFromEnv precedence/fallback/blank and initErrorReporter no-op safety. Docs describe DSN opt-in, env var precedence, dynamic import behavior, and exit-code neutrality.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: opt-in error reporting to GlitchTip via Sentry.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 30.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/error-reporting-70

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/aitm/docs/observability.md`:
- Line 26: The observability docs currently promise that reporting never affects
exit code, but the CLI path in cli.ts still awaits reporter.flush() on both
exits without handling rejections. Either update the wording in observability.md
to narrow the guarantee, or harden the cli.ts exit flow so reporter failures are
caught and ignored before process termination, keeping the promise accurate.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 68935e85-9fe2-4bce-a89d-5e6a18abe657

📥 Commits

Reviewing files that changed from the base of the PR and between 7140325 and fb9a2ba.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• packages/aitm/docs/observability.md
• packages/aitm/package.json
• packages/aitm/src/cli/cli.ts
• packages/aitm/src/observability/error-reporter.test.ts
• packages/aitm/src/observability/error-reporter.ts

[OGtwelve]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.