@aurostack/stacks 0.1.1 → 0.2.1

package/templates/react-monorepo/files/apps/landing/src/main.tsx

@@ -1,10 +1,14 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { initTelemetry } from '@acme/telemetry'; // @feature telemetry
+import { API_URL, TELEMETRY } from './lib/env'; // @feature telemetry
 import { RouterProvider } from 'react-router';
 import '@acme/ui/globals.css';
 import { Providers } from './app/providers';
 import { router } from './app/router';
 
+initTelemetry({ service: 'acme-landing', ...TELEMETRY, apiUrls: [API_URL] }); // @feature telemetry
+
 createRoot(document.getElementById('root')!).render(
 	<StrictMode>
 		<Providers>

package/templates/react-monorepo/files/build.sh

@@ -46,7 +46,9 @@ read_var() {
 }
 
 BUILD_ARGS="--build-arg APP=$APP"
-for VAR in VITE_APP_API_URL VITE_APP_AUTH_HOST VITE_APP_CLIENT_HOST VITE_APP_ADMIN_HOST VITE_APP_LANDING VITE_APP_SUPPORT_EMAIL; do
+VARS="VITE_APP_API_URL VITE_APP_AUTH_HOST VITE_APP_CLIENT_HOST VITE_APP_ADMIN_HOST VITE_APP_LANDING VITE_APP_SUPPORT_EMAIL VITE_APP_SITE_URL"
+VARS="$VARS VITE_OPENOBSERVE_URL VITE_OPENOBSERVE_ORG VITE_OPENOBSERVE_CLIENT_TOKEN" # @feature telemetry
+for VAR in $VARS; do
 	VALUE="$(read_var "$VAR")"
 	[ -n "$VALUE" ] && BUILD_ARGS="$BUILD_ARGS --build-arg $VAR=$VALUE"
 done

package/templates/react-monorepo/files/packages/auth/package.json

@@ -11,6 +11,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@acme/telemetry": "workspace:*",
 		"better-auth": "^1.6.2"
 	},
 	"peerDependencies": {

package/templates/react-monorepo/files/packages/auth/src/provider.tsx

@@ -3,6 +3,7 @@ import { useDispatch } from 'react-redux';
 import { getAuthClient } from './client';
 import { sessionCleared, sessionLoaded, sessionLoading, type AuthUser } from './slice';
 import { AUTH_BROADCAST_CHANNEL } from './logout';
+import { setTelemetryUser } from '@acme/telemetry'; // @feature telemetry
 
 function toAuthUser(user: Record<string, unknown> | null | undefined): AuthUser | null {
 	if (!user) return null;
@@ -33,6 +34,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 		}
 		const user = (session.data?.user as Record<string, unknown> | undefined) ?? null;
 		dispatch(sessionLoaded(toAuthUser(user)));
+		setTelemetryUser(user ? { id: String(user.id) } : null); // @feature telemetry
 	}, [session.isPending, session.data, dispatch]);
 
 	useEffect(() => {

package/templates/react-monorepo/files/packages/layouts/package.json

@@ -11,6 +11,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@acme/telemetry": "workspace:*",
 		"@acme/ui": "workspace:*",
 		"lucide-react": "^1.17.0"
 	},

package/templates/react-monorepo/files/packages/layouts/src/error-boundary.tsx

@@ -1,6 +1,7 @@
 import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Button } from '@acme/ui';
 import { StateScreen } from './states/state-screen';
