@lensmcp/node-instrumentation 1.0.0

package/lib/tap-fs.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tapFs = tapFs;
+const tslib_1 = require("tslib");
+/**
+ * fs tap: counts real read/write traffic (sync, callback, promise and stream
+ * APIs) and publishes a 1-second aggregate (source `fs`, kind `fs-ops`) —
+ * per-op events would drown the bus; an aggregate keeps the canvas honest
+ * about which services touch the disk and how hard.
+ *
+ * Self-noise is excluded by construction: the lens writer captured the
+ * ORIGINAL appendFileSync before this tap patches fs, `isLensWriting()`
+ * guards re-entry, and bus/node_modules/tmp/dist paths are skipped.
+ */
+const os = tslib_1.__importStar(require("node:os"));
+const emit_1 = require("./emit");
+const bucket = {
+    reads: 0,
+    writes: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    paths: new Map(),
+};
+let timer = null;
+const TMP = os.tmpdir();
+const CWD = process.cwd();
+const SKIP = ['node_modules', '/.nx/', '/dist/', '/.git/', '.lensmcp'];
+function trackedPath(p) {
+    if ((0, emit_1.isLensWriting)())
+        return null;
+    const s = typeof p === 'string' ? p
+        : Buffer.isBuffer(p) ? p.toString()
+            : p instanceof URL ? p.pathname
+                : null;
+    if (!s || s === emit_1.EVENT_FILE)
+        return null;
+    if (s.startsWith(TMP))
+        return null;
+    if (SKIP.some((k) => s.includes(k)))
+        return null;
+    return s;
+}
+function record(kind, p, bytes = 0) {
+    const s = trackedPath(p);
+    if (!s)
+        return;
+    if (kind === 'read') {
+        bucket.reads += 1;
+        bucket.bytesRead += bytes;
+    }
+    else {
+        bucket.writes += 1;
+        bucket.bytesWritten += bytes;
+    }
+    const rel = s.startsWith(CWD) ? s.slice(CWD.length + 1) : s;
+    if (bucket.paths.size < 50)
+        bucket.paths.set(rel, (bucket.paths.get(rel) ?? 0) + 1);
+    if (!timer) {
+        timer = setTimeout(flush, 1000);
+        timer.unref?.();
+    }
+}
+function flush() {
+    timer = null;
+    const { reads, writes, bytesRead, bytesWritten } = bucket;
+    if (reads + writes === 0)
+        return;
+    const top = [...bucket.paths.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([p]) => p);
+    bucket.reads = bucket.writes = bucket.bytesRead = bucket.bytesWritten = 0;
+    bucket.paths.clear();
+    (0, emit_1.lensEmit)('fs', 'info', `fs ${reads} reads · ${writes} writes`, { name: 'fs', kind: 'fs-ops', reads, writes, bytesRead, bytesWritten, top }, `fs:${emit_1.PROJECT}`);
+}
+const byteLen = (d) => typeof d === 'string' ? Buffer.byteLength(d) : Buffer.isBuffer(d) ? d.length : 0;
+function wrap(obj, key, make) {
+    const orig = obj?.[key];
+    if (!obj || typeof orig !== 'function' || orig.__lensmcp)
+        return;
+    const wrapped = make(orig);
+    wrapped.__lensmcp = true;
+    try {
+        obj[key] = wrapped;
+    }
+    catch {
+        /* frozen namespace — skip */
+    }
+}
+function tapFs() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fs = require('node:fs');
+    wrap(fs, 'readFileSync', (orig) => function (p, ...rest) {
+        const r = orig.call(this, p, ...rest);
+        record('read', p, byteLen(r));
+        return r;
+    });
+    wrap(fs, 'writeFileSync', (orig) => function (p, data, ...rest) {
+        const r = orig.call(this, p, data, ...rest);
+        record('write', p, byteLen(data));
+        return r;
+    });
+    wrap(fs, 'appendFileSync', (orig) => function (p, data, ...rest) {
+        const r = orig.call(this, p, data, ...rest);
+        record('write', p, byteLen(data));
+        return r;
+    });
+    // Callback forms — measure on success via the wrapped callback.
+    wrap(fs, 'readFile', (orig) => function (p, ...rest) {
+        const cb = rest[rest.length - 1];
+        if (typeof cb === 'function') {
+            rest[rest.length - 1] = (err, data) => {
+                if (!err)
+                    record('read', p, byteLen(data));
+                cb(err, data);
+            };
+        }
+        return orig.call(this, p, ...rest);
+    });
+    for (const key of ['writeFile', 'appendFile']) {
+        wrap(fs, key, (orig) => function (p, data, ...rest) {
+            const cb = rest[rest.length - 1];
+            if (typeof cb === 'function') {
+                rest[rest.length - 1] = (err) => {
+                    if (!err)
+                        record('write', p, byteLen(data));
+                    cb(err);
+                };
+            }
+            return orig.call(this, p, data, ...rest);
+        });
+    }
+    // Promise forms (fs.promises === require('node:fs/promises') — same object).
+    const fsp = fs.promises;
+    wrap(fsp, 'readFile', (orig) => async function (p, ...rest) {
+        const r = await orig.call(this, p, ...rest);
+        record('read', p, byteLen(r));
+        return r;
+    });
+    for (const key of ['writeFile', 'appendFile']) {
+        wrap(fsp, key, (orig) => async function (p, data, ...rest) {
+            const r = await orig.call(this, p, data, ...rest);
+            record('write', p, byteLen(data));
+            return r;
+        });
+    }
+    // Streams: count the open; byte accounting per chunk isn't worth the heat.
+    wrap(fs, 'createReadStream', (orig) => function (p, ...rest) {
+        record('read', p, 0);
+        return orig.call(this, p, ...rest);
+    });
+    wrap(fs, 'createWriteStream', (orig) => function (p, ...rest) {
+        record('write', p, 0);
+        return orig.call(this, p, ...rest);
+    });
+}

