@lensmcp/nest-instrumentation 1.0.0

package/lib/instrument.js

@@ -0,0 +1,160 @@
+import { fingerprint, ulid } from '@lensmcp/core';
+import { currentLensmcpContext } from './context.js';
+import { activeOptions } from './state.js';
+/** Marks a function already wrapped by traceWrap (avoids double-wrap). */
+export const LENSMCP_TRACED = Symbol.for('@lensmcp/nest-instrumentation/traced');
+/** Marks a class/method opted out of auto-instrumentation. */
+export const LENSMCP_IGNORE = Symbol.for('@lensmcp/nest-instrumentation/ignore');
+/** `@LensmcpIgnore()` — skip a class (all methods) or a single method. */
+export function LensmcpIgnore() {
+    return ((target, propertyKey) => {
+        if (propertyKey === undefined) {
+            target[LENSMCP_IGNORE] = true;
+        }
+        else {
+            const fn = target[propertyKey];
+            if (typeof fn === 'function') {
+                fn[LENSMCP_IGNORE] = true;
+            }
+        }
+    });
+}
+export function isTraced(fn) {
+    return typeof fn === 'function' && Boolean(fn[LENSMCP_TRACED]);
+}
+export function isIgnored(target) {
+    return (!!target &&
+        (typeof target === 'function' || typeof target === 'object') &&
+        Boolean(target[LENSMCP_IGNORE]));
+}
+/**
+ * Wrap `fn` with span + db-call tracing. Pure: no decorator/Nest
+ * coupling, so the auto-instrumenter can apply it to any instance method.
+ */
+export function traceWrap(fn, spanName, options = {}) {
+    if (isTraced(fn))
+        return fn;
+    const isDb = options.db ?? false;
+    const wrapped = function (...args) {
+        let opts;
+        try {
+            opts = activeOptions();
+        }
+        catch {
+            return fn.apply(this, args);
+        }
+        if (!opts.trace.services) {
+            return fn.apply(this, args);
+        }
+        const startedAt = Date.now();
+        const ctx = currentLensmcpContext();
+        const dbCountAtStart = ctx?.dbCallCount ?? 0;
+        const redisCountAtStart = ctx?.redisCallCount ?? 0;
+        const externalCountAtStart = ctx?.externalCallCount ?? 0;
+        const emitSpan = (status, err) => {
+            const durationMs = Date.now() - startedAt;
+            const event = {
+                id: ulid(),
+                sessionId: opts.sessionId,
+                timestamp: Date.now(),
+                source: 'nestjs',
+                category: 'backend',
+                severity: status === 'error' ? 'error' : 'info',
+                context: { sessionId: opts.sessionId, flowId: ctx?.flowId, requestId: ctx?.requestId },
+                fingerprint: fingerprint({ kind: 'method-call', identity: spanName }),
+                title: `${spanName} (${durationMs}ms)${status === 'error' ? ' ✗' : ''}`,
+                message: err instanceof Error ? err.message : undefined,
+                raw: {
+                    kind: 'span',
+                    span: {
+                        name: spanName,
+                        flowId: ctx?.flowId,
+                        requestId: ctx?.requestId,
+                        startTime: startedAt,
+                        endTime: Date.now(),
+                        durationMs,
+                        status,
+                    },
+                },
+            };
+            opts.emit(event);
+        };
+        const emitDbQuery = () => {
+            if (ctx)
+                ctx.dbCallCount = (ctx.dbCallCount ?? 0) + 1;
+            opts.emit({
+                id: ulid(),
+                sessionId: opts.sessionId,
+                timestamp: Date.now(),
+                source: 'db',
+                category: 'db',
+                severity: 'info',
+                context: { sessionId: opts.sessionId, flowId: ctx?.flowId, requestId: ctx?.requestId },
+                fingerprint: fingerprint({ kind: 'db-query', identity: spanName }),
+                title: `query ${spanName}`,
+                raw: { kind: 'db-query', query: { signature: spanName } },
+            });
+        };
+        const emitLoopIfNeeded = () => {
+            if (isDb || !ctx)
+                return;
+            const dbDelta = (ctx.dbCallCount ?? 0) - dbCountAtStart;
+            const redisDelta = (ctx.redisCallCount ?? 0) - redisCountAtStart;
+            const externalDelta = (ctx.externalCallCount ?? 0) - externalCountAtStart;
+            // One method issuing the SAME class of operation ≥3 times is the
+            // N+1 / fan-out signal (a loop of selects, a Promise.all of fetches).
+            // Two ops is normal shape (ensure + query); three starts the pattern.
+            if (dbDelta < 3 && redisDelta < 3 && externalDelta < 3)
+                return;
+            const durationMs = Date.now() - startedAt;
+            const parts = [];
+            if (dbDelta >= 3)
+                parts.push(`${dbDelta} DB calls`);
+            if (redisDelta >= 3)
+                parts.push(`${redisDelta} redis calls`);
+            if (externalDelta >= 3)
+                parts.push(`${externalDelta} external calls`);
+            opts.emit({
+                id: ulid(),
+                sessionId: opts.sessionId,
+                timestamp: Date.now(),
+                source: 'nestjs',
+                category: 'backend',
+                severity: 'warning',
+                context: { sessionId: opts.sessionId, flowId: ctx.flowId, requestId: ctx.requestId },
+                fingerprint: fingerprint({ kind: 'loop', identity: spanName }),
+                title: `loop in ${spanName} (${parts.join(', ')})`,
+                raw: {
+                    kind: 'loop',
+                    loop: {
+                        iterations: Math.max(dbDelta, redisDelta, externalDelta),
+                        durationMs,
+                        startedAt,
+                        dbCallsInsideLoop: dbDelta,
+                        redisCallsInsideLoop: redisDelta,
+                        externalCallsInsideLoop: externalDelta,
+                        awaitedOperationsInsideLoop: dbDelta + redisDelta + externalDelta,
+                    },
+                },
+            });
+        };
+        const onOk = () => { if (isDb)
+            emitDbQuery(); emitSpan('ok'); emitLoopIfNeeded(); };
+        const onErr = (err) => { if (isDb)
+            emitDbQuery(); emitSpan('error', err); emitLoopIfNeeded(); };
+        try {
+            const result = fn.apply(this, args);
+            if (result instanceof Promise) {
+                return result.then((v) => { onOk(); return v; }, (err) => { onErr(err); throw err; });
+            }
+            onOk();
+            return result;
+        }
+        catch (err) {
+            onErr(err);
+            throw err;
+        }
+    };
+    wrapped[LENSMCP_TRACED] = true;
+    return wrapped;
+}