+import { reportError } from '@acme/telemetry'; // @feature telemetry
 
 type ErrorBoundaryProps = {
 	children: ReactNode;
@@ -21,6 +22,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 
 	componentDidCatch(error: Error, info: ErrorInfo): void {
 		console.error('ErrorBoundary caught an error', error, info);
+		reportError(error, { componentStack: info.componentStack }); // @feature telemetry
 	}
 
 	render(): ReactNode {

package/templates/react-monorepo/files/packages/telemetry/eslint.config.mjs

@@ -0,0 +1,3 @@
+import config from '@acme/config/eslint';
+
+export default config;

package/templates/react-monorepo/files/packages/telemetry/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "@acme/telemetry",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"lint": "eslint .",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@openobserve/browser-logs": "^0.4.3",
+		"@openobserve/browser-rum": "^0.4.3"
+	},
+	"devDependencies": {
+		"@acme/config": "workspace:*"
+	}
+}

package/templates/react-monorepo/files/packages/telemetry/src/index.ts

@@ -0,0 +1,80 @@
+// @acme/telemetry — browser monitoring (RUM) and logs, sent to OpenObserve.
+//
+// Page views, errors, slow resources and user actions, plus console errors as
+// logs. Requests to the app's own API carry a W3C `traceparent` header, so a
+// click links to the backend trace it caused. The SDK finishes starting a
+// moment after init (its session store is async), so the first request or two
+// of a page load (typically the session check) go out without the header.
+// Off until connection settings are passed; everything here is then a no-op.
+import { DefaultPrivacyLevel, openobserveRum } from '@openobserve/browser-rum';
+import { openobserveLogs } from '@openobserve/browser-logs';
+
+export interface TelemetryOptions {
+	/** Service name, e.g. `acme-client` — one per app. */
+	service: string;
+	/** OpenObserve base URL, e.g. `https://o2.example.com`. */
+	url?: string;
+	/** The project's organization identifier. */
+	org?: string;
+	/**
+	 * A RUM client token (Ingestion → RUM). Write-only and built for shipping
+	 * in a bundle — never the backend's ingestion token.
+	 */
+	clientToken?: string;
+	/** `development`, `production`, … — Vite's `import.meta.env.MODE`. */
+	environment?: string;
+	version?: string;
+	/** Backend origin(s) whose requests should carry trace headers. */
+	apiUrls?: string[];
+	/** Share of sessions to record for replay, 0–100. Off by default. */
+	sessionReplaySampleRate?: number;
+}
+
+let started = false;
+
+export function initTelemetry(options: TelemetryOptions): boolean {
+	const { url, org, clientToken } = options;
+	if (started || !url || !org || !clientToken) return false;
+
+	// The SDK takes a bare host (no scheme) plus an explicit plain-HTTP flag.
+	const { host, protocol } = new URL(url);
+	const common = {
+		clientToken,
+		site: host,
+		organizationIdentifier: org,
+		insecureHTTP: protocol === 'http:',
+		service: options.service,
+		env: options.environment,
+		version: options.version
+	};
+
+	openobserveRum.init({
+		...common,
+		applicationId: options.service,
+		sessionSampleRate: 100,
+		sessionReplaySampleRate: options.sessionReplaySampleRate ?? 0,
+		defaultPrivacyLevel: DefaultPrivacyLevel.MASK_USER_INPUT,
+		trackResources: true,
+		trackLongTasks: true,
+		trackUserInteractions: true,
+		allowedTracingUrls: (options.apiUrls ?? []).filter(Boolean).map((match) => ({
+			match,
+			propagatorTypes: ['tracecontext' as const]
+		}))
+	});
+	openobserveLogs.init({ ...common, forwardErrorsToLogs: true });
+	started = true;
+	return true;
+}
+
+/** Report a handled error — e.g. from an error boundary. */
+export function reportError(error: unknown, context?: object): void {
+	if (started) openobserveRum.addError(error, context);
+}
+
+/** Tie the session to a signed-in user (id only), or clear it on logout. */
+export function setTelemetryUser(user: { id: string } | null): void {
+	if (!started) return;
+	if (user) openobserveRum.setUser({ id: user.id });
+	else openobserveRum.clearUser();
+}

package/templates/react-monorepo/files/packages/telemetry/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "@acme/config/tsconfig/react.json",
+	"include": ["src"]
+}

