feat(error-tracking): add GlitchTip integration with shared error-tracking package

Infrastructure:
- Add GlitchTip (web + worker) to docker-compose.macmini.yml (port 8020)
- Add glitchtip.mana.how to Cloudflare Tunnel config
- Add glitchtip database to init-db SQL
- Add GLITCHTIP_DSN to .env.development

Shared Package (@manacore/shared-error-tracking):
- initErrorTracking() - Sentry-compatible init with GlitchTip DSN
- captureException(), captureMessage(), setUser(), setTag(), flush()
- SentryExceptionFilter for NestJS (captures 5xx errors only)
- Graceful no-op when DSN is not configured

Integration:
- Add instrument.ts to calendar, contacts, todo backends
- Import instrument.ts before app bootstrap in all 3 main.ts files
- Error tracking auto-initializes when GLITCHTIP_DSN env var is set

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.env.development

@@ -12,6 +12,11 @@
 # SHARED - Used across multiple apps
 # ============================================
 
+# GlitchTip Error Tracking (self-hosted Sentry-compatible)
+# Set DSN after creating projects in GlitchTip admin
+# Format: https://<key>@glitchtip.mana.how/<project-id>
+GLITCHTIP_DSN=
+
 # Mana Core Auth Service
 MANA_CORE_AUTH_URL=http://localhost:3001
 # Service key for bot-to-auth communication (Matrix-SSO-Link)

apps/calendar/apps/backend/package.json

@@ -24,6 +24,7 @@
 		"@calendar/shared": "workspace:*",
 		"@manacore/credit-operations": "workspace:*",
 		"@manacore/nestjs-integration": "workspace:*",
+		"@manacore/shared-error-tracking": "workspace:^",
 		"@manacore/shared-nestjs-auth": "workspace:*",
 		"@manacore/shared-nestjs-health": "workspace:*",
 		"@manacore/shared-nestjs-metrics": "workspace:*",

apps/calendar/apps/backend/src/instrument.ts

@@ -0,0 +1,8 @@
+import { initErrorTracking } from '@manacore/shared-error-tracking';
+
+initErrorTracking({
+	serviceName: 'calendar-backend',
+	environment: process.env.NODE_ENV,
+	release: process.env.APP_VERSION,
+	debug: process.env.NODE_ENV === 'development',
+});

apps/calendar/apps/backend/src/main.ts

@@ -1,3 +1,4 @@
+import './instrument';
 import { bootstrapApp } from '@manacore/shared-nestjs-setup';
 import { AppModule } from './app.module';
 

apps/contacts/apps/backend/package.json

