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

package/dist/agent.js

@@ -13,8 +13,10 @@ import { StudioTracer } from './instrumentation/tracer.js';
 import { RouteScanner } from './discovery/route-scanner.js';
 import { RequestRecorder } from './recording/request-recorder.js';
 import { ContainerIntrospector, } from './introspection/container-introspector.js';
+import { DatabaseIntrospector } from './introspection/database-introspector.js';
 import { LogCapture } from './logging/log-capture.js';
 import { SecurityEngine } from './security/index.js';
+import { resolveInstallId } from './identity/install-id.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -90,6 +92,7 @@ export class StudioAgent {
     recorder;
     introspector = null;
     containerSnapshot = null;
+    databaseIntrospector = null;
     logCapture;
     securityEngine = null;
     io = null;
@@ -101,8 +104,18 @@ export class StudioAgent {
     responseTimes = [];
     startTime = Date.now();
     isRunning = false;
+    srcWatcher = null;
+    rescanTimer = null;
+    /**
+     * 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.
+     */
+    metricsTimer = null;
     constructor(config = {}) {
         this.config = {
+            mode: config.mode ?? 'development',
+            installId: resolveInstallId(config.installId || undefined),
             port: config.port ?? 3334,
             dbPath: config.dbPath ?? '.studio/studio.db',
             enableRecording: config.enableRecording ?? true,
@@ -119,6 +132,7 @@ export class StudioAgent {
         };
         if (this.config.appContainer) {
             this.introspector = new ContainerIntrospector(this.config.appContainer);
+            this.databaseIntrospector = new DatabaseIntrospector(this.config.appContainer);
         }
         this.logCapture = new LogCapture(1000);
         this.tracer = new StudioTracer(this.config.serviceName);
@@ -178,8 +192,64 @@ export class StudioAgent {
             this.securityEngine?.scheduleRefresh();
         });
         this.startSecurityEngine();
+        // Watch the project's `src/` for controller / module / DTO changes so
+        // the Routes, Architecture and API client tabs stay live without the
+        // user reloading Studio. Disabled in production and silently no-ops
+        // when the directory is missing or `fs.watch(recursive)` isn't
+        // supported on this platform/Node version.
+        this.startSrcWatcher();
         this.isRunning = true;
     }
+    /**
+     * 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.
+     */
+    startSrcWatcher() {
+        if (process.env.NODE_ENV === 'production')
+            return;
+        if (process.env.EXPRESSOTS_STUDIO_FS_WATCH === 'false')
+            return;
+        const srcDir = path.resolve(process.cwd(), 'src');
+        if (!fs.existsSync(srcDir))
+            return;
+        const debounceMs = 300;
+        const onChange = (_event, filename) => {
+            if (!filename)
+                return;
+            const name = filename.toString();
+            // Only react to source file changes; skip editor swap files and the
+            // compiled output to avoid feedback loops.
+            if (!/\.(ts|js)$/i.test(name))
+                return;
+            if (name.includes('node_modules'))
+                return;
+            if (name.includes('dist' + path.sep) || name.startsWith('dist'))
+                return;
+            if (this.rescanTimer)
+                clearTimeout(this.rescanTimer);
+            this.rescanTimer = setTimeout(() => {
+                this.rescanTimer = null;
+                void this.scanRoutes();
+            }, debounceMs);
+        };
+        try {
+            this.srcWatcher = fs.watch(srcDir, { recursive: true }, onChange);
+            this.srcWatcher.on('error', () => {
+                // Best-effort: a closed handle / inotify exhaustion shouldn't take
+                // down the agent. Disable further reactions until next start().
+                this.srcWatcher?.close();
+                this.srcWatcher = null;
+            });
+        }
+        catch {
+            // Recursive watch is unsupported on some Linux setups (Node < 20).
+            // Live updates simply degrade to "rescan on next request"; users
+            // running tsx/nodemon will still get a fresh agent on each restart.
+            this.srcWatcher = null;
+        }
+    }
     /**
      * Stand up the SecurityEngine and kick off the first scan. The
      * engine reuses the existing Socket.IO server — every transition in
@@ -214,6 +284,23 @@ export class StudioAgent {
     getContainerSnapshot() {
         return this.containerSnapshot;
     }
+    /**
+     * Capture a fresh in-memory database snapshot. Returns an "unavailable"
+     * snapshot when no `InMemoryDBProvider` is registered or no container was
+     * provided to the agent.
+     */
+    captureDatabaseSnapshot() {
+        if (this.databaseIntrospector) {
+            return this.databaseIntrospector.capture();
+        }
+        return {
+            available: false,
+            tableCount: 0,
+            totalRecords: 0,
+            entities: [],
+            timestamp: new Date().toISOString(),
+        };
+    }
     /** Stop the Studio Agent */
     async stop() {
         if (!this.isRunning)
@@ -240,6 +327,23 @@ export class StudioAgent {
             this.securityEngine.stop();
             this.securityEngine = null;
         }
+        if (this.metricsTimer) {
+            clearInterval(this.metricsTimer);
+            this.metricsTimer = null;
+        }
+        if (this.rescanTimer) {
+            clearTimeout(this.rescanTimer);
+            this.rescanTimer = null;
+        }
+        if (this.srcWatcher) {
+            try {
+                this.srcWatcher.close();
+            }
+            catch {
+                // best-effort
+            }
+            this.srcWatcher = null;
+        }
     }
     /**
      * Tear down the WebSocket / HTTP server with a hard timeout so the
@@ -294,30 +398,118 @@ export class StudioAgent {
         try {
             this.appStructure = await this.scanner.scan();
             this.routes = this.scanner.getRoutes();
-            // Route counts available via getRoutes()
-            // If Express app is provided, also scan runtime routes
+            // Snapshot the un-prefixed path for every freshly scanned route.
+            // The static scanner only sees `@controller(...)` + `@Get(...)`
+            // metadata — the host mounts the whole router under
+            // `setGlobalRoutePrefix("/api")` later, so the source-of-truth
+            // path is kept on `originalPath` and the user-visible `path` is
+            // always recomputed from it. This lets `updateRuntimeInfo` swap
+            // the prefix later without compounding `/api/api/health`-style
+            // duplication on each call.
+            for (const r of this.routes) {
+                r.originalPath = r.path;
+            }
+            // Re-fold any previously reported runtime middleware data into
+            // the fresh static structure. Without this, a hot-reload rescan
+            // would drop the global pipeline nodes and Reflect-derived edges
+            // until the next `updateRuntimeInfo()` callback.
+            this.mergeRuntimeMiddlewareIntoStructure();
+            // Apply the host-supplied global URL prefix. Earlier versions
+            // tried to recover the prefix from `app.router.stack[i].regexp`
+            // at runtime, but Express 5 dropped that field in favour of
+            // opaque `matchers` closures, so the prefix is no longer
+            // recoverable from the layer alone. The host already passes it
+            // in via `agentOptions.globalPrefix` — use that as the source of
+            // truth.
+            this.applyGlobalPrefixToRoutes();
+            // If Express app is provided, also scan runtime routes and merge
+            // anything the static scan missed (handlers registered ad-hoc via
+            // `app.get(...)` outside a `@Controller()` class, e.g. health-check
+            // probes wired directly in `configureServices`). The static
+            // scanner is the source of truth for decorated routes; runtime
+            // routes only ever *add* — never replace.
             if (this.config.expressApp) {
                 const runtimeRoutes = RouteScanner.scanExpressApp(this.config.expressApp);
-                // Merge runtime routes with discovered routes
-                // Merge with discovered routes
+                const prefix = this.normaliseGlobalPrefix(this.config.globalPrefix);
                 for (const runtimeRoute of runtimeRoutes) {
-                    const exists = this.routes.some((r) => r.path === runtimeRoute.path && r.method === runtimeRoute.method);
-                    if (!exists) {
-                        this.routes.push(runtimeRoute);
-                    }
+                    // Apply the same global prefix to runtime routes — Express 5
+                    // strips it from `app.router.stack` (the prefix lives inside
+                    // sub-router matcher closures), so `scanExpressApp` returns
+                    // un-prefixed paths just like the static scanner.
+                    const fullPath = prefix
+                        ? this.joinPrefixWithRoute(prefix, runtimeRoute.path)
+                        : runtimeRoute.path;
+                    const exact = this.routes.find((r) => r.path === fullPath && r.method === runtimeRoute.method);
+                    if (exact)
+                        continue;
+                    this.routes.push({
+                        ...runtimeRoute,
+                        path: fullPath,
+                        // Keep the un-prefixed form so a later prefix change rewrites
+                        // this route the same way it does decorator-discovered ones.
+                        ...({ originalPath: runtimeRoute.path }),
+                    });
                 }
             }
-            // Broadcast to connected clients
+            // Broadcast to connected clients. The routes payload is small,
+            // but the architecture map needs the full `appStructure` (controllers,
+            // services, providers, middleware, dependencies) to redraw nodes
+            // and edges for newly added classes — without this second emit the
+            // map keeps showing the boot-time graph even after a rescan.
             this.broadcast('routes', this.routes);
+            if (this.appStructure) {
+                this.broadcast('structure', this.appStructure);
+            }
         }
         catch (error) {
-            console.error('Failed to scan routes:', error);
+            // `console.error('Failed to scan routes:', error)` prints `{}` for any
+            // thrown value that isn't a `Error` instance (because plain objects
+            // serialise as their enumerable keys, of which there are none on most
+            // exception shapes). Normalise to a useful one-liner so users can
+            // actually diagnose what the static scan tripped over.
+            const err = error;
+            const message = (err && (err.message || err.code)) ||
+                (typeof error === 'string' ? error : JSON.stringify(error)) ||
+                'unknown error';
+            console.error(`[StudioAgent] Failed to scan routes: ${message}`);
+            if (err?.stack && process.env.EXPRESSOTS_STUDIO_DEBUG === 'true') {
+                console.error(err.stack);
+            }
         }
     }
     /** Get discovered routes */
     getRoutes() {
         return this.routes;
     }
+    /**
+     * 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.
+     */
+    normaliseGlobalPrefix(value) {
+        if (!value || typeof value !== 'string')
+            return '';
+        if (value === '/' || value === '')
+            return '';
+        return value.endsWith('/') ? value.slice(0, -1) : value;
+    }
+    /**
+     * 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`.
+     */
+    joinPrefixWithRoute(prefix, path) {
+        if (!path || path === '/')
+            return prefix + '/';
+        return prefix + (path.startsWith('/') ? path : `/${path}`);
+    }
     /** Get application structure */
     getAppStructure() {
         return this.appStructure;
@@ -346,8 +538,18 @@ export class StudioAgent {
     updateRuntimeInfo(patch) {
         if (patch.appPort !== undefined)
             this.config.appPort = patch.appPort;
-        if (patch.globalPrefix !== undefined)
+        // Track whether the prefix actually changed before assigning, so we
+        // know whether to re-prefix the cached `routes`. Without this, a
+        // late `updateRuntimeInfo({ globalPrefix: "/api" })` (e.g. fired
+        // from `app.listen()`'s callback after `setGlobalRoutePrefix("/api")`
+        // ran during configureServices) would update the config but leave
+        // the route list still showing un-prefixed paths until the next
+        // file-watcher rescan.
+        let prefixChanged = false;
+        if (patch.globalPrefix !== undefined && patch.globalPrefix !== this.config.globalPrefix) {
             this.config.globalPrefix = patch.globalPrefix;
+            prefixChanged = true;
+        }
         if (patch.startupMs !== undefined)
             this.config.startupMs = patch.startupMs;
         if (patch.interceptorCount !== undefined) {
@@ -360,17 +562,197 @@ export class StudioAgent {
             this.config.middlewareCount = patch.middlewareCount;
         }
         if (patch.runtimeItems !== undefined) {
-            // Merge so partial updates (e.g. providers only) don't wipe the
-            // other categories.
             this.config.runtimeItems = {
                 ...this.config.runtimeItems,
                 ...patch.runtimeItems,
             };
         }
+        if (patch.middlewarePreset !== undefined) {
+            this.config.middlewarePreset = patch.middlewarePreset;
+        }
+        // Fold the latest runtime data into the cached `appStructure` so the
+        // architecture map sees:
+        //   1. Global pipeline middleware as nodes (even when nothing in
+        //      source extends ExpressoMiddleware — e.g. plain functions
+        //      added via `Middleware.add`).
+        //   2. Scoped middleware → controller / route edges from the
+        //      `middlewareBindings` payload.
+        //
+        // The merge is idempotent — calling `updateRuntimeInfo` repeatedly
+        // with the same payload yields the same structure.
+        const merged = this.mergeRuntimeMiddlewareIntoStructure();
+        if (merged && this.io) {
+            this.broadcast('structure', this.appStructure);
+        }
+        // If the global URL prefix changed, splice it onto every cached
+        // route so the Routes / API client tabs immediately reflect the
+        // mounted paths instead of the bare per-controller paths.
+        if (prefixChanged) {
+            this.applyGlobalPrefixToRoutes();
+            if (this.io)
+                this.broadcast('routes', this.routes);
+        }
         if (this.io) {
             this.broadcast('runtime', this.getRuntimeInfo());
         }
     }
+    /**
+     * 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.
+     */
+    applyGlobalPrefixToRoutes() {
+        const prefix = this.normaliseGlobalPrefix(this.config.globalPrefix);
+        for (const route of this.routes) {
+            const original = route.originalPath;
+            if (typeof original !== 'string')
+                continue;
+            route.path = prefix
+                ? this.joinPrefixWithRoute(prefix, original)
+                : original;
+        }
+    }
+    /**
+     * 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.
+     */
+    mergeRuntimeMiddlewareIntoStructure() {
+        if (!this.appStructure)
+            return false;
+        const runtime = this.config.runtimeItems;
+        if (!runtime)
+            return false;
+        let changed = false;
+        const byName = new Map();
+        for (const mw of this.appStructure.middleware) {
+            byName.set(mw.name, mw);
+        }
+        // Global pipeline middleware → upgrade or create a node.
+        for (const item of runtime.middleware ?? []) {
+            if (item.type === 'built-in')
+                continue;
+            const existing = byName.get(item.name);
+            if (existing) {
+                if (existing.scope !== 'global') {
+                    existing.scope = 'global';
+                    changed = true;
+                }
+            }
+            else {
+                const node = {
+                    name: item.name,
+                    filePath: '',
+                    dependencies: [],
+                    methods: [],
+                    scope: 'global',
+                };
+                this.appStructure.middleware.push(node);
+                byName.set(item.name, node);
+                changed = true;
+            }
+        }
+        const knownNodes = new Set();
+        for (const c of this.appStructure.controllers)
+            knownNodes.add(c.name);
+        for (const s of this.appStructure.services)
+            knownNodes.add(s.name);
+        for (const p of this.appStructure.providers)
+            knownNodes.add(p.name);
+        for (const m of this.appStructure.middleware)
+            knownNodes.add(m.name);
+        const seenEdge = new Set();
+        for (const dep of this.appStructure.dependencies) {
+            seenEdge.add(`${dep.source}->${dep.target}@${dep.type}`);
+        }
+        // Scoped bindings from Reflect metadata. If a binding references a
+        // middleware name we haven't seen before (common for plain-function
+        // middleware like `newMiddleware()` that doesn't extend
+        // ExpressoMiddleware), create a lightweight node on-the-fly so the
+        // architecture map can still render it.
+        for (const binding of runtime.middlewareBindings ?? []) {
+            if (!knownNodes.has(binding.controllerName))
+                continue;
+            if (!knownNodes.has(binding.middlewareName)) {
+                const node = {
+                    name: binding.middlewareName,
+                    filePath: '',
+                    dependencies: [],
+                    methods: [],
+                    scope: binding.scope,
+                };
+                this.appStructure.middleware.push(node);
+                byName.set(binding.middlewareName, node);
+                knownNodes.add(binding.middlewareName);
+                changed = true;
+            }
+            const key = `${binding.middlewareName}->${binding.controllerName}@middleware`;
+            if (!seenEdge.has(key)) {
+                this.appStructure.dependencies.push({
+                    source: binding.middlewareName,
+                    target: binding.controllerName,
+                    type: 'middleware',
+                });
+                seenEdge.add(key);
+                changed = true;
+            }
+            const mw = byName.get(binding.middlewareName);
+            if (mw) {
+                if (binding.scope === 'controller' && mw.scope !== 'controller') {
+                    mw.scope = 'controller';
+                    changed = true;
+                }
+                else if (binding.scope === 'route' &&
+                    mw.scope !== 'controller' &&
+                    mw.scope !== 'route') {
+                    mw.scope = 'route';
+                    changed = true;
+                }
+            }
+        }
+        // Global middleware fans out to every controller. We only emit
+        // edges for nodes that already exist; the list is short (typically
+        // a handful of custom middleware × a handful of controllers) so
+        // duplication is cheap and produces a readable layered layout.
+        for (const mw of this.appStructure.middleware) {
+            if (mw.scope !== 'global')
+                continue;
+            for (const ctrl of this.appStructure.controllers) {
+                const key = `${mw.name}->${ctrl.name}@middleware`;
+                if (seenEdge.has(key))
+                    continue;
+                this.appStructure.dependencies.push({
+                    source: mw.name,
+                    target: ctrl.name,
+                    type: 'middleware',
+                });
+                seenEdge.add(key);
+                changed = true;
+            }
+        }
+        return changed;
+    }
     /**
      * Build a snapshot of runtime information for the Status dashboard.
      *
@@ -437,6 +819,7 @@ export class StudioAgent {
             },
             runtimeItems: this.config.runtimeItems,
             recordingEnabled: this.config.enableRecording,
+            middlewarePreset: this.config.middlewarePreset,
         };
     }
     /** Start WebSocket server */
@@ -491,6 +874,14 @@ export class StudioAgent {
                     data: this.containerSnapshot,
                 });
             }
+            // Send the in-memory database schema snapshot (when a provider is
+            // registered). Always emitted so the UI can render the "not detected"
+            // empty state when `available` is false.
+            socket.emit('message', {
+                type: 'database',
+                timestamp: Date.now(),
+                data: this.captureDatabaseSnapshot(),
+            });
             socket.emit('message', {
                 type: 'recording_state',
                 timestamp: Date.now(),
@@ -624,6 +1015,35 @@ export class StudioAgent {
                     data: this.containerSnapshot,
                 });
             });
+            // Re-send the in-memory database schema snapshot on demand. Captured
+            // fresh each call so newly created tables / records are reflected.
+            socket.on('get_database_schema', () => {
+                socket.emit('message', {
+                    type: 'database',
+                    timestamp: Date.now(),
+                    data: this.captureDatabaseSnapshot(),
+                });
+            });
+            // Return a page of rows for a single table.
+            socket.on('get_database_table', async (params) => {
+                const table = typeof params?.table === 'string' ? params.table : '';
+                if (!table)
+                    return;
+                const offset = typeof params?.offset === 'number' && params.offset >= 0
+                    ? params.offset
+                    : 0;
+                const limit = typeof params?.limit === 'number' && params.limit > 0
+                    ? Math.min(params.limit, 200)
+                    : 50;
+                const data = this.databaseIntrospector
+                    ? await this.databaseIntrospector.getTableData(table, offset, limit)
+                    : { table, rows: [], total: 0, offset, limit };
+                socket.emit('message', {
+                    type: 'database_table',
+                    timestamp: Date.now(),
+                    data,
+                });
+            });
             // Push the latest cached report on demand. Useful when the UI
             // explicitly navigates to the Security view and wants a fresh
             // copy even if nothing has changed.
@@ -893,7 +1313,13 @@ export class StudioAgent {
     }
     /** Start metrics collection interval */
     startMetricsCollection() {
-        setInterval(() => {
+        // Reuse an existing timer rather than stacking duplicates if the host
+        // re-invokes start(); also makes idempotent restarts safe.
+        if (this.metricsTimer) {
+            clearInterval(this.metricsTimer);
+            this.metricsTimer = null;
+        }
+        this.metricsTimer = setInterval(() => {
             // Calculate percentiles
             if (this.responseTimes.length > 0) {
                 const sorted = [...this.responseTimes].sort((a, b) => a - b);
@@ -912,6 +1338,9 @@ export class StudioAgent {
             // negligible.
             this.broadcast('runtime', this.getRuntimeInfo());
         }, 5000);
+        // Don't keep the event loop alive solely for metrics broadcasting;
+        // the agent is observability infrastructure, not application logic.
+        this.metricsTimer.unref?.();
     }
     /** Create Express middleware for request/response recording */
     createMiddleware() {