package/lib/lensmcp-app.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `createLensmcpNestApp` — a drop-in for `NestFactory.create(AppModule)`
+ * that wires LensMCP with zero edits to the host's `AppModule`.
+ *
+ *   // main.ts
+ *   import { createLensmcpNestApp } from '@lensmcp/nest-instrumentation';
+ *   import { AppModule } from './app.module';
+ *
+ *   const app = await createLensmcpNestApp(AppModule, { projectName: 'api' });
+ *   await app.listen(3100);
+ *
+ * It builds a wrapper module that imports `AppModule` + `LensmcpModule`,
+ * and defaults `trace.autoInstrumentMethods` + `memory.scope: 'all'` on,
+ * so every provider's methods + containers are instrumented without any
+ * `@TraceMethod` / `@TraceProvider`.
+ */
+import { type DynamicModule, type INestApplication, type NestApplicationOptions, type Type } from '@nestjs/common';
+import type { LensmcpModuleOptions } from './types.js';
+export interface CreateLensmcpNestAppOptions extends Partial<LensmcpModuleOptions> {
+    /** Forwarded to `NestFactory.create` (logger, cors, etc.). */
+    nestOptions?: NestApplicationOptions;
+}
+export declare function createLensmcpNestApp(appModule: Type<unknown> | DynamicModule, options?: CreateLensmcpNestAppOptions): Promise<INestApplication>;
+//# sourceMappingURL=lensmcp-app.d.ts.map

package/lib/lensmcp-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lensmcp-app.d.ts","sourceRoot":"","sources":["../../src/lib/lensmcp-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,2BAA4B,SAAQ,OAAO,CAAC,oBAAoB,CAAC;IAChF,8DAA8D;IAC9D,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAED,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,EACxC,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,gBAAgB,CAAC,CAsB3B"}

