@lensmcp/core 1.0.0

package/lib/resource-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-store.d.ts","sourceRoot":"","sources":["../../src/lib/resource-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAC5E,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAS7E;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkD;IAEvE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,WAAW;IAWvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAM/C,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIzC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,WAAW;CAWrE"}

package/lib/resource-store.js

@@ -0,0 +1,71 @@
+/**
+ * The resource store. URIs are registered once; reading is cheap; the
+ * `markDirty` call bumps the revision counter and notifies subscribers
+ * only when the produced JSON actually changes (diff-aware).
+ */
+export class ResourceStore {
+    constructor() {
+        this.entries = new Map();
+        this.subs = new Map();
+    }
+    register(uri, produce) {
+        if (this.entries.has(uri)) {
+            throw new Error(`Resource already registered: ${uri}`);
+        }
+        this.entries.set(uri, { uri, produce, revision: 0 });
+        return () => {
+            this.entries.delete(uri);
+            this.subs.delete(uri);
+        };
+    }
+    async read(uri) {
+        const entry = this.entries.get(uri);
+        if (!entry)
+            throw new Error(`Unknown resource: ${uri}`);
+        return entry.produce();
+    }
+    list() {
+        return [...this.entries.keys()];
+    }
+    /**
+     * Recompute the JSON, bump the revision counter if it differs, and
+     * notify subscribers. No-op if the URI is unknown or the JSON didn't
+     * change.
+     */
+    async markDirty(uri) {
+        const entry = this.entries.get(uri);
+        if (!entry)
+            return;
+        const next = await entry.produce();
+        const serialised = JSON.stringify(next);
+        if (serialised === entry.lastJson)
+            return;
+        entry.lastJson = serialised;
+        entry.revision += 1;
+        const handlers = this.subs.get(uri);
+        if (handlers) {
+            for (const h of handlers) {
+                try {
+                    h(uri, entry.revision);
+                }
+                catch {
+                    /* swallow handler errors */
+                }
+            }
+        }
+    }
+    revision(uri) {
+        return this.entries.get(uri)?.revision;
+    }
+    subscribe(uri, handler) {
+        let set = this.subs.get(uri);
+        if (!set) {
+            set = new Set();
+            this.subs.set(uri, set);
+        }
+        set.add(handler);
+        return () => {
+            set?.delete(handler);
+        };
+    }
+}

package/lib/story.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Story compiler. Takes a set of `BaseEvent`s belonging to one
+ * `flowId`, sorts them by timestamp, and emits a `FlowStory` —
+ * a small declarative record of the phases the flow went through
+ * (user-action → loading-ui → backend-request → state-update →
+ * final-render). The output shape mirrors `02-data-model.md#story`.
+ */
+import type { BaseEvent } from '@lensmcp/protocol-types';
+export type StoryPhaseKind = 'user-action' | 'loading-ui' | 'idle-ui' | 'route-transition' | 'state-update' | 'backend-request' | 'render' | 'final-render' | 'visual-violation';
+export interface StoryPhase {
+    kind: StoryPhaseKind;
+    at: number;
+    /** Human-friendly label used in `story://` summaries. */
+    label: string;
+    /** Optional refs back to the underlying events. */
+    eventIds: string[];
+    details?: Record<string, unknown>;
+}
+export interface FlowStory {
+    flowId: string;
+    origin: {
+        type?: string;
+        nodeId?: string;
+        at: number;
+    };
+    phases: StoryPhase[];
+    /** Final stable state summary (last render commit + last visual frame). */
+    finalState?: {
+        page?: string;
+        route?: string;
+        componentName?: string;
+        renderId?: string;
+        visualFrameId?: string;
+    };
+    startedAt: number;
+    endedAt: number;
+    eventCount: number;
+}
+export interface CompileStoryOptions {
+    /** Trim events outside the supplied flow id; defaults to scanning all. */
+    flowId?: string;
+}
+/** Group events by `context.flowId`. Events without a flowId are dropped. */
+export declare function groupByFlow(events: readonly BaseEvent[]): Map<string, BaseEvent[]>;
+/**
+ * Compile a single flow's events into a `FlowStory`. The caller can
+ * either pre-filter events (preferred) or pass everything and supply
+ * `options.flowId`.
+ */
+export declare function compileStory(events: readonly BaseEvent[], options?: CompileStoryOptions): FlowStory | undefined;
+//# sourceMappingURL=story.d.ts.map

package/lib/story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/lib/story.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,YAAY,GACZ,SAAS,GACT,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,QAAQ,GACR,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IACF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAalF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,GAAE,mBAAwB,GAChC,SAAS,GAAG,SAAS,CA4EvB"}

package/lib/story.js