package/lib/tap-nest.d.ts

@@ -0,0 +1,15 @@
+export interface CapturedChildApp {
+    handler: unknown;
+    serviceConfig: {
+        port: number | string;
+    };
+    close: () => Promise<void>;
+}
+/**
+ * Default `createChildApp` for zero-touch bundles. Installed BEFORE the
+ * bundle is imported; a legacy dual-mode main.ts overwrites it at import
+ * time and takes precedence automatically.
+ */
+export declare function installChildAppBridge(): void;
+export declare function nestTap(exportsObject: unknown): boolean;
+//# sourceMappingURL=tap-nest.d.ts.map

package/lib/tap-nest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-nest.d.ts","sourceRoot":"","sources":["../../src/lib/tap-nest.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACzC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAwCD;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAM5C;AAED,wBAAgB,OAAO,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAiDvD"}

package/lib/tap-nest.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installChildAppBridge = installChildAppBridge;
+exports.nestTap = nestTap;
+/**
+ * NestJS tap — the piece that makes a completely ORDINARY main.ts
+ * (`NestFactory.create(AppModule)` … `app.listen(port)`) both fully
+ * instrumented and pod-servable, with zero lens imports in host source:
+ *
+ * 1. `NestFactory.create` is patched to graft `LensmcpModule.forRoot` (class
+ *    traces via autoInstrumentMethods, request flows, memory tracking) around
+ *    the user's root module — exactly what `createLensmcpNestApp` did, minus
+ *    the import. Roots already wrapped (legacy `createLensmcpNestApp`) carry
+ *    the `Symbol.for('lensmcp.wrappedRoot')` marker and are left alone.
+ *
+ * 2. Under the cluster devserver (`APP_RUNNER=1`), `app.listen(port)` is
+ *    hijacked: instead of binding TCP, the app is `init()`ed and its raw
+ *    request handler is pushed to the capture queue. The bridge installs a
+ *    default `global.createChildApp` that drains that queue — so the
+ *    devserver's existing contract is satisfied by the RUNNER, not by
+ *    dual-mode boilerplate in the host's main.ts. Legacy bundles that still
+ *    define `global.createChildApp` simply overwrite the default at import
+ *    and win.
+ */
+const emit_1 = require("./emit");
+const WRAPPED = Symbol.for('lensmcp.wrappedRoot');
+const captures = [];
+const waiters = [];
+function pushCapture(c) {
+    const w = waiters.shift();
+    if (w) {
+        clearTimeout(w.timer);
+        w.resolve(c);
+    }
+    else {
+        captures.push(c);
+    }
+}
+function nextCapture(timeoutMs = 60_000) {
+    const ready = captures.shift();
+    if (ready)
+        return Promise.resolve(ready);
+    return new Promise((resolve, reject) => {
+        const w = {
+            resolve,
+            reject,
+            timer: setTimeout(() => {
+                const i = waiters.indexOf(w);
+                if (i >= 0)
+                    waiters.splice(i, 1);
+                reject(new Error('[lensmcp] no NestJS app captured within 60s — does main.ts call app.listen()? ' +
+                    '(zero-touch pods boot by running your main and intercepting listen)'));
+            }, timeoutMs),
+        };
+        w.timer.unref?.();
+        waiters.push(w);
+    });
+}
+/**
+ * Default `createChildApp` for zero-touch bundles. Installed BEFORE the
+ * bundle is imported; a legacy dual-mode main.ts overwrites it at import
+ * time and takes precedence automatically.
+ */
+function installChildAppBridge() {
+    if (process.env['APP_RUNNER'] !== '1')
+        return;
+    const g = global;
+    const factory = () => nextCapture();
+    g['createChildApp'] = factory;
+    g['__lensmcpCreateChildApp'] = factory;
+}
+function nestTap(exportsObject) {
+    const core = exportsObject;
+    const NF = core?.NestFactory;
+    const orig = NF?.['create'];
+    // Partial exports (@nestjs/core's own circular require mid-load) → not yet.
+    if (!NF || typeof orig !== 'function')
+        return false;
+    if (orig.__lensmcp)
+        return true;
+    const wrapped = async function (moduleCls, ...rest) {
+        let root = moduleCls;
+        const mc = moduleCls;
+        const alreadyWrapped = !!(mc?.[WRAPPED] || mc?.['module']?.[WRAPPED]);
+        if (process.env['LENSMCP_NEST'] !== '0' && !alreadyWrapped) {
+            try {
+                root = await buildLensmcpRoot(moduleCls);
+            }
+            catch {
+                root = moduleCls; // instrumentation unavailable — boot uninstrumented, never block the app
+            }
+        }
+        return orig.call(this ?? NF, root, ...rest);
+    };
+    wrapped.__lensmcp = true;
+    NF['create'] = wrapped;
+    // Pod capture happens at CLASS level: NestFactory.create returns Nest's
+    // exception-zone Proxy whose set trap rejects every property write, so a
+    // per-instance `app.listen = …` assignment is impossible — patch
+    // NestApplication.prototype.listen once instead. `this` inside is the
+    // proxy; method CALLS through it (init/getHttpAdapter/close) are fine.
+    if (process.env['APP_RUNNER'] === '1') {
+        const proto = core?.NestApplication?.prototype;
+        const origListen = proto?.['listen'];
+        if (proto && typeof origListen === 'function' && !origListen.__lensmcp) {
+            const listenWrapped = async function (port, ...rest) {
+                return captureApp(this, port).catch((err) => {
+                    // Capture failed — fall back to a real TCP listen so standalone
+                    // runs (or exotic adapters) still come up.
+                    console.error('[lensmcp] pod capture failed, falling back to TCP listen:', err);
+                    return origListen.call(this, port, ...rest);
+                });
+            };
+            listenWrapped.__lensmcp = true;
+            proto['listen'] = listenWrapped;
+        }
+    }
+    return true;
+}
+async function buildLensmcpRoot(userModule) {
+    // Dynamic import: @lensmcp/nest-instrumentation ships ESM; this lib is CJS.
+    const ni = await import('@lensmcp/nest-instrumentation');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const common = require('@nestjs/common');
+    const lensmcp = ni.LensmcpModule.forRoot({
+        projectName: emit_1.PROJECT,
+        trace: { autoInstrumentMethods: true },
+        memory: { mode: 'light', scope: 'all' },
+    });
+    class LensmcpZeroTouchRoot {
+    }
+    LensmcpZeroTouchRoot[WRAPPED] = true;
+    // Lensmcp FIRST: APP_INTERCEPTORs run in registration order, and the trace
+    // interceptor must be OUTERMOST — a user interceptor that short-circuits
+    // (e.g. a cache hit) would otherwise bypass tracing entirely: no
+    // server-request event and no ALS context for the taps it does hit.
+    common.Module({ imports: [lensmcp, userModule] })(LensmcpZeroTouchRoot);
+    return LensmcpZeroTouchRoot;
+}
+async function captureApp(app, port) {
+    await app['init']();
+    const adapter = app['getHttpAdapter']?.();
+    let handler = adapter?.['getInstance']?.();
+    if (typeof handler !== 'function') {
+        // Fastify adapter: getInstance() is the fastify instance, not a listener.
+        const instance = handler;
+        if (instance?.ready)
+            await instance.ready();
+        if (typeof instance?.routing === 'function') {
+            handler = (req, res) => instance.routing(req, res);
+        }
+    }
+    if (typeof handler !== 'function') {
+        throw new Error('[lensmcp] cannot derive a request handler from the HTTP adapter');
+    }
+    pushCapture({
+        handler,
+        serviceConfig: { port: port ?? process.env['PORT'] ?? 0 },
+        close: () => Promise.resolve(app['close']()).then(() => undefined),
+    });
+    // The user's `await app.listen(port)` resolves with the (unbound) server,
+    // so post-listen log lines in main.ts keep working.
+    return app['getHttpServer']?.();
+}

