@expressots/studio-agent 4.0.0-preview.1

package/README.md

@@ -0,0 +1,143 @@
+# @expressots/studio-agent
+
+Instrumentation agent for ExpressoTS Studio - provides route discovery, OpenTelemetry tracing, and request recording.
+
+## Features
+
+- **Route Discovery**: Automatically scans your ExpressoTS application to discover all routes, controllers, and services
+- **OpenTelemetry Tracing**: Full distributed tracing with automatic instrumentation
+- **Request Recording**: Record and replay HTTP requests for debugging
+- **WebSocket Communication**: Real-time updates to Studio UI
+- **Metrics Collection**: P50/P95/P99 latency, error rates, and more
+
+## Installation
+
+```bash
+npm install @expressots/studio-agent
+```
+
+## Quick Start
+
+```typescript
+import { StudioAgent } from '@expressots/studio-agent';
+
+const agent = new StudioAgent({
+  port: 3334,
+  serviceName: 'my-app',
+  enableRecording: true,
+});
+
+// Start the agent
+await agent.start();
+
+// Use the middleware (optional, for request recording)
+app.use(agent.createMiddleware());
+
+// Get discovered routes
+const routes = agent.getRoutes();
+
+// Stop when done
+await agent.stop();
+```
+
+## Configuration
+
+```typescript
+interface AgentConfig {
+  /** Port for the agent WebSocket server (default: 3334) */
+  port: number;
+  
+  /** Path to store SQLite database (default: '.studio/studio.db') */
+  dbPath: string;
+  
+  /** Enable request/response recording (default: true) */
+  enableRecording: boolean;
+  
+  /** Maximum number of recorded exchanges to keep (default: 1000) */
+  maxRecordedExchanges: number;
+  
+  /** Enable performance profiling (default: true) */
+  enableProfiling: boolean;
+  
+  /** Sample rate for tracing 0-1 (default: 1.0) */
+  traceSampleRate: number;
+  
+  /** Custom service name (default: 'expressots-app') */
+  serviceName: string;
+  
+  /** Express app instance for runtime route scanning */
+  expressApp?: any;
+}
+```
+
+## Components
+
+### StudioAgent
+
+Main orchestrator that coordinates all functionality.
+
+### RouteScanner
+
+Scans TypeScript source files to discover routes and their metadata:
+
+```typescript
+import { RouteScanner } from '@expressots/studio-agent';
+
+const scanner = new RouteScanner('./src');
+const structure = await scanner.scan();
+
+console.log(structure.controllers);
+console.log(structure.services);
+console.log(structure.dependencies);
+```
+
+### RequestRecorder
+
+Records HTTP requests/responses for later replay:
+
+```typescript
+import { RequestRecorder } from '@expressots/studio-agent';
+
+const recorder = new RequestRecorder('.studio/studio.db');
+await recorder.initialize();
+
+// Get recent exchanges
+const exchanges = recorder.getRecentExchanges(100);
+
+// Search by path
+const results = recorder.searchExchanges('/api/users', 'GET');
+```
+
+### StudioTracer
+
+OpenTelemetry tracer with custom span processing:
+
+```typescript
+import { StudioTracer } from '@expressots/studio-agent';
+
+const tracer = new StudioTracer('my-service');
+await tracer.start((trace) => {
+  console.log('Trace completed:', trace.traceId);
+});
+
+// Create custom spans
+await tracer.createSpan('my-operation', async () => {
+  // Your code here
+}, { attribute: 'value' });
+```
+
+## WebSocket Events
+
+The agent emits real-time events to connected clients:
+
+| Event | Description |
+|-------|-------------|
+| `routes` | Discovered routes |
+| `trace` | Completed trace |
+| `request` | New request recorded |
+| `metrics` | Updated metrics |
+| `structure` | Application structure |
+
+## License
+
+MIT © ExpressoTS

package/dist/agent.d.ts