@@ -0,0 +1,191 @@
+/** Group events by `context.flowId`. Events without a flowId are dropped. */
+export function groupByFlow(events) {
+    const out = new Map();
+    for (const e of events) {
+        const flowId = e.context.flowId;
+        if (!flowId)
+            continue;
+        let arr = out.get(flowId);
+        if (!arr) {
+            arr = [];
+            out.set(flowId, arr);
+        }
+        arr.push(e);
+    }
+    return out;
+}
+/**
+ * Compile a single flow's events into a `FlowStory`. The caller can
+ * either pre-filter events (preferred) or pass everything and supply
+ * `options.flowId`.
+ */
+export function compileStory(events, options = {}) {
+    let pool;
+    let flowId;
+    if (options.flowId) {
+        flowId = options.flowId;
+        pool = events.filter((e) => e.context.flowId === flowId);
+    }
+    else {
+        const first = events.find((e) => e.context.flowId);
+        if (!first)
+            return undefined;
+        flowId = first.context.flowId;
+        pool = events.filter((e) => e.context.flowId === flowId);
+    }
+    if (pool.length === 0)
+        return undefined;
+    pool.sort((a, b) => a.timestamp - b.timestamp);
+    const origin = pool[0];
+    const phases = [];
+    let finalRender;
+    let finalVisualFrame;
+    for (const event of pool) {
+        const phase = classifyEvent(event);
+        if (!phase)
+            continue;
+        phases.push(phase);
+        if (phase.kind === 'render' || phase.kind === 'final-render') {
+            const raw = event.raw;
+            if (raw?.render) {
+                finalRender = {
+                    id: raw.render.id,
+                    page: raw.render.page,
+                    route: raw.render.route,
+                    componentName: raw.render.componentName,
+                };
+            }
+        }
+        else if (event.source === 'visual' && phase.kind === 'visual-violation') {
+            const raw = event.raw;
+            if (raw?.frame)
+                finalVisualFrame = raw.frame.id;
+        }
+    }
+    // Promote the final `render` phase (if any) to `final-render`.
+    for (let i = phases.length - 1; i >= 0; i--) {
+        if (phases[i].kind === 'render') {
+            phases[i] = { ...phases[i], kind: 'final-render' };
+            break;
+        }
+    }
+    const startedAt = pool[0].timestamp;
+    const endedAt = pool[pool.length - 1].timestamp;
+    return {
+        flowId,
+        origin: {
+            type: origin.context.originType,
+            nodeId: origin.context.originNodeId,
+            at: origin.timestamp,
+        },
+        phases,
+        finalState: finalRender
+            ? {
+                page: finalRender.page,
+                route: finalRender.route,
+                componentName: finalRender.componentName,
+                renderId: finalRender.id,
+                visualFrameId: finalVisualFrame,
+            }
+            : undefined,
+        startedAt,
+        endedAt,
+        eventCount: pool.length,
+    };
+}
+/**
+ * Classify a single event into a story phase. Returns undefined for
+ * events that don't carry phase semantics (we still keep them under
+ * `flow://flow/{flowId}.events` but don't surface them in the story).
+ */
+function classifyEvent(event) {
+    const raw = (event.raw ?? null);
+    const kind = raw?.kind;
+    // Flow origin events (synthetic user-action emitter)
+    if (kind === 'flow-origin' || (event.source === 'client-runtime' && kind === 'user-action')) {
+        const r = event.raw;
+        return {
+            kind: 'user-action',
+            at: event.timestamp,
+            label: r?.origin?.label ?? event.title,
+            eventIds: [event.id],
+        };
+    }
+    // React renders
+    if (event.source === 'react' && kind === 'render') {
+        const r = event.raw;
+        return {
+            kind: 'render',
+            at: event.timestamp,
+            label: `render ${r?.render?.componentName ?? '?'}`,
+            eventIds: [event.id],
+            details: r?.render
+                ? { componentName: r.render.componentName, durationMs: r.render.actualDurationMs }
+                : undefined,
+        };
+    }
+    // Slot transitions (loading / idle UI)
+    if (event.source === 'react' && kind === 'slot-content-changed') {
+        const r = event.raw;
+        const to = r?.slot?.toComponent ?? '?';
+        const isLoading = /spinner|loader|loading/i.test(to);
+        return {
+            kind: isLoading ? 'loading-ui' : 'idle-ui',
+            at: event.timestamp,
+            label: `slot ${r?.slot?.slotLogicalId ?? ''} → ${to}`,
+            eventIds: [event.id],
+        };
+    }
+    // Route transitions (client-runtime emits)
+    if (event.source === 'client-runtime' && kind === 'route') {
+        const r = event.raw;
+        return {
+            kind: 'route-transition',
+            at: event.timestamp,
+            label: `route ${r?.from ?? ''} → ${r?.url ?? ''}`,
+            eventIds: [event.id],
+        };
+    }
+    // Valtio state-update
+    if (event.source === 'valtio' && kind === 'state-update') {
+        const r = event.raw;
+        return {
+            kind: 'state-update',
+            at: event.timestamp,
+            label: `${r?.update?.storeId ?? '?'}.${r?.update?.path ?? '?'}`,
+            eventIds: [event.id],
+            details: r?.update,
+        };
+    }
+    // Backend (NestJS) server-request
+    if (event.source === 'nestjs' && kind === 'server-request') {
+        const r = event.raw;
+        return {
+            kind: 'backend-request',
+            at: event.timestamp,
+            label: `${r?.request?.method ?? '?'} ${r?.request?.route ?? '?'} → ${r?.request?.status ?? '?'}`,
+            eventIds: [event.id],
+            details: r?.request,
+        };
+    }
+    // Chrome fetch (browser side) — synthesised by client-runtime.
+    if (event.source === 'chrome' && event.category === 'network') {
+        return {
+            kind: 'backend-request',
+            at: event.timestamp,
+            label: event.title,
+            eventIds: [event.id],
+        };
+    }
+    // Visual violations
+    if (event.source === 'visual' && kind === 'visual-violation') {
+        const r = event.raw;
+        return {
+            kind: 'visual-violation',
+            at: event.timestamp,
+            label: `${r?.violation?.ruleType ?? 'rule'} ${r?.violation?.ruleId ?? ''}`,
+            eventIds: [event.id],
+        };
+    }
+    return undefined;
+}