package/lib/lensmcp-app.js

@@ -0,0 +1,43 @@
+import { __decorate } from "tslib";
+/**
+ * `createLensmcpNestApp` — a drop-in for `NestFactory.create(AppModule)`
+ * that wires LensMCP with zero edits to the host's `AppModule`.
+ *
+ *   // main.ts
+ *   import { createLensmcpNestApp } from '@lensmcp/nest-instrumentation';
+ *   import { AppModule } from './app.module';
+ *
+ *   const app = await createLensmcpNestApp(AppModule, { projectName: 'api' });
+ *   await app.listen(3100);
+ *
+ * It builds a wrapper module that imports `AppModule` + `LensmcpModule`,
+ * and defaults `trace.autoInstrumentMethods` + `memory.scope: 'all'` on,
+ * so every provider's methods + containers are instrumented without any
+ * `@TraceMethod` / `@TraceProvider`.
+ */
+import { Module, } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { LensmcpModule } from './lensmcp.module.js';
+export async function createLensmcpNestApp(appModule, options = {}) {
+    const { nestOptions, projectName, ...rest } = options;
+    const lensmcp = LensmcpModule.forRoot({
+        projectName: projectName ?? process.env['LENSMCP_PROJECT'] ?? 'app',
+        ...rest,
+        // Zero-config defaults: instrument everything unless the caller
+        // explicitly narrows it.
+        trace: { autoInstrumentMethods: true, ...rest.trace },
+        memory: { mode: 'light', scope: 'all', ...rest.memory },
+    });
+    // Lensmcp first → TraceInterceptor outermost (short-circuiting user
+    // interceptors must not bypass tracing).
+    let LensmcpRootModule = class LensmcpRootModule {
+    };
+    LensmcpRootModule = __decorate([
+        Module({ imports: [lensmcp, appModule] })
+    ], LensmcpRootModule);
+    // Marker for @lensmcp/node-instrumentation's NestFactory.create auto-graft:
+    // an already-wrapped root must not be wrapped a second time (duplicate
+    // interceptors → duplicate events).
+    LensmcpRootModule[Symbol.for('lensmcp.wrappedRoot')] = true;
+    return NestFactory.create(LensmcpRootModule, nestOptions);
+}

package/lib/lensmcp.module.d.ts

