@expressots/studio-agent 4.0.0-preview.1 → 4.0.0-preview.3

package/README.md

@@ -1,143 +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
+# @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

@@ -17,6 +17,7 @@ export declare class StudioAgent {
     private recorder;
     private introspector;
     private containerSnapshot;
+    private databaseIntrospector;
     private logCapture;
     private securityEngine;
     private io;
@@ -28,9 +29,24 @@ export declare class StudioAgent {
     private responseTimes;
     private startTime;
     private isRunning;
+    private srcWatcher;
+    private rescanTimer;
+    /**
+     * Periodic metrics-broadcast timer. Captured so `stop()` can clear it
+     * cleanly; `.unref()`'d so it never keeps the Node event loop alive in
+     * tests / serverless environments.
+     */
+    private metricsTimer;
     constructor(config?: Partial<AgentConfig>);
     /** Start the Studio Agent */
     start(): Promise<void>;
+    /**
+     * Start a debounced filesystem watcher over `./src` (relative to the
+     * host's CWD) that triggers a route + structure rescan whenever a
+     * `*.ts` / `*.js` file changes. Uses `fs.watch({ recursive: true })`
+     * to avoid taking a chokidar dependency. Failures are non-fatal.
+     */
+    private startSrcWatcher;
     /**
      * Stand up the SecurityEngine and kick off the first scan. The
      * engine reuses the existing Socket.IO server — every transition in
@@ -40,6 +56,12 @@ export declare class StudioAgent {
     private startSecurityEngine;
     /** Get the captured container snapshot (or null if unavailable). */
     getContainerSnapshot(): ContainerSnapshot | null;
+    /**
+     * Capture a fresh in-memory database snapshot. Returns an "unavailable"
+     * snapshot when no `InMemoryDBProvider` is registered or no container was
+     * provided to the agent.
+     */
+    private captureDatabaseSnapshot;
     /** Stop the Studio Agent */
     stop(): Promise<void>;
     /**
@@ -56,6 +78,25 @@ export declare class StudioAgent {
     scanRoutes(): Promise<void>;
     /** Get discovered routes */
     getRoutes(): RouteInfo[];
+    /**
+     * Normalise the host-supplied global URL prefix into the form we
+     * actually want to splice into route paths.
+     *
+     *   - Returns `''` for "no prefix" (so callers can fall through with a
+     *     simple truthy check).
+     *   - Strips trailing slashes (`/api/` → `/api`) so the join helper
+     *     never produces `/api//foo`.
+     *   - Defends against the host passing through a legitimate but
+     *     no-op `'/'` prefix.
+     */
+    private normaliseGlobalPrefix;
+    /**
+     * Splice a normalised global prefix onto a controller-relative route
+     * path while preserving the leading slash and avoiding doubled
+     * separators. `/api` + `/` → `/api/`, `/api` + `users` → `/api/users`,
+     * `/api` + `/users` → `/api/users`.
+     */
+    private joinPrefixWithRoute;
     /** Get application structure */
     getAppStructure(): AppStructure | null;
     /** Get current metrics */
@@ -79,7 +120,41 @@ export declare class StudioAgent {
         providerCount?: number;
         middlewareCount?: number;
         runtimeItems?: import('./types/index.js').RuntimeItems;
+        middlewarePreset?: import('./types/index.js').MiddlewarePresetInfo;
     }): void;
+    /**
+     * Recompute every route's `path` from its captured `originalPath` plus
+     * the current `config.globalPrefix`. Idempotent and prefix-change-safe
+     * — calling it twice with different prefixes never produces the
+     * `/api/api/health` doubling we'd see if we appended in place.
+     *
+     * Routes pushed by older code paths that don't carry an `originalPath`
+     * (defensive — hot-reload scans always set it now) are left alone, so
+     * we never silently strip a prefix the source of truth set
+     * intentionally.
+     */
+    private applyGlobalPrefixToRoutes;
+    /**
+     * Merge global pipeline middleware and runtime middleware bindings
+     * into the static `appStructure` so the architecture map sees a
+     * single source of truth. Returns `true` when the structure changed.
+     *
+     * Rules:
+     *   - Each `runtimeItems.middleware` entry whose `type === 'custom'`
+     *     gets a `MiddlewareInfo` node with `scope: 'global'` (built-in
+     *     pipeline entries like `helmet` / `jsonParser` aren't worth
+     *     plotting — they would clutter every architecture map without
+     *     adding signal). Names are deduplicated against the existing
+     *     middleware list.
+     *   - Each `runtimeItems.middlewareBindings` entry contributes a
+     *     `middleware → controller` edge (deduplicated with the static
+     *     bindings produced by `RouteScanner`). The middleware node's
+     *     scope is upgraded to `controller` or `route`.
+     *   - Global middleware also gets synthetic edges to every
+     *     controller in the structure so the map shows the pipeline
+     *     fanning out across the app.
+     */
+    private mergeRuntimeMiddlewareIntoStructure;
     /**
      * Build a snapshot of runtime information for the Status dashboard.
      *

package/dist/agent.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}