package/templates/react-monorepo/files/packages/types/.bin/secrets.js

@@ -1,5 +1,5 @@
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -52,6 +52,11 @@ const env = normalizeEnv(parseEnvArg());
 const envFile = ENV_FILES[env];
 
 console.log(`Fetching secrets for '${slug}' (${env}) -> ${envFile}...`);
-execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env} > ${envFile}`, {
-	stdio: 'inherit'
+// Export first and write only on success: a shell `>` redirect would empty
+// the existing file before infisical had the chance to fail. execSync throws
+// (and the process exits non-zero) when infisical fails.
+const output = execSync(`infisical export --projectId="${PROJECT_ID}" --path="${secretPath}" --env=${env}`, {
+	stdio: ['inherit', 'pipe', 'inherit']
 });
+writeFileSync(envFile, output);
+console.log(`Wrote ${envFile}`);

package/templates/react-monorepo/files/turbo.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://turbo.build/schema.json",
 	"ui": "tui",
-	"globalDependencies": [".env", "tsconfig.base.json"],
+	"globalDependencies": [".env", "packages/config/tsconfig/base.json"],
 	"tasks": {
 		"build": {
 			"dependsOn": ["^build"],

package/templates/react-monorepo/template.json

@@ -81,6 +81,52 @@
 				"packages/types/**"
 			]
 		},
+		"telemetry": {
+			"title": "Browser monitoring → OpenObserve",
+			"description": "The @acme/telemetry package: OpenObserve RUM and logs in every app — page views, errors (including the error boundary's), slow resources, user actions, the signed-in user id, and traceparent headers on API calls so frontend and backend traces link up. Session replay is off unless a project turns it on. Off at runtime until VITE_OPENOBSERVE_* are set.",
+			"default": true,
+			"files": [
+				"packages/telemetry/**"
+			],
+			"packageJson": [
+				{
+					"file": "apps/admin/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/auth/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/client/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "apps/landing/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "packages/layouts/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				},
+				{
+					"file": "packages/auth/package.json",
+					"dependencies": [
+						"@acme/telemetry"
+					]
+				}
+			]
+		},
 		"app-auth": {
 			"title": "Auth app",
 			"description": "Login, signup, forgot/reset password, email verification. The one app that owns the session; the others redirect here.",
@@ -99,14 +145,14 @@
 		},
 		"app-admin": {
 			"title": "Admin console",
-			"description": "Role-gated internal console over the same data layer.",
+			"description": "Internal console over the same data layer, gated to the admin and superuser roles in the UI. The API must enforce the role on every endpoint it calls.",
 			"files": [
 				"apps/admin/**"
 			]
 		},
 		"app-landing": {
 			"title": "Marketing site",
-			"description": "Public landing site with a prerender step for static routes.",
+			"description": "Public marketing site: a home page, an SEO route table, and build-time robots.txt, sitemap.xml and security.txt.",
 			"files": [
 				"apps/landing/**"
 			]
@@ -127,7 +173,7 @@
 		},
 		"pwa": {
 			"title": "Installable PWA (client app)",
-			"description": "vite-plugin-pwa: app-shell offline caching, auto-update with an update prompt, and a custom install button.",
+			"description": "vite-plugin-pwa configured for the client app: app-shell offline caching, and registerType 'prompt' so a new build waits for the user instead of swapping assets under a running app. The update prompt and install button are yours to build with the plugin's useRegisterSW.",
 			"requires": [
 				"app-client"
 			],
@@ -140,7 +186,7 @@
 		},
 		"charts": {
 			"title": "Charts (client app)",
-			"description": "ApexCharts via react-apexcharts, theme-aware through the shared chart palette.",
+			"description": "ApexCharts and react-apexcharts in the client app, with a theme-aware chart palette (the --chart-* tokens in the UI kit). No chart components ship.",
 			"requires": [
 				"app-client"
 			],
@@ -193,11 +239,43 @@
 				"apps/*/.bin/**",
 				"packages/types/.bin/**"
 			],
-			"packageJson": {
-				"scripts": [
-					"secrets"
-				]
-			}
+			"packageJson": [
+				{
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/admin/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/auth/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/client/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "apps/landing/package.json",
+					"scripts": [
+						"secrets"
+					]
+				},
+				{
+					"file": "packages/types/package.json",
+					"scripts": [
+						"secrets"
+					]
+				}
+			]
 		}
 	},
 	"hooks": [

package/templates/nest-api/files/src/common/controllers/metrics.controller.ts

@@ -1,21 +0,0 @@
-import { Controller, Get, Res } from '@nestjs/common';
-import { ApiExcludeEndpoint, ApiTags } from '@nestjs/swagger';
-import { SkipThrottle } from '@nestjs/throttler'; // @feature rate-limit
-import { AllowAnonymous } from '@thallesp/nestjs-better-auth';
-import { PrometheusController } from '@willsoto/nestjs-prometheus';
-import type { Response } from 'express';
-
-@ApiTags('App')
-@Controller()
-// @feature:start rate-limit
-// Scraped on a fixed interval by Prometheus; already gated by basic auth.
-@SkipThrottle()
-// @feature:end
-export class MetricsController extends PrometheusController {
-	@Get()
-	@ApiExcludeEndpoint()
-	@AllowAnonymous()
-	async index(@Res({ passthrough: true }) response: Response): Promise<string> {
-		return super.index(response);
-	}
-}

package/templates/nest-api/files/src/common/interceptors/index.ts

@@ -1 +0,0 @@
-export * from './metrics.interceptor'; // @feature observability

package/templates/nest-api/files/src/common/interceptors/metrics.interceptor.ts

@@ -1,37 +0,0 @@
-import {
-	Injectable,
-	NestInterceptor,
-	ExecutionContext,
-	CallHandler
-} from '@nestjs/common';
-import { InjectMetric } from '@willsoto/nestjs-prometheus';
-import { Histogram } from 'prom-client';
-import { Observable, tap } from 'rxjs';
-
-@Injectable()
-export class MetricsInterceptor implements NestInterceptor {
-	constructor(
-		@InjectMetric('http_request_duration_seconds')
-		private readonly histogram: Histogram<string>
-	) {}
-
-	intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
-		if (context.getType() !== 'http') {
-			return next.handle();
-		}
-
-		const http = context.switchToHttp();
-		const req = http.getRequest();
-		const res = http.getResponse();
-		const stop = this.histogram.startTimer();
-
-		const observe = () =>
-			stop({
-				method: req.method,
-				route: req.route?.path ?? 'unmatched',
-				status: res.statusCode
-			});
-
-		return next.handle().pipe(tap({ next: observe, error: observe }));
-	}
-}

package/templates/nest-api/files/src/common/modules/metrics.module.ts

@@ -1,28 +0,0 @@
-import { Module } from '@nestjs/common';
-import { APP_INTERCEPTOR } from '@nestjs/core';
-import {
-	makeHistogramProvider,
-	PrometheusModule
-} from '@willsoto/nestjs-prometheus';
-import { MetricsController } from '../controllers';
-import { MetricsInterceptor } from '../interceptors';
-
-@Module({
-	imports: [
-		PrometheusModule.register({
-			defaultLabels: { app: 'acme-api' },
-			defaultMetrics: { enabled: true },
-			controller: MetricsController
-		})
-	],
-	providers: [
-		makeHistogramProvider({
-			name: 'http_request_duration_seconds',
-			help: 'Duration of HTTP requests in seconds',
-			labelNames: ['method', 'route', 'status'],
-			buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5]
-		}),
-		{ provide: APP_INTERCEPTOR, useClass: MetricsInterceptor }
-	]
-})
-export class MetricsModule {}