package/lib/thresholds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tunable thresholds that decide when a signal/channel fires. Defaults
+ * live here; a workspace overrides any subset via `nx.json#lensmcp.thresholds`,
+ * which the server loads at boot and threads into the reducers/detectors.
+ *
+ * Pure + isomorphic (no node APIs) so the detectors in `patterns.ts` and the
+ * reducers can both depend on it.
+ */
+export interface LensmcpThresholds {
+    /** DB calls inside one loop before `db-in-loop` fires. Default 5. */
+    dbInLoop: number;
+    /** Identical query repeats before `n+1-query` fires. Default 3. */
+    nPlusOne: number;
+    /** Renders of one component (per window) before `render-storm` fires. Default 5. */
+    renderStorm: number;
+    /** Server route durationMs at/above which it's "slow". Default 500. */
+    slowRouteMs: number;
+    /** React render durationMs at/above which it's "slow". Default 16. */
+    slowRenderMs: number;
+}
+export declare const DEFAULT_THRESHOLDS: LensmcpThresholds;
+/**
+ * Merge partial overrides over the defaults, ignoring any non-finite /
+ * non-numeric values (so a malformed config can't disable detection).
+ */
+export declare function resolveThresholds(overrides?: Partial<LensmcpThresholds> | null): LensmcpThresholds;
+//# sourceMappingURL=thresholds.d.ts.map

package/lib/thresholds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.d.ts","sourceRoot":"","sources":["../../src/lib/thresholds.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,EAAE,iBAMhC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,GAC5C,iBAAiB,CAWnB"}

package/lib/thresholds.js

@@ -0,0 +1,23 @@
+export const DEFAULT_THRESHOLDS = {
+    dbInLoop: 5,
+    nPlusOne: 3,
+    renderStorm: 5,
+    slowRouteMs: 500,
+    slowRenderMs: 16,
+};
+/**
+ * Merge partial overrides over the defaults, ignoring any non-finite /
+ * non-numeric values (so a malformed config can't disable detection).
+ */
+export function resolveThresholds(overrides) {
+    const out = { ...DEFAULT_THRESHOLDS };
+    if (overrides) {
+        for (const key of Object.keys(DEFAULT_THRESHOLDS)) {
+            const v = overrides[key];
+            if (typeof v === 'number' && Number.isFinite(v) && v >= 0) {
+                out[key] = v;
+            }
+        }
+    }
+    return out;
+}

package/lib/ulid.d.ts

@@ -0,0 +1,2 @@
+export declare function ulid(now?: number): string;
+//# sourceMappingURL=ulid.d.ts.map

package/lib/ulid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../../src/lib/ulid.ts"],"names":[],"mappings":"AAiCA,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAErD"}

package/lib/ulid.js

@@ -0,0 +1,32 @@
+/**
+ * Tiny dependency-free ULID-like ID generator.
+ *
+ * Real ULIDs are 26 chars Crockford-Base32. Ours are 26 chars of the same
+ * alphabet for compatibility, with the 48-bit timestamp prefix and 80
+ * bits of `crypto.getRandomValues` randomness. Sortable by creation time.
+ */
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const RANDOM_LEN = 16;
+function encodeTime(now, len) {
+    let out = '';
+    let n = now;
+    for (let i = len - 1; i >= 0; i--) {
+        const mod = n % 32;
+        out = ALPHABET[mod] + out;
+        n = (n - mod) / 32;
+    }
+    return out;
+}
+function encodeRandom(len) {
+    const bytes = new Uint8Array(len);
+    // Node 24 has global crypto; this is also fine in modern browsers.
+    globalThis.crypto.getRandomValues(bytes);
+    let out = '';
+    for (let i = 0; i < len; i++) {
+        out += ALPHABET[(bytes[i] ?? 0) & 31];
+    }
+    return out;
+}
+export function ulid(now = Date.now()) {
+    return encodeTime(now, 10) + encodeRandom(RANDOM_LEN);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lensmcp/core",
+  "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/protocol-types": "1.0.0",
+    "tslib": "^2.3.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": "LensMCP core — event bus, resource store, graph store, and pattern detectors.",
+  "keywords": [
+    "lensmcp",
+    "mcp",
+    "observability",
+    "ai-agents",
+    "claude",
+    "core"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiwiapps-ltd/lensmcp.git",
+    "directory": "libs/core"
+  }
+}