@@ -21,6 +21,7 @@
 		"test:cov": "jest --coverage"
 	},
 	"dependencies": {
+		"@manacore/shared-error-tracking": "workspace:^",
 		"@manacore/shared-nestjs-auth": "workspace:*",
 		"@manacore/shared-nestjs-health": "workspace:*",
 		"@manacore/shared-nestjs-metrics": "workspace:*",

apps/contacts/apps/backend/src/instrument.ts

@@ -0,0 +1,8 @@
+import { initErrorTracking } from '@manacore/shared-error-tracking';
+
+initErrorTracking({
+	serviceName: 'contacts-backend',
+	environment: process.env.NODE_ENV,
+	release: process.env.APP_VERSION,
+	debug: process.env.NODE_ENV === 'development',
+});

apps/contacts/apps/backend/src/main.ts

@@ -1,3 +1,4 @@
+import './instrument';
 import { bootstrapApp } from '@manacore/shared-nestjs-setup';
 import { AppModule } from './app.module';
 

apps/todo/apps/backend/package.json

@@ -20,6 +20,7 @@
 	"dependencies": {
 		"@manacore/credit-operations": "workspace:*",
 		"@manacore/nestjs-integration": "workspace:*",
+		"@manacore/shared-error-tracking": "workspace:^",
 		"@manacore/shared-nestjs-auth": "workspace:*",
 		"@manacore/shared-nestjs-health": "workspace:*",
 		"@manacore/shared-nestjs-metrics": "workspace:*",

apps/todo/apps/backend/src/instrument.ts

@@ -0,0 +1,8 @@
+import { initErrorTracking } from '@manacore/shared-error-tracking';
+
+initErrorTracking({
+	serviceName: 'todo-backend',
+	environment: process.env.NODE_ENV,
+	release: process.env.APP_VERSION,
+	debug: process.env.NODE_ENV === 'development',
+});

apps/todo/apps/backend/src/main.ts

@@ -1,3 +1,4 @@
+import './instrument';
 import { bootstrapApp } from '@manacore/shared-nestjs-setup';
 import { AppModule } from './app.module';
 

docker/init-db/01-create-databases.sql

@@ -2,6 +2,7 @@
 -- This script runs on first container initialization
 
 -- Core databases
+CREATE DATABASE IF NOT EXISTS glitchtip;
 CREATE DATABASE IF NOT EXISTS chat;
 CREATE DATABASE IF NOT EXISTS zitare;
 CREATE DATABASE IF NOT EXISTS contacts;
@@ -36,4 +37,5 @@ GRANT ALL PRIVILEGES ON DATABASE techbase TO manacore;
 GRANT ALL PRIVILEGES ON DATABASE voxel_lava TO manacore;
 GRANT ALL PRIVILEGES ON DATABASE figgos TO manacore;
 GRANT ALL PRIVILEGES ON DATABASE context TO manacore;
+GRANT ALL PRIVILEGES ON DATABASE glitchtip TO manacore;
 GRANT ALL PRIVILEGES ON DATABASE manacore TO manacore;

packages/shared-error-tracking/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@manacore/shared-error-tracking",
+	"version": "1.0.0",
+	"description": "Error tracking integration for ManaCore apps (GlitchTip/Sentry-compatible)",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./nestjs": {
+			"types": "./dist/nestjs.d.ts",
+			"default": "./dist/nestjs.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc",
+		"type-check": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@sentry/node": "^9.0.0"
+	},
+	"peerDependencies": {
+		"@nestjs/common": "^10.0.0 || ^11.0.0",
+		"@nestjs/core": "^10.0.0 || ^11.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@nestjs/common": {
+			"optional": true
+		},
+		"@nestjs/core": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@nestjs/common": "^10.0.0",
+		"@nestjs/core": "^10.0.0",
+		"@types/node": "^22.10.2",
+		"typescript": "^5.0.0"
+	}
+}

packages/shared-error-tracking/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared Error Tracking for ManaCore Apps
+ *
+ * Uses Sentry SDK with GlitchTip as the self-hosted backend.
+ * Compatible with any Sentry-compatible error tracking service.
+ *
+ * @example
+ * ```typescript
+ * // In instrument.ts (must be imported BEFORE app bootstrap)
+ * import { initErrorTracking } from '@manacore/shared-error-tracking';
+ *
+ * initErrorTracking({
+ *   serviceName: 'calendar-backend',
+ *   dsn: process.env.GLITCHTIP_DSN,
+ *   environment: process.env.NODE_ENV,
+ *   release: process.env.APP_VERSION,
+ * });
+ * ```
+ */
+
+import * as Sentry from '@sentry/node';
+
+export interface ErrorTrackingOptions {
+	/** Service/app name (e.g. 'calendar-backend', 'contacts-web') */
+	serviceName: string;
+	/** GlitchTip/Sentry DSN. If not set, error tracking is disabled. */
+	dsn?: string;
+	/** Environment (development, staging, production) */
+	environment?: string;
+	/** Release/version string */
+	release?: string;
+	/** Sample rate for error events (0.0 to 1.0, default: 1.0) */
+	sampleRate?: number;
+	/** Sample rate for performance traces (0.0 to 1.0, default: 0.1) */
+	tracesSampleRate?: number;
+	/** Enable debug mode (default: false) */
+	debug?: boolean;
+}
+
+let initialized = false;
+
+/**
+ * Initialize error tracking. Call this BEFORE bootstrapping your app.
+ * If no DSN is provided, error tracking is silently disabled.
+ */
+export function initErrorTracking(options: ErrorTrackingOptions): void {
+	if (initialized) return;
+
+	const dsn = options.dsn || process.env.GLITCHTIP_DSN || process.env.SENTRY_DSN;
+
+	if (!dsn) {
+		if (options.debug) {
+			console.log(`[ErrorTracking] No DSN configured for ${options.serviceName} - disabled`);
+		}
+		return;
+	}
+
+	Sentry.init({
+		dsn,
+		environment: options.environment || process.env.NODE_ENV || 'development',
+		release: options.release || process.env.APP_VERSION,
+		serverName: options.serviceName,
+		sampleRate: options.sampleRate ?? 1.0,
+		tracesSampleRate: options.tracesSampleRate ?? 0.1,
+		debug: options.debug ?? false,
+	});
+
+	initialized = true;
+
+	console.log(
+		`[ErrorTracking] Initialized for ${options.serviceName} (${options.environment || 'development'})`
+	);
+}
+
+/**
+ * Capture an exception manually
+ */
+export function captureException(error: unknown, context?: Record<string, unknown>): void {
+	if (!initialized) return;
+	Sentry.captureException(error, { extra: context });
+}
+
+/**
+ * Capture a message
+ */
+export function captureMessage(
+	message: string,
+	level: 'fatal' | 'error' | 'warning' | 'info' | 'debug' = 'info'
+): void {
+	if (!initialized) return;
+	Sentry.captureMessage(message, level);
+}
+
+/**
+ * Set user context for error reports
+ */
+export function setUser(user: { id: string; email?: string } | null): void {
+	if (!initialized) return;
+	Sentry.setUser(user);
+}
+
+/**
+ * Set extra context tags
+ */
+export function setTag(key: string, value: string): void {
+	if (!initialized) return;
+	Sentry.setTag(key, value);
+}
+
+/**
+ * Flush pending events (call before process exit)
+ */
+export async function flush(timeout = 2000): Promise<void> {
+	if (!initialized) return;
+	await Sentry.flush(timeout);
+}
+
+export { Sentry };