@@ -0,0 +1,27 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { LensmcpModuleOptions } from './types.js';
+/**
+ * `LensmcpModule.forRoot({ projectName: "api", … })` — the host's
+ * AppModule imports this to wire LensMCP into a NestJS app.
+ *
+ *   import { Module } from '@nestjs/common';
+ *   import { LensmcpModule } from '@lensmcp/nest-instrumentation';
+ *
+ *   @Module({
+ *     imports: [LensmcpModule.forRoot({ projectName: 'api' })],
+ *   })
+ *   export class AppModule {}
+ *
+ * Side effects:
+ *   • Registers an APP_INTERCEPTOR so every request gets a
+ *     LensmcpRequestContext + a server-request span event.
+ *   • Registers a provider tracker that emits `singleton-instance`
+ *     events on bootstrap + lifecycle.
+ *   • Calls `setActiveOptions(...)` synchronously so `@TraceMethod`
+ *     decorators applied to constructor-injected providers find the
+ *     options at decoration time.
+ */
+export declare class LensmcpModule {
+    static forRoot(options: LensmcpModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=lensmcp.module.d.ts.map

package/lib/lensmcp.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lensmcp.module.d.ts","sourceRoot":"","sources":["../../src/lib/lensmcp.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,gBAAgB,CAAC;AAO3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,aAAa;IACxB,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa;CAoC7D"}

package/lib/lensmcp.module.js

@@ -0,0 +1,70 @@
+var LensmcpModule_1;
+import { __decorate } from "tslib";
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { configureMemoryTracker } from '@lensmcp/memory-tracker';
+import { TraceInterceptor } from './trace-interceptor.js';
+import { LensmcpProviderTracker } from './provider-tracker.js';
+import { setActiveOptions } from './state.js';
+import { currentLensmcpContext } from './context.js';
+/**
+ * `LensmcpModule.forRoot({ projectName: "api", … })` — the host's
+ * AppModule imports this to wire LensMCP into a NestJS app.
+ *
+ *   import { Module } from '@nestjs/common';
+ *   import { LensmcpModule } from '@lensmcp/nest-instrumentation';
+ *
+ *   @Module({
+ *     imports: [LensmcpModule.forRoot({ projectName: 'api' })],
+ *   })
+ *   export class AppModule {}
+ *
+ * Side effects:
+ *   • Registers an APP_INTERCEPTOR so every request gets a
+ *     LensmcpRequestContext + a server-request span event.
+ *   • Registers a provider tracker that emits `singleton-instance`
+ *     events on bootstrap + lifecycle.
+ *   • Calls `setActiveOptions(...)` synchronously so `@TraceMethod`
+ *     decorators applied to constructor-injected providers find the
+ *     options at decoration time.
+ */
+let LensmcpModule = LensmcpModule_1 = class LensmcpModule {
+    static forRoot(options) {
+        // Resolve options immediately so subsequent imports and decorator
+        // applications see the populated state singleton.
+        const resolved = setActiveOptions(options);
+        // Phase 7: wire the memory tracker to the same sink + the per-request
+        // ALS context so each container mutation attributes to the active flow.
+        if (resolved.memory.mode !== 'off') {
+            configureMemoryTracker({
+                sessionId: resolved.sessionId,
+                sink: resolved.emit,
+                contextGetter: () => {
+                    const ctx = currentLensmcpContext();
+                    if (!ctx)
+                        return undefined;
+                    return {
+                        sessionId: ctx.sessionId,
+                        flowId: ctx.flowId,
+                        requestId: ctx.requestId,
+                        originNodeId: ctx.originNodeId,
+                    };
+                },
+            });
+        }
+        const providers = [
+            { provide: APP_INTERCEPTOR, useClass: TraceInterceptor },
+            LensmcpProviderTracker,
+        ];
+        return {
+            module: LensmcpModule_1,
+            providers,
+            exports: [],
+            global: true,
+        };
+    }
+};
+LensmcpModule = LensmcpModule_1 = __decorate([
+    Module({})
+], LensmcpModule);
+export { LensmcpModule };

package/lib/provider-tracker.d.ts

@@ -0,0 +1,28 @@
+import { type OnApplicationBootstrap, type OnModuleDestroy } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+/**
+ * On application bootstrap, walks the Nest container and emits one
+ * `singleton-instance` event per provider so the `apps/nest` reducer
+ * can materialise `nest://providers`. On module destroy (HMR / shutdown)
+ * marks each instance as `disposed`.
+ *
+ * `generation` is the LensMCP module-instance counter (incremented each
+ * time `LensmcpModule.forRoot` is constructed), which mirrors a hot
+ * reload. Lets the agent ask "is the new gen serving requests, or did
+ * an old one stick around?".
+ */
+export declare class LensmcpProviderTracker implements OnApplicationBootstrap, OnModuleDestroy {
+    private readonly moduleRef;
+    private active;
+    constructor(moduleRef: ModuleRef);
+    onApplicationBootstrap(): void;
+    onModuleDestroy(): void;
+    /**
+     * Handle a provider with no bootstrap instance. Request-scoped and
+     * transient providers fall here; value/factory providers (no class
+     * `metatype`) are ignored. Wraps the class's shared prototype once and
+     * emits a provider event with the real scope.
+     */
+    private trackScopedProvider;
+}
+//# sourceMappingURL=provider-tracker.d.ts.map

package/lib/provider-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-tracker.d.ts","sourceRoot":"","sources":["../../src/lib/provider-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,sBAAsB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAyBzC;;;;;;;;;;GAUG;AACH,qBACa,sBAAuB,YAAW,sBAAsB,EAAE,eAAe;IAGxE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,MAAM,CAA6B;gBAEd,SAAS,EAAE,SAAS;IAEjD,sBAAsB,IAAI,IAAI;IA2F9B,eAAe,IAAI,IAAI;IAavB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CAuC5B"}