package/lib/tap-pg.d.ts

@@ -0,0 +1,2 @@
+export declare function pgTap(exportsObject: unknown): boolean;
+//# sourceMappingURL=tap-pg.d.ts.map

package/lib/tap-pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-pg.d.ts","sourceRoot":"","sources":["../../src/lib/tap-pg.ts"],"names":[],"mappings":"AAqDA,wBAAgB,KAAK,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAuErD"}

package/lib/tap-pg.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pgTap = pgTap;
+/**
+ * pg tap (source `db`): wraps `Client.prototype.query` — Pool.query checks
+ * out a Client and delegates, so one patch point covers both. Emits
+ * kind `db-query` with op/table parsed from the SQL text, row count and
+ * duration — the same shape the canvas's postgres node reduces.
+ *
+ * Transaction plumbing (BEGIN/COMMIT/…) is skipped: with pools it's pure
+ * noise that says nothing about what the service actually does.
+ */
+const emit_1 = require("./emit");
+const flow_context_1 = require("./flow-context");
+const SKIP_OPS = new Set(['BEGIN', 'COMMIT', 'ROLLBACK', 'SET', 'SHOW', 'DEALLOCATE', 'DISCARD']);
+function parseSql(text) {
+    const op = (text.match(/^\s*(\w+)/)?.[1] ?? 'query').toUpperCase();
+    const m = text.match(/\b(?:from|into|update|join|table(?:\s+if\s+not\s+exists)?)\s+"?([\w$.]+)"?/i);
+    const table = m?.[1]?.split('.').pop();
+    return { op, ...(table ? { table } : {}) };
+}
+const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+/** Param values, readable but bounded (dev tool: values matter, walls of JSON don't). */
+function paramPreview(values) {
+    if (!Array.isArray(values) || values.length === 0)
+        return undefined;
+    return values.slice(0, 10).map((v) => {
+        if (v === null || v === undefined)
+            return String(v);
+        const s = typeof v === 'string' ? v : (() => { try {
+            return JSON.stringify(v);
+        }
+        catch {
+            return String(v);
+        } })();
+        return clip(s, 80);
+    });
+}
+const rowsOf = (res) => res?.rowCount ?? res?.rows?.length ?? 0;
+/** What came BACK: the first rows, readable and bounded. */
+function resultPreview(res) {
+    const rows = res?.rows;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return undefined;
+    try {
+        return clip(JSON.stringify(rows.slice(0, 2)), 240);
+    }
+    catch {
+        return undefined;
+    }
+}
+function pgTap(exportsObject) {
+    const pg = exportsObject;
+    const proto = pg?.Client?.prototype;
+    const orig = proto?.['query'];
+    if (!proto || typeof orig !== 'function')
+        return false; // partial exports (circular require) — retry
+    if (orig.__lensmcp)
+        return true;
+    const wrapped = function (config, values, callback) {
+        const cfg = config;
+        const text = typeof cfg === 'string' ? cfg : cfg?.text;
+        // Submittables (cursors, query streams) drive their own lifecycle — pass through.
+        if (!text || (cfg && typeof cfg === 'object' && typeof cfg.submit === 'function')) {
+            return orig.call(this, config, values, callback);
+        }
+        const { op, table } = parseSql(text);
+        if (SKIP_OPS.has(op))
+            return orig.call(this, config, values, callback);
+        const opl = op.toLowerCase();
+        const t0 = Date.now();
+        // Snapshot flow context + the actual statement AT the call site (the
+        // request's ALS scope), not at promise resolution.
+        const ctx = (0, flow_context_1.flowContext)();
+        const live = (0, flow_context_1.liveFlowContext)();
+        if (live)
+            live.dbCallCount = (live.dbCallCount ?? 0) + 1; // feeds the N+1 loop detector
+        const query = clip(oneLine(text), 500);
+        const params = paramPreview(Array.isArray(values) ? values : config?.values);
+        const done = (err, res) => {
+            const durationMs = Date.now() - t0;
+            if (err) {
+                (0, emit_1.lensEmit)('db', 'error', `${opl}${table ? ' ' + table : ''} failed (${durationMs}ms)`, {
+                    name: 'postgres', kind: 'db-query', op: opl, ...(table ? { table } : {}),
+                    query, ...(params ? { params } : {}), startedAt: t0,
+                    error: String(err?.message ?? err), durationMs,
+                }, 'db:postgres', ctx);
+            }
+            else {
+                const rows = rowsOf(res);
+                const result = resultPreview(res);
+                (0, emit_1.lensEmit)('db', 'info', `${opl} ${table ?? 'query'} (${rows} rows, ${durationMs}ms)`, {
+                    name: 'postgres', kind: 'db-query', op: opl, ...(table ? { table } : {}),
+                    query, ...(params ? { params } : {}), ...(result ? { result } : {}),
+                    startedAt: t0, rows, durationMs,
+                }, 'db:postgres', ctx);
+            }
+        };
+        const cb = typeof callback === 'function' ? callback : typeof values === 'function' ? values : undefined;
+        if (cb) {
+            const wrappedCb = (err, res) => {
+                try {
+                    done(err, res);
+                }
+                catch { /* ignore */ }
+                cb(err, res);
+            };
+            return typeof values === 'function'
+                ? orig.call(this, config, wrappedCb)
+                : orig.call(this, config, values, wrappedCb);
+        }
+        const ret = orig.call(this, config, values);
+        if (ret && typeof ret.then === 'function') {
+            ret.then((res) => done(undefined, res), (err) => done(err, undefined));
+        }
+        return ret;
+    };
+    wrapped.__lensmcp = true;
+    proto['query'] = wrapped;
+    return true;
+}