@@ -0,0 +1,127 @@
+/**
+ * StudioAgent - Main orchestrator for ExpressoTS Studio instrumentation
+ *
+ * Provides:
+ * - OpenTelemetry instrumentation
+ * - Route discovery
+ * - Request/response recording
+ * - WebSocket communication with Studio UI
+ */
+import { type ContainerSnapshot } from './introspection/container-introspector.js';
+import { type LogEntry } from './logging/log-capture.js';
+import type { AgentConfig, RouteInfo, AppStructure, AppMetrics, EndpointStats, RuntimeInfo } from './types/index.js';
+export declare class StudioAgent {
+    private config;
+    private tracer;
+    private scanner;
+    private recorder;
+    private introspector;
+    private containerSnapshot;
+    private logCapture;
+    private securityEngine;
+    private io;
+    private httpServer;
+    private routes;
+    private appStructure;
+    private metrics;
+    private endpointStats;
+    private responseTimes;
+    private startTime;
+    private isRunning;
+    constructor(config?: Partial<AgentConfig>);
+    /** Start the Studio Agent */
+    start(): Promise<void>;
+    /**
+     * Stand up the SecurityEngine and kick off the first scan. The
+     * engine reuses the existing Socket.IO server — every transition in
+     * its report goes out as a `WSMessage<'security'>` envelope, gated
+     * on at least one connected client.
+     */
+    private startSecurityEngine;
+    /** Get the captured container snapshot (or null if unavailable). */
+    getContainerSnapshot(): ContainerSnapshot | null;
+    /** Stop the Studio Agent */
+    stop(): Promise<void>;
+    /**
+     * Tear down the WebSocket / HTTP server with a hard timeout so the
+     * host's graceful shutdown never hangs on a slow socket.io drain.
+     *
+     * If the close doesn't complete in time, we move on — the OS reclaims
+     * the port the moment the host process exits, so the next hot-reload
+     * start succeeds anyway. (`tsx --watch` / `nodemon` will SIGKILL us
+     * otherwise, which surfaces to the user as "Failed running ./src/main.ts".)
+     */
+    private shutdownWebSocketServer;
+    /** Scan application for routes */
+    scanRoutes(): Promise<void>;
+    /** Get discovered routes */
+    getRoutes(): RouteInfo[];
+    /** Get application structure */
+    getAppStructure(): AppStructure | null;
+    /** Get current metrics */
+    getMetrics(): AppMetrics;
+    /** Get endpoint statistics (without internal durations array) */
+    getEndpointStats(): EndpointStats[];
+    /**
+     * Apply runtime details that the host application only knows after
+     * boot (e.g. the actual port returned by `app.listen()`, total startup
+     * duration, count of registered interceptors).
+     *
+     * Called by the adapter integration once the HTTP server is listening.
+     * Re-broadcasts the updated runtime info so connected Studio clients
+     * see fresh values without waiting for the next metrics tick.
+     */
+    updateRuntimeInfo(patch: {
+        appPort?: number;
+        globalPrefix?: string;
+        startupMs?: number;
+        interceptorCount?: number;
+        providerCount?: number;
+        middlewareCount?: number;
+        runtimeItems?: import('./types/index.js').RuntimeItems;
+    }): void;
+    /**
+     * Build a snapshot of runtime information for the Status dashboard.
+     *
+     * Pulls together:
+     *   - host process info (`pid`, `nodeVersion`, `platform`, etc.)
+     *   - explicit values passed via `AgentConfig` (port, prefix, startupMs)
+     *   - counts derived from the latest discovery scan
+     *   - best-effort framework versions from the host's `node_modules`
+     *
+     * Designed to be cheap to call on every WebSocket connection.
+     */
+    getRuntimeInfo(): RuntimeInfo;
+    /** Start WebSocket server */
+    private startWebSocketServer;
+    /**
+     * `httpServer.listen()` that survives transient `EADDRINUSE` from
+     * hot-reload races — when `tsx --watch` (or nodemon) restarts the host
+     * process before the previous run has released the agent port. We
+     * retry a few times with exponential-ish backoff before giving up.
+     *
+     * On final failure throws an `Error` whose `.code` is preserved so
+     * the integration layer (`@expressots/adapter-express`) can decide
+     * whether to surface it; today it just logs a warning and the host
+     * app keeps running (Studio is opt-in dev tooling).
+     */
+    private listenWithRetry;
+    /** Single attempt — resolves on `listening`, rejects on `error`. */
+    private listenOnce;
+    /** Handle incoming trace */
+    private handleTrace;
+    /** Update endpoint statistics */
+    private updateEndpointStats;
+    /** Replay a recorded request */
+    private replayRequest;
+    /** Broadcast message to all connected clients */
+    private broadcast;
+    /** Create WebSocket message */
+    private createMessage;
+    /** Start metrics collection interval */
+    private startMetricsCollection;
+    /** Create Express middleware for request/response recording */
+    createMiddleware(): (req: any, res: any, next: any) => any;
+}
+export type { LogEntry };
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAKrE,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EAET,YAAY,EACZ,UAAU,EACV,aAAa,EAGb,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAgE1B,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,SAAS,CAAkB;gBAEvB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM;IA2C7C,6BAA6B;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoD5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA2B3B,oEAAoE;IACpE,oBAAoB,IAAI,iBAAiB,GAAG,IAAI;IAIhD,4BAA4B;IACtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3B;;;;;;;;OAQG;YACW,uBAAuB;IAyCrC,kCAAkC;IAC5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BjC,4BAA4B;IAC5B,SAAS,IAAI,SAAS,EAAE;IAIxB,gCAAgC;IAChC,eAAe,IAAI,YAAY,GAAG,IAAI;IAItC,0BAA0B;IAC1B,UAAU,IAAI,UAAU;IAQxB,iEAAiE;IACjE,gBAAgB,IAAI,aAAa,EAAE;IAInC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,KAAK,EAAE;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,OAAO,kBAAkB,EAAE,YAAY,CAAC;KACxD,GAAG,IAAI;IA0BR;;;;;;;;;;OAUG;IACH,cAAc,IAAI,WAAW;IAgE7B,6BAA6B;YACf,oBAAoB;IA+RlC;;;;;;;;;;OAUG;YACW,eAAe;IA2B7B,oEAAoE;IACpE,OAAO,CAAC,UAAU;IAgBlB,4BAA4B;IAC5B,OAAO,CAAC,WAAW;IAkCnB,iCAAiC;IACjC,OAAO,CAAC,mBAAmB;IA6D3B,gCAAgC;YAClB,aAAa;IAqF3B,iDAAiD;IACjD,OAAO,CAAC,SAAS;IAMjB,+BAA+B;IAC/B,OAAO,CAAC,aAAa;IAQrB,wCAAwC;IACxC,OAAO,CAAC,sBAAsB;IAwB9B,+DAA+D;IAC/D,gBAAgB,KACN,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG;CA+JxC;AAED,YAAY,EAAE,QAAQ,EAAE,CAAC"}