feat(telemetry): add withTracing helper to reduce Sentry span boilerplate

[BYK]

Summary

Adds generic tracing helpers and automatic database query instrumentation to reduce boilerplate and improve observability.

Part 1: Generic Tracing Helpers

New helpers in src/lib/telemetry.ts:

• withTracing(name, op, fn, attrs?) - Simple async wrapper with automatic status setting
• withTracingSpan(name, op, fn, attrs?) - Passes span to callback for dynamic attributes; won't override manually-set status
• withFsSpan(operation, fn) - File system operations wrapper

Refactored:

• code-scanner.ts: scanDirectory now uses withTracingSpan
• project-root.ts: Removed duplicate withFsSpan, uses shared helper
• withHttpSpan now uses withTracing internally

Part 2: Automatic Database Query Tracing

Problem: The previous withDbSpan required manually passing SQL query strings, which could diverge from actual queries and created code bloat.

Solution: Wrap the SQLite Database with a Proxy that automatically traces all queries:

• createTracedDatabase(db) - Wraps Database, intercepts query() method
• createTracedStatement(stmt, sql) - Wraps Statement, traces get/run/all/values calls
• SQL is captured directly from db.query(sql) - single source of truth, can't diverge
• Sets both span name and db.statement attribute for Sentry Queries feature

Changes:

• db/index.ts: getDatabase() now returns a traced database
• withDbSpan simplified to just group logical operations (op: db.operation)
• Removed manual query strings from auth.ts

Before (manual, error-prone)

withDbSpan("getAuthToken", () => {
  return db.query("SELECT * FROM auth WHERE id = 1").get();
}, "SELECT * FROM auth WHERE id = ?");  // Can diverge!

After (automatic)

withDbSpan("getAuthToken", () => {
  return db.query("SELECT * FROM auth WHERE id = 1").get();
  // ↑ Automatically creates child span with db.statement
});

Span Hierarchy

getAuthToken                           (op: db.operation)
└── SELECT * FROM auth WHERE id = 1    (op: db, db.statement attribute set)

Closes #165

^{Cursor Bugbot reviewed your changes and found no issues for commit bad9778}

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

New Features ✨

• (dsn) Add project root detection for automatic DSN discovery by BYK in #159
• (issue) Replace --org/--project flags with /ID syntax by BYK in #161

• (telemetry) Add withTracing helper to reduce Sentry span boilerplate by BYK in #172

Bug Fixes 🐛

• (types) Align schema types with Sentry API by betegon in #169
• Added nullable in substatus's zod validation by MathurAditya724 in #157

Other

• test: add model-based and property-based testing with fast-check by BYK in #166

---

_{🤖 This preview updates automatically when you update the PR.}

[github-actions]

Codecov Results 📊

✅ Patch coverage is 99.13%. Project has 2183 uncovered lines.
✅ Project coverage is 70.69%. Comparing base (base) to head (head).

Files with missing lines (34)

File	Patch %	Lines
human.ts	31.80%	⚠️ 684 Missing
resolve-target.ts	10.74%	⚠️ 291 Missing
oauth.ts	25.10%	⚠️ 194 Missing
upgrade.ts	39.76%	⚠️ 153 Missing
api-client.ts	74.21%	⚠️ 138 Missing
resolver.ts	3.23%	⚠️ 120 Missing
errors.ts	5.94%	⚠️ 95 Missing
migration.ts	47.44%	⚠️ 82 Missing
version-check.ts	34.04%	⚠️ 62 Missing
telemetry.ts	77.43%	⚠️ 51 Missing
api.ts	89.80%	⚠️ 47 Missing
seer.ts	75.54%	⚠️ 45 Missing
preload.ts	38.71%	⚠️ 38 Missing
seer.ts	79.87%	⚠️ 30 Missing
schema.ts	52.73%	⚠️ 26 Missing
utils.ts	87.43%	⚠️ 24 Missing
detector.ts	90.10%	⚠️ 20 Missing
code-scanner.ts	95.00%	⚠️ 16 Missing
fs-utils.ts	57.14%	⚠️ 9 Missing
project-root.ts	97.37%	⚠️ 9 Missing
auth.ts	94.78%	⚠️ 7 Missing
dsn-cache.ts	96.71%	⚠️ 7 Missing
feedback.ts	84.21%	⚠️ 6 Missing
arg-parsing.ts	93.41%	⚠️ 6 Missing
upgrade.ts	93.83%	⚠️ 5 Missing
colors.ts	91.84%	⚠️ 4 Missing
env-file.ts	97.58%	⚠️ 3 Missing
sentry-urls.ts	88.00%	⚠️ 3 Missing
project-aliases.ts	97.40%	⚠️ 2 Missing
project-root-cache.ts	96.92%	⚠️ 2 Missing
alias.ts	99.28%	⚠️ 1 Missing
parser.ts	98.63%	⚠️ 1 Missing
helpers.ts	94.74%	⚠️ 1 Missing
helpers.ts	94.74%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    70.49%    70.69%     +0.2%
==========================================
  Files           54        54         —
  Lines         7400      7448       +48
  Branches         0         0         —
==========================================
+ Hits          5216      5265       +49
- Misses        2184      2183        -1
- Partials         0         0         —

---

Generated by Codecov Action

[BYK]

Regarding the Bugbot comment about error handling in code-scanner.ts:

This catch block behavior is pre-existing from PR #159 (commit 67bc20f) that added DSN discovery. The design intentionally returns an empty result rather than throwing because:

1. DSN scanning is a best-effort feature - failure shouldn't block CLI operation
2. The span status is set to error (code: 2) for observability
3. Callers handle empty results gracefully

This PR only refactored from Sentry.startSpan() to withTracingSpan() - the error handling logic was not changed.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}