package/lib/tap-redis.d.ts

@@ -0,0 +1,2 @@
+export declare function redisTap(exportsObject: unknown): boolean;
+//# sourceMappingURL=tap-redis.d.ts.map

package/lib/tap-redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-redis.d.ts","sourceRoot":"","sources":["../../src/lib/tap-redis.ts"],"names":[],"mappings":"AAyCA,wBAAgB,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAoBxD"}

package/lib/tap-redis.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redisTap = redisTap;
+/**
+ * ioredis tap (source `redis`): wraps `Redis.prototype.sendCommand` — the
+ * single funnel every command passes through. Emits kind `redis-op` with the
+ * `cache` role (matching the canvas's redis-by-role grouping).
+ *
+ * Two deliberate exclusions keep the picture truthful:
+ *  - BullMQ traffic (eval/evalsha + any `bull:`-prefixed key) is OWNED by the
+ *    queue tap — surfacing it here would paint the cache node with queue load.
+ *  - Housekeeping (info/ping/hello/…) says nothing about the app.
+ * A 30-events/sec cap protects the bus from hot loops; severity stays a
+ * sampling concern, not a correctness one (counts live in the dashboard).
+ */
+const emit_1 = require("./emit");
+const flow_context_1 = require("./flow-context");
+const HOUSEKEEPING = new Set([
+    'info', 'ping', 'hello', 'auth', 'select', 'client', 'cluster', 'command',
+    'subscribe', 'psubscribe', 'unsubscribe', 'punsubscribe', 'echo', 'quit',
+    'wait', 'script', 'config', 'debug', 'memory', 'readonly', 'readwrite',
+]);
+const MAX_PER_SEC = 30;
+let emitted = 0;
+let windowStart = 0;
+function isBullTraffic(command) {
+    const op = String(command.name ?? '').toLowerCase();
+    if (op === 'eval' || op === 'evalsha')
+        return true;
+    const args = command.args ?? [];
+    for (let i = 0; i < Math.min(args.length, 4); i++) {
+        const s = String(args[i] ?? '');
+        if (s.startsWith('bull:') || s.startsWith('{bull'))
+            return true;
+    }
+    return false;
+}
+function redisTap(exportsObject) {
+    const mod = exportsObject;
+    const Redis = (mod?.['default'] ?? mod);
+    const proto = Redis?.prototype;
+    const orig = proto?.['sendCommand'];
+    if (!proto || typeof orig !== 'function')
+        return false; // partial exports (circular require) — retry
+    if (orig.__lensmcp)
+        return true;
+    const wrapped = function (command, stream) {
+        const ret = orig.call(this, command, stream);
+        try {
+            observe(command);
+        }
+        catch {
+            /* never break redis */
+        }
+        return ret;
+    };
+    wrapped.__lensmcp = true;
+    proto['sendCommand'] = wrapped;
+    return true;
+}
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+/** The actual command line, values size-annotated: `SET me:default …(1.2kb) EX 15`. */
+function commandLine(op, args) {
+    const parts = args.slice(0, 6).map((a, i) => {
+        const s = String(a ?? '');
+        // first arg is the key — keep it readable; long VALUES become size notes
+        if (i > 0 && s.length > 48)
+            return `…(${(s.length / 1024).toFixed(1)}kb)`;
+        return clip(s, 64);
+    });
+    return [op.toUpperCase(), ...parts].join(' ');
+}
+function observe(command) {
+    const op = String(command?.name ?? '').toLowerCase();
+    if (!op || HOUSEKEEPING.has(op) || isBullTraffic(command))
+        return;
+    // Count EVERY real op for the loop detector BEFORE the event-rate cap — the
+    // cap throttles bus chatter, but a 200-GET fan-out must still register as
+    // 200 calls (capping the counter would blind the N+1 detector at peak load).
+    const live = (0, flow_context_1.liveFlowContext)();
+    if (live)
+        live.redisCallCount = (live.redisCallCount ?? 0) + 1;
+    const now = Date.now();
+    if (now - windowStart > 1000) {
+        windowStart = now;
+        emitted = 0;
+    }
+    if (++emitted > MAX_PER_SEC)
+        return;
+    const args = command?.args ?? [];
+    const key = String(args[0] ?? '');
+    const ctx = (0, flow_context_1.flowContext)(); // snapshot at SEND time — the request's ALS scope
+    const cmd = commandLine(op, args);
+    const base = {
+        name: 'cache', kind: 'redis-op', op, key, command: cmd, startedAt: now,
+    };
+    if (op === 'get' && command.promise && typeof command.promise.then === 'function') {
+        const t0 = now;
+        command.promise.then((res) => {
+            const hit = res != null;
+            (0, emit_1.lensEmit)('redis', 'info', `cache ${hit ? 'hit' : 'miss'} ${key}`, {
+                ...base, hit, durationMs: Date.now() - t0,
+                ...(hit ? { value: clip(String(res), 120) } : {}),
+            }, 'redis:cache', ctx);
+        }, () => { });
+        return;
+    }
+    if (op === 'set') {
+        const strArgs = args.map((a) => String(a));
+        const exIdx = strArgs.findIndex((a) => a.toUpperCase() === 'EX');
+        const ttlSec = exIdx >= 0 ? Number(strArgs[exIdx + 1]) : undefined;
+        (0, emit_1.lensEmit)('redis', 'info', ttlSec ? `cache set ${key} (ttl ${ttlSec}s)` : `cache set ${key}`, {
+            ...base, ...(ttlSec ? { ttlSec } : {}),
+        }, 'redis:cache', ctx);
+        return;
+    }
+    (0, emit_1.lensEmit)('redis', 'info', `cache ${op} ${key}`, base, 'redis:cache', ctx);
+}

