@lensmcp/nest-instrumentation 1.0.0

package/lib/trace-provider.js

@@ -0,0 +1,25 @@
+/**
+ * `@TraceProvider({ memory: true })` — opt a provider into memory
+ * container tracking. The provider tracker reads this metadata at
+ * bootstrap and, for each tagged provider (or all providers when
+ * `memory.scope === 'all'`), scans the instance's own enumerable
+ * fields for Map / Set / Array containers and wraps them via
+ * `trackContainer`.
+ *
+ * Implemented without `reflect-metadata` writes beyond a plain
+ * property flag so it stays decoupled from Nest's metadata system.
+ */
+const TRACE_PROVIDER_FLAG = Symbol.for('@lensmcp/nest-instrumentation/trace-provider');
+export function TraceProvider(options = {}) {
+    return (target) => {
+        target[TRACE_PROVIDER_FLAG] = {
+            memory: options.memory ?? true,
+        };
+    };
+}
+export function readTraceProvider(ctor) {
+    if (!ctor || (typeof ctor !== 'function' && typeof ctor !== 'object')) {
+        return undefined;
+    }
+    return ctor[TRACE_PROVIDER_FLAG];
+}

package/lib/types.d.ts

@@ -0,0 +1,52 @@
+import type { BaseEvent } from '@lensmcp/protocol-types';
+/**
+ * Where to send instrumentation events. Phase 3 ships a synchronous
+ * in-process bus (the Nest app runs inside the same process as the
+ * lensmcp-mcp server during dev), an IPC client over a Unix socket
+ * (cross-process; supervisor wiring lands in 1.5/3.5), and a no-op
+ * sink that just collects events in memory for testing.
+ */
+export type EventSink = (event: BaseEvent) => void;
+export interface LensmcpModuleOptions {
+    /** Project name stamped onto every event (used for resource routing). */
+    projectName: string;
+    /** Per-request session id; defaults to `process.env.LENSMCP_SESSION_ID` or a fresh one. */
+    sessionId?: string;
+    /** Override the event sink. Defaults to a sink that posts JSONL to a Unix socket if `LENSMCP_IPC_SOCKET` is set; otherwise to stdout for visibility. */
+    emit?: EventSink;
+    /** Which trace layers to enable. */
+    trace?: {
+        requests?: boolean;
+        guards?: boolean;
+        controllers?: boolean;
+        services?: boolean;
+        db?: boolean;
+        redis?: boolean;
+        queues?: boolean;
+        /**
+         * Auto-wrap every singleton provider's methods with span +
+         * db-call-count tracing at bootstrap — no `@TraceMethod` needed.
+         * Set by `createLensmcpNestApp`. Methods already decorated with
+         * `@TraceMethod` (or marked `@LensmcpIgnore`) are skipped.
+         */
+        autoInstrumentMethods?: boolean;
+    };
+    /** Memory tracking (Phase 7). */
+    memory?: {
+        /** off = no tracking; light = container size + growth; deep = + heap snapshots (7.5). */
+        mode?: 'off' | 'light' | 'deep';
+        /** tagged = only `@TraceProvider({ memory: true })` providers; all = every provider. */
+        scope?: 'tagged' | 'all';
+    };
+}
+export interface ResolvedOptions {
+    projectName: string;
+    sessionId: string;
+    emit: EventSink;
+    trace: Required<NonNullable<LensmcpModuleOptions['trace']>>;
+    memory: {
+        mode: 'off' | 'light' | 'deep';
+        scope: 'tagged' | 'all';
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wJAAwJ;IACxJ,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,oCAAoC;IACpC,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,EAAE,CAAC,EAAE,OAAO,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB;;;;;WAKG;QACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;KACjC,CAAC;IACF,iCAAiC;IACjC,MAAM,CAAC,EAAE;QACP,yFAAyF;QACzF,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;QAChC,wFAAwF;QACxF,KAAK,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,EAAE;QACN,IAAI,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;QAC/B,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;KACzB,CAAC;CACH"}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lensmcp/nest-instrumentation",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@lensmcp/core": "1.0.0",
+    "@lensmcp/memory-tracker": "1.0.0",
+    "@lensmcp/protocol-types": "1.0.0",
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0 <12.0.0",
+    "@nestjs/core": ">=10.0.0 <12.0.0",
+    "rxjs": "^7.0.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/kiwiapps-ltd/lensmcp#readme",
+  "bugs": {
+    "url": "https://github.com/kiwiapps-ltd/lensmcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Zero-config NestJS instrumentation for LensMCP — createLensmcpNestApp.",
+  "keywords": [
+    "lensmcp",
+    "mcp",
+    "observability",
+    "ai-agents",
+    "claude",
+    "nestjs",
+    "tracing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiwiapps-ltd/lensmcp.git",
+    "directory": "libs/nest-instrumentation"
+  }
+}