@getvision/adapter-fastify 0.0.0-develop-20251031183955

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/README.md

@@ -0,0 +1,298 @@
+# @getvision/adapter-fastify
+
+Fastify adapter for Vision Dashboard.
+
+## Installation
+
+```bash
+bun add @getvision/adapter-fastify fastify-type-provider-zod
+# or
+npm install @getvision/adapter-fastify fastify-type-provider-zod
+```
+
+**Note:** `fastify-type-provider-zod` is required for Zod schema validation.
+
+## Quick Start
+
+```typescript
+import Fastify from 'fastify'
+import { visionPlugin, enableAutoDiscovery } from '@getvision/adapter-fastify'
+import { z } from 'zod'
+import { serializerCompiler, validatorCompiler, type ZodTypeProvider } from 'fastify-type-provider-zod'
+
+const app = Fastify()
+
+// Add Zod validator and serializer
+app.setValidatorCompiler(validatorCompiler)
+app.setSerializerCompiler(serializerCompiler)
+
+// Register Vision plugin (development only)
+if (process.env.NODE_ENV === 'development') {
+  await app.register(visionPlugin, { port: 9500 })
+}
+
+// Routes
+app.get('/users', async (request, reply) => {
+  return { users: [] }
+})
+
+// Zod validation with Fastify type provider
+const CreateUserSchema = z.object({
+  name: z.string().min(1).describe('Full name'),
+  email: z.string().email().describe('Email'),
+  age: z.number().int().positive().optional().describe('Age (optional)'),
+})
+
+app.withTypeProvider<ZodTypeProvider>().post('/users', {
+  schema: {
+    body: CreateUserSchema
+  }
+}, async (request, reply) => {
+  return { id: 1, ...request.body }
+})
+
+// Enable auto-discovery after routes
+if (process.env.NODE_ENV === 'development') {
+  enableAutoDiscovery(app)
+}
+
+await app.listen({ port: 3000 })
+```
+
+Visit `http://localhost:9500` to see the dashboard! 🎉
+
+## Features
+
+### Automatic Request Tracing
+Every request is automatically traced with:
+- HTTP method, path, query params
+- Request/response headers and body
+- Status code and duration
+- Root `http.request` span with child spans (DB, etc.)
+
+### Custom Spans
+Track operations within requests:
+
+```typescript
+import { useVisionSpan } from '@getvision/adapter-fastify'
+
+app.get('/users', async (request, reply) => {
+  const withSpan = useVisionSpan()
+  
+  const users = withSpan('db.select', {
+    'db.system': 'postgresql',
+    'db.table': 'users'
+  }, () => {
+    return db.select().from(users).all()
+  })
+  
+  return { users }
+})
+```
+
+### Auto-Discovery (Services Catalog)
+Automatically discover all routes:
+
+```typescript
+// Auto-group routes by first path segment (Users, Root, etc.)
+enableAutoDiscovery(app)
+
+// Or provide manual services grouping with glob-like patterns
+enableAutoDiscovery(app, {
+  services: [
+    { name: 'Users', description: 'User management', routes: ['/users/*'] },
+    { name: 'Auth', routes: ['/auth/*'] }
+  ]
+})
+```
+
+## API
+
+### `visionPlugin(options?)`
+
+Fastify plugin for Vision.
+
+**Options:**
+```typescript
+interface VisionFastifyOptions {
+  port?: number              // Dashboard port (default: 9500)
+  enabled?: boolean          // Enable Vision (default: true)
+  maxTraces?: number         // Max traces to store (default: 1000)
+  maxLogs?: number           // Max logs to store (default: 10000)
+  logging?: boolean          // Console logging (default: true)
+  cors?: boolean             // Auto CORS for dashboard (default: true)
+  service?: {
+    name?: string            // Service name
+    version?: string         // Service version
+    description?: string     // Service description
+    integrations?: {
+      database?: string      // Database connection
+      redis?: string         // Redis connection
+      [key: string]: string | undefined
+    }
+  }
+}
+```
+
+### `enableAutoDiscovery(app, options?)`
+
+Enable automatic route discovery for Fastify app.
+
+**Note:** Call this after all routes are registered.
+
+```ts
+type ServiceDefinition = {
+  name: string
+  description?: string
+  routes: string[] // e.g. ['/users/*']
+}
+
+enableAutoDiscovery(app, {
+  services: [
+    { name: 'Users', routes: ['/users/*'] },
+  ]
+})
+```
+
+### `useVisionSpan()`
+
+Get span helper for current request. Child spans are automatically parented to the root `http.request` span for the current request.
+
+**Returns:** `(name, attributes, fn) => result`
+
+```typescript
+const withSpan = useVisionSpan()
+
+const result = withSpan('operation.name', {
+  'attr.key': 'value'
+}, () => {
+  // Your operation
+  return result
+})
+```
+
+### `getVisionContext()`
+
+Get current Vision context.
+
+**Returns:** `{ vision: VisionCore, traceId: string, rootSpanId: string }`
+
+```typescript
+import { getVisionContext } from '@getvision/adapter-fastify'
+
+app.get('/debug', async (request, reply) => {
+  const { vision, traceId } = getVisionContext()
+  return { traceId }
+})
+```
+
+### `getVisionInstance()`
+
+Get the global Vision instance.
+
+**Returns:** `VisionCore | null`
+
+## Environment Variables
+
+```bash
+VISION_ENABLED=true        # Enable/disable Vision
+VISION_PORT=9500           # Dashboard port
+NODE_ENV=development       # Environment
+
+# CORS notes
+# Dashboard adds/needs headers: X-Vision-Trace-Id, X-Vision-Session
+# The plugin auto-sets:
+#   Access-Control-Allow-Origin: *
+#   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
+#   Access-Control-Allow-Headers: Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session
+#   Access-Control-Expose-Headers: X-Vision-Trace-Id, X-Vision-Session
+```
+
+## Fastify-Specific Features
+
+### Hooks Lifecycle
+
+Vision uses Fastify hooks for tracing:
+- `onRequest` - Create trace, start root span, add CORS headers
+- `preHandler` - Run in AsyncLocalStorage context
+- `onResponse` - Complete trace, end span, broadcast to dashboard
+
+### Schema Support
+
+Fastify's native schema support works with Zod:
+
+```typescript
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string(),
+  email: z.string().email()
+})
+
+app.post('/users', {
+  schema: {
+    body: schema
+  }
+}, async (request, reply) => {
+  // request.body is validated
+  return request.body
+})
+```
+
+Vision automatically extracts the schema and generates JSON templates for API Explorer.
+
+## Integration with ORMs
+
+### Prisma
+
+```typescript
+app.get('/users', async (request, reply) => {
+  const withSpan = useVisionSpan()
+  
+  const users = await withSpan('db.query', {
+    'db.system': 'postgresql',
+    'db.operation': 'findMany'
+  }, async () => {
+    return await prisma.user.findMany()
+  })
+  
+  return { users }
+})
+```
+
+### Drizzle
+
+```typescript
+app.get('/users', async (request, reply) => {
+  const withSpan = useVisionSpan()
+  
+  const users = await withSpan('db.select', {
+    'db.system': 'postgresql',
+    'db.table': 'users'
+  }, async () => {
+    return await db.select().from(users)
+  })
+  
+  return { users }
+})
+```
+
+## TypeScript
+
+Full TypeScript support included.
+
+```typescript
+import type { VisionFastifyOptions } from '@getvision/adapter-fastify'
+
+const options: VisionFastifyOptions = {
+  port: 9500,
+  service: {
+    name: 'my-api',
+    version: '1.0.0'
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { VisionCore } from '@getvision/core';
+import type { Trace, VisionFastifyOptions, ServiceDefinition } from '@getvision/core';
+interface VisionContext {
+    vision: VisionCore;
+    trace: Trace;
+    traceId: string;
+    rootSpanId: string;
+}
+export declare function getVisionContext(): VisionContext;
+export declare function useVisionSpan(): <T>(name: string, attributes: Record<string, any> | undefined, fn: () => T) => T;
+export declare function getVisionInstance(): VisionCore | null;
+export declare const visionPlugin: FastifyPluginAsync<VisionFastifyOptions>;
+export declare function enableAutoDiscovery(fastify: FastifyInstance, options?: {
+    services?: ServiceDefinition[];
+}): void;
+export { generateZodTemplate } from '@getvision/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAElE,OAAO,EACL,UAAU,EAMX,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAIV,KAAK,EACL,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,iBAAiB,CAAA;AAGxB,UAAU,aAAa;IACrB,MAAM,EAAE,UAAU,CAAA;IAClB,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAMhD;AAED,wBAAgB,aAAa,KAInB,CAAC,EACP,MAAM,MAAM,EACZ,YAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAK,EACpC,IAAI,MAAM,CAAC,KACV,CAAC,CAgCL;AAKD,wBAAgB,iBAAiB,IAAI,UAAU,GAAG,IAAI,CAErD;AA2OD,eAAO,MAAM,YAAY,0CAGvB,CAAA;AAEF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAAE,GAC3C,IAAI,CAgEN;AAmGD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,382 @@
+import fp from 'fastify-plugin';
+import { VisionCore, autoDetectPackageInfo, autoDetectIntegrations, detectDrizzle, startDrizzleStudio, stopDrizzleStudio, } from '@getvision/core';
+import { fastifyRequestContext, requestContext } from '@fastify/request-context';
+export function getVisionContext() {
+    const ctx = requestContext.get('visionTrace');
+    if (!ctx) {
+        throw new Error('Vision context not available. Make sure visionPlugin is registered.');
+    }
+    return ctx;
+}
+export function useVisionSpan() {
+    const { vision, traceId, rootSpanId } = getVisionContext();
+    const tracer = vision.getTracer();
+    return (name, attributes = {}, fn) => {
+        const span = tracer.startSpan(name, traceId, rootSpanId);
+        for (const [key, value] of Object.entries(attributes)) {
+            tracer.setAttribute(span.id, key, value);
+        }
+        try {
+            const result = fn();
+            const completedSpan = tracer.endSpan(span.id);
+            if (completedSpan) {
+                vision.getTraceStore().addSpan(traceId, completedSpan);
+            }
+            return result;
+        }
+        catch (error) {
+            tracer.setAttribute(span.id, 'error', true);
+            tracer.setAttribute(span.id, 'error.message', error instanceof Error ? error.message : String(error));
+            const completedSpan = tracer.endSpan(span.id);
+            if (completedSpan) {
+                vision.getTraceStore().addSpan(traceId, completedSpan);
+            }
+            throw error;
+        }
+    };
+}
+let visionInstance = null;
+export function getVisionInstance() {
+    return visionInstance;
+}
+const visionPluginImpl = async (fastify, options) => {
+    const { port = 9500, enabled = true, maxTraces = 1000, maxLogs = 10000, logging = true, cors = true, } = options;
+    if (!enabled) {
+        return;
+    }
+    if (!visionInstance) {
+        visionInstance = new VisionCore({
+            port,
+            maxTraces,
+            maxLogs,
+        });
+    }
+    const vision = visionInstance;
+    await fastify.register(fastifyRequestContext, {
+        hook: 'onRequest',
+    });
+    fastify.addHook('onReady', async () => {
+        // Auto-detect service info
+        const pkgInfo = autoDetectPackageInfo();
+        const autoDetectedIntegrations = autoDetectIntegrations();
+        // Merge with user-provided config
+        const serviceName = options.service?.name || pkgInfo.name;
+        const serviceVersion = options.service?.version || pkgInfo.version;
+        const serviceDesc = options.service?.description;
+        const integrations = {
+            ...autoDetectedIntegrations,
+            ...options.service?.integrations,
+        };
+        // Filter out undefined values from integrations
+        const cleanIntegrations = {};
+        for (const [key, value] of Object.entries(integrations)) {
+            if (value !== undefined) {
+                cleanIntegrations[key] = value;
+            }
+        }
+        // Detect and optionally start Drizzle Studio
+        const drizzleInfo = detectDrizzle();
+        let drizzleStudioUrl;
+        if (drizzleInfo.detected) {
+            console.log(`🗄️  Drizzle detected (${drizzleInfo.configPath})`);
+            if (options.drizzle?.autoStart) {
+                const drizzlePort = options.drizzle.port || 4983;
+                const started = startDrizzleStudio(drizzlePort);
+                if (started) {
+                    // Drizzle Studio uses local.drizzle.studio domain (with HTTPS)
+                    drizzleStudioUrl = 'https://local.drizzle.studio';
+                }
+            }
+            else {
+                console.log('💡 Tip: Enable Drizzle Studio auto-start with drizzle: { autoStart: true }');
+                drizzleStudioUrl = 'https://local.drizzle.studio';
+            }
+        }
+        // Set app status with service metadata
+        vision.setAppStatus({
+            name: serviceName,
+            version: serviceVersion,
+            description: serviceDesc,
+            running: true,
+            pid: process.pid,
+            metadata: {
+                framework: 'Fastify',
+                integrations: Object.keys(cleanIntegrations).length > 0 ? cleanIntegrations : undefined,
+                drizzle: drizzleInfo.detected
+                    ? {
+                        detected: true,
+                        configPath: drizzleInfo.configPath,
+                        studioUrl: drizzleStudioUrl,
+                        autoStarted: options.drizzle?.autoStart || false,
+                    }
+                    : undefined,
+            },
+        });
+        // Cleanup on exit
+        process.on('SIGINT', () => {
+            stopDrizzleStudio();
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            stopDrizzleStudio();
+            process.exit(0);
+        });
+    });
+    const CAPTURE_KEY = Symbol.for('vision.fastify.routes');
+    const captured = (fastify[CAPTURE_KEY] = fastify[CAPTURE_KEY] || []);
+    fastify.addHook('onRoute', (routeOpts) => {
+        const methods = Array.isArray(routeOpts.method) ? routeOpts.method : [routeOpts.method];
+        for (const m of methods) {
+            const method = (m || '').toString().toUpperCase();
+            if (!method || method === 'HEAD' || method === 'OPTIONS')
+                continue;
+            captured.push({
+                method,
+                url: routeOpts.url,
+                schema: routeOpts.schema,
+                handlerName: routeOpts.handler?.name || 'anonymous',
+            });
+        }
+    });
+    if (cors) {
+        fastify.options('/*', async (request, reply) => {
+            reply
+                .header('Access-Control-Allow-Origin', '*')
+                .header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS')
+                .header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session')
+                .header('Access-Control-Expose-Headers', 'X-Vision-Trace-Id, X-Vision-Session')
+                .code(204)
+                .send();
+        });
+        fastify.addHook('onRequest', async (request, reply) => {
+            reply.header('Access-Control-Allow-Origin', '*');
+            reply.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+            reply.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Vision-Trace-Id, X-Vision-Session');
+            reply.header('Access-Control-Expose-Headers', 'X-Vision-Trace-Id, X-Vision-Session');
+        });
+    }
+    fastify.addHook('onRequest', async (request, reply) => {
+        if (request.method === 'OPTIONS')
+            return;
+        const startTime = Date.now();
+        request.visionStartTime = startTime;
+        const trace = vision.createTrace(request.method, request.url);
+        reply.header('X-Vision-Trace-Id', trace.id);
+        const tracer = vision.getTracer();
+        const rootSpan = tracer.startSpan('http.request', trace.id);
+        request.requestContext.set('visionTrace', {
+            vision,
+            trace,
+            traceId: trace.id,
+            rootSpanId: rootSpan.id,
+        });
+        tracer.setAttribute(rootSpan.id, 'http.method', request.method);
+        tracer.setAttribute(rootSpan.id, 'http.path', request.url);
+        tracer.setAttribute(rootSpan.id, 'http.url', request.url);
+        if (request.query && Object.keys(request.query).length > 0) {
+            tracer.setAttribute(rootSpan.id, 'http.query', request.query);
+        }
+        const requestMeta = {
+            method: request.method,
+            url: request.url,
+            headers: request.headers,
+            query: Object.keys(request.query || {}).length ? request.query : undefined,
+            body: request.body,
+        };
+        tracer.setAttribute(rootSpan.id, 'http.request', requestMeta);
+        trace.metadata = { ...trace.metadata, request: requestMeta };
+        const sessionId = request.headers['x-vision-session'];
+        if (sessionId) {
+            tracer.setAttribute(rootSpan.id, 'session.id', sessionId);
+            trace.metadata = { ...trace.metadata, sessionId };
+        }
+        if (logging) {
+            const parts = [`method=${request.method}`, `path=${request.url}`];
+            if (sessionId)
+                parts.push(`sessionId=${sessionId}`);
+            parts.push(`traceId=${trace.id}`);
+            console.info(`INF starting request ${parts.join(' ')}`);
+        }
+    });
+    fastify.addHook('onResponse', async (request, reply) => {
+        if (request.method === 'OPTIONS')
+            return;
+        const startTime = request.visionStartTime;
+        const context = request.requestContext.get('visionTrace');
+        if (!context || !startTime)
+            return;
+        const { vision, trace, traceId, rootSpanId } = context;
+        const tracer = vision.getTracer();
+        try {
+            const duration = Date.now() - startTime;
+            const rootSpan = tracer.getSpan(rootSpanId);
+            if (!rootSpan)
+                return;
+            tracer.setAttribute(rootSpan.id, 'http.status_code', reply.statusCode);
+            const responseMeta = {
+                status: reply.statusCode,
+                headers: reply.getHeaders(),
+            };
+            tracer.setAttribute(rootSpan.id, 'http.response', responseMeta);
+            trace.metadata = { ...trace.metadata, response: responseMeta };
+            const completedSpan = tracer.endSpan(rootSpan.id);
+            if (completedSpan) {
+                vision.getTraceStore().addSpan(traceId, completedSpan);
+            }
+            vision.completeTrace(traceId, reply.statusCode, duration);
+            if (logging) {
+                console.info(`INF request completed code=${reply.statusCode} duration=${duration}ms method=${request.method} path=${request.url} traceId=${traceId}`);
+            }
+        }
+        catch (error) {
+            console.error('Vision: Error completing trace:', error);
+        }
+    });
+};
+export const visionPlugin = fp(visionPluginImpl, {
+    fastify: '5.x',
+    name: '@getvision/adapter-fastify'
+});
+export function enableAutoDiscovery(fastify, options) {
+    const vision = visionInstance;
+    if (!vision) {
+        console.warn('Vision not initialized. Call visionPlugin first.');
+        return;
+    }
+    fastify.addHook('onReady', async () => {
+        const routes = [];
+        const services = {};
+        // Use captured routes from onRoute hook
+        const CAPTURE_KEY = Symbol.for('vision.fastify.routes');
+        const capturedRoutes = fastify[CAPTURE_KEY] || [];
+        for (const route of capturedRoutes) {
+            const routeMeta = {
+                method: route.method,
+                path: route.url,
+                handler: route.handlerName || 'anonymous',
+            };
+            // Try to get schema from route
+            if (route.schema?.body) {
+                try {
+                    routeMeta.requestBody = jsonSchemaToTemplate(route.schema.body);
+                }
+                catch (e) {
+                    // Ignore schema conversion errors
+                }
+            }
+            // Try to get response schema (Fastify supports response: { 200: { ... } })
+            if (route.schema?.response) {
+                try {
+                    // Get the success response schema (200, 201, etc.)
+                    const responseSchema = route.schema.response['200'] ||
+                        route.schema.response['201'] ||
+                        route.schema.response['2xx'];
+                    if (responseSchema) {
+                        routeMeta.responseBody = jsonSchemaToTemplate(responseSchema);
+                    }
+                }
+                catch (e) {
+                    // Ignore schema conversion errors
+                }
+            }
+            routes.push(routeMeta);
+            // Group into services
+            const serviceName = findServiceForRoute(routeMeta.path, options?.services);
+            if (!services[serviceName]) {
+                services[serviceName] = {
+                    name: serviceName,
+                    routes: [],
+                };
+            }
+            services[serviceName].routes.push(routeMeta);
+        }
+        vision.registerRoutes(routes);
+        vision.registerServices(Object.values(services));
+        console.info(`Vision: Discovered ${routes.length} routes across ${Object.keys(services).length} services`);
+    });
+}
+function jsonSchemaToTemplate(schema) {
+    if (!schema || typeof schema !== 'object') {
+        return {
+            template: '{}',
+            fields: [],
+        };
+    }
+    const lines = ['{'];
+    const fields = [];
+    if (schema.properties && typeof schema.properties === 'object') {
+        const props = Object.entries(schema.properties);
+        const required = Array.isArray(schema.required) ? schema.required : [];
+        props.forEach(([key, prop], index) => {
+            const isRequired = required.includes(key);
+            const description = prop?.description || '';
+            const type = Array.isArray(prop?.type) ? prop.type[0] : prop?.type || 'any';
+            let value;
+            switch (type) {
+                case 'string':
+                    value = prop?.format === 'email' ? '"user@example.com"' : '"string"';
+                    break;
+                case 'number':
+                case 'integer':
+                    value = '0';
+                    break;
+                case 'boolean':
+                    value = 'false';
+                    break;
+                case 'array':
+                    value = '[]';
+                    break;
+                case 'object':
+                    value = '{}';
+                    break;
+                default:
+                    value = 'null';
+            }
+            const comment = description
+                ? ` // ${description}${isRequired ? '' : ' (optional)'}`
+                : (isRequired ? '' : ' // optional');
+            const comma = index < props.length - 1 ? ',' : '';
+            lines.push(`  "${key}": ${value}${comma}${comment}`);
+            fields.push({
+                name: key,
+                type,
+                description: description || undefined,
+                required: isRequired,
+                example: prop?.examples?.[0],
+            });
+        });
+    }
+    lines.push('}');
+    return {
+        template: lines.join('\n'),
+        fields,
+    };
+}
+function findServiceForRoute(path, customServices) {
+    if (customServices) {
+        for (const service of customServices) {
+            for (const pattern of service.routes) {
+                if (matchPattern(path, pattern)) {
+                    return service.name;
+                }
+            }
+        }
+    }
+    const segments = path.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return 'Root';
+    // Find first non-param segment
+    const firstSegment = segments.find(s => !s.startsWith(':')) || segments[0];
+    // Skip param-only paths
+    if (firstSegment.startsWith(':'))
+        return 'Root';
+    return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
+}
+function matchPattern(path, pattern) {
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -2);
+        return path === prefix || path.startsWith(prefix + '/');
+    }
+    return path === pattern;
+}
+export { generateZodTemplate } from '@getvision/core';