packages/shared-error-tracking/src/nestjs.ts

@@ -0,0 +1,93 @@
+/**
+ * NestJS-specific error tracking integration
+ *
+ * Provides an exception filter that automatically captures errors
+ * and a middleware that sets user context from JWT.
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * import { SentryExceptionFilter } from '@manacore/shared-error-tracking/nestjs';
+ *
+ * @Module({
+ *   providers: [
+ *     { provide: APP_FILTER, useClass: SentryExceptionFilter },
+ *   ],
+ * })
+ * ```
+ */
+
+import {
+	type ExceptionFilter,
+	Catch,
+	type ArgumentsHost,
+	HttpException,
+	HttpStatus,
+	Logger,
+} from '@nestjs/common';
+import { captureException, setUser } from './index';
+
+/**
+ * NestJS exception filter that captures errors to GlitchTip/Sentry.
+ * Use alongside your existing HttpExceptionFilter or as a replacement.
+ */
+@Catch()
+export class SentryExceptionFilter implements ExceptionFilter {
+	private readonly logger = new Logger(SentryExceptionFilter.name);
+
+	catch(exception: unknown, host: ArgumentsHost) {
+		const ctx = host.switchToHttp();
+		const request = ctx.getRequest();
+		const response = ctx.getResponse();
+
+		let status = HttpStatus.INTERNAL_SERVER_ERROR;
+		let message = 'Internal server error';
+
+		if (exception instanceof HttpException) {
+			status = exception.getStatus();
+			const exceptionResponse = exception.getResponse();
+			message =
+				typeof exceptionResponse === 'string'
+					? exceptionResponse
+					: (exceptionResponse as Record<string, unknown>).message?.toString() || message;
+		}
+
+		// Only capture 5xx errors to GlitchTip (not 4xx client errors)
+		if (status >= 500) {
+			captureException(exception, {
+				url: request.url,
+				method: request.method,
+				statusCode: status,
+				userId: request.user?.userId || request.user?.sub,
+			});
+			this.logger.error(
+				`[${request.method}] ${request.url} - ${status}: ${message}`,
+				exception instanceof Error ? exception.stack : undefined
+			);
+		} else {
+			this.logger.warn(`[${request.method}] ${request.url} - ${status}: ${message}`);
+		}
+
+		response.status(status).json({
+			statusCode: status,
+			message,
+			timestamp: new Date().toISOString(),
+			path: request.url,
+		});
+	}
+}
+
+/**
+ * Set Sentry user context from a NestJS request.
+ * Call this in a middleware or interceptor after JWT validation.
+ */
+export function setUserFromRequest(request: {
+	user?: { userId?: string; sub?: string; email?: string };
+}): void {
+	if (request.user) {
+		setUser({
+			id: request.user.userId || request.user.sub || 'unknown',
+			email: request.user.email,
+		});
+	}
+}

packages/shared-error-tracking/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ES2021",
+		"module": "commonjs",
+		"moduleResolution": "node",
+		"declaration": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}