package/lib/tap-stdout.d.ts

@@ -0,0 +1,2 @@
+export declare function tapStdout(): void;
+//# sourceMappingURL=tap-stdout.d.ts.map

package/lib/tap-stdout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-stdout.d.ts","sourceRoot":"","sources":["../../src/lib/tap-stdout.ts"],"names":[],"mappings":"AAuCA,wBAAgB,SAAS,IAAI,IAAI,CA0BhC"}

package/lib/tap-stdout.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tapStdout = tapStdout;
+/**
+ * stdout/stderr tap — the service's ACTUAL log output (the Nest `Logger`,
+ * `console`, raw writes — exactly what shows in the pod terminal) mirrored into
+ * the lens as `runtime` log events, so it surfaces in the dashboard Logs view.
+ *
+ * The original write still runs (terminal output is unchanged), and `[lensmcp]`
+ * lines are skipped so the lens never feeds on its own chatter. The emit path is
+ * fs-tap-safe (lensLog binds the pristine appendFileSync + sets `isLensWriting`),
+ * so a log line can never recurse into instrumentation. Disable with LENSMCP_LOGS=0.
+ */
+const emit_1 = require("./emit");
+// Strip ANSI SGR colour codes (Nest's colourised ConsoleLogger). Build the ESC
+// byte at runtime so there's no control character literal in source.
+const ANSI = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g');
+/** Best-effort level from a Nest-formatted line; falls back to the stream default. */
+function severityOf(line, fallback) {
+    if (/\bFATAL\b/.test(line))
+        return 'fatal';
+    if (/\bERROR\b/.test(line))
+        return 'error';
+    if (/\bWARN\b/.test(line))
+        return 'warning';
+    if (/\bDEBUG\b/.test(line) || /\bVERBOSE\b/.test(line))
+        return 'debug';
+    if (/\bLOG\b/.test(line))
+        return 'info';
+    return fallback;
+}
+function emitChunk(s, fallback) {
+    for (const rawLine of s.split('\n')) {
+        const line = rawLine.replace(ANSI, '').replace(/\s+$/, '');
+        if (!line.trim())
+            continue;
+        (0, emit_1.lensLog)(severityOf(line, fallback), line);
+    }
+}
+function tapStdout() {
+    if (process.env['LENSMCP_LOGS'] === '0')
+        return;
+    // Only tap ACTUAL service pods (APP_RUNNER=1) — never the gateway/devserver parent,
+    // whose high-volume proxy logging would swamp the bus with synchronous appends.
+    if (process.env['APP_RUNNER'] !== '1')
+        return;
+    const targets = [
+        [process.stdout, 'info'],
+        [process.stderr, 'error'],
+    ];
+    for (const [stream, fallback] of targets) {
+        if (stream.write.__lensmcp)
+            continue;
+        const orig = stream.write.bind(stream);
+        const wrapped = function (chunk, ...args) {
+            try {
+                if (!(0, emit_1.isLensWriting)()) {
+                    const s = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) ? chunk.toString('utf8') : '';
+                    if (s && s.indexOf('[lensmcp]') === -1)
+                        emitChunk(s, fallback);
+                }
+            }
+            catch {
+                /* never break the host's stdout */
+            }
+            return orig(chunk, ...args);
+        };
+        wrapped.__lensmcp = true;
+        stream.write = wrapped;
+    }
+}