enpilink 1.0.2

package/dist/server/analytics.js

@@ -0,0 +1,168 @@
+import { setActiveStorage } from "./log-sink.js";
+import { seedMockData } from "./mock-seed.js";
+import { initOtel } from "./otel.js";
+import { resolveStorageAdapter } from "./storage/index.js";
+import { MemoryStorageAdapter } from "./storage/memory.js";
+/**
+ * Resolve a storage adapter for the session. In `--mock` mode we force an
+ * in-memory adapter (the demo seed must never touch disk and must vanish on
+ * exit); otherwise the configured `ENPILINK_STORAGE` adapter is used.
+ */
+function resolveSessionStorage(mock) {
+    return mock ? new MemoryStorageAdapter() : resolveStorageAdapter();
+}
+/** Truthy values that enable analytics via {@link analyticsEnabled}. */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/**
+ * Whether analytics is enabled. OFF by default; enable with
+ * `ENPILINK_ANALYTICS=1` (also accepts `true`/`yes`/`on`, case-insensitive).
+ */
+export function analyticsEnabled() {
+    const raw = process.env.ENPILINK_ANALYTICS;
+    return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());
+}
+/**
+ * Whether the `--mock` demo seed is enabled (`ENPILINK_MOCK`=1/true/yes/on).
+ * Mock mode is opt-in only and IMPLIES analytics-on + in-memory storage for the
+ * session, so the Dashboard renders full demo data with NO real traffic. It
+ * NEVER touches disk and is never on by default.
+ */
+export function mockEnabled() {
+    // The demo seed is DEV-ONLY: it must never seed a real deployment. In
+    // production `ENPILINK_MOCK` is ignored entirely (read the literal so the
+    // guard survives DCE and is unambiguous).
+    if (process.env.NODE_ENV === "production") {
+        return false;
+    }
+    const raw = process.env.ENPILINK_MOCK;
+    return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());
+}
+/**
+ * Extract the tool name from a `tools/call` request's params. Returns
+ * `undefined` for non-`tools/call` methods or malformed params, never throws.
+ */
+function toolNameOf(method, params) {
+    if (method !== "tools/call") {
+        return undefined;
+    }
+    const name = params?.name;
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * Build the analytics middleware entry. Times each request around `next()`,
+ * records a `tool_call`-typed event (capturing the tool name for `tools/call`),
+ * and ALWAYS swallows storage errors so a storage failure can never break or
+ * slow a tool call. Recording is fire-and-forget (non-blocking).
+ */
+export function createAnalyticsMiddleware(storage, now = Date.now, otel = null) {
+    return async (request, _extra, next) => {
+        const start = now();
+        const tool = toolNameOf(request.method, request.params);
+        let ok = true;
+        let error;
+        try {
+            const result = await next();
+            // A tool result with `isError: true` is a soft (handled) failure.
+            if (result &&
+                typeof result === "object" &&
+                result.isError === true) {
+                ok = false;
+            }
+            return result;
+        }
+        catch (err) {
+            // Record the failure, then rethrow so behavior is unchanged.
+            ok = false;
+            error = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+        finally {
+            const ms = now() - start;
+            const event = {
+                ts: start,
+                type: "tool_call",
+                tool,
+                method: request.method,
+                ms,
+                ok,
+                error,
+            };
+            // Fire-and-forget; never block or throw into the request path.
+            void recordSafely(storage, event);
+            // Optional OTel export — guarded, synchronous, error-swallowing.
+            if (otel) {
+                try {
+                    otel.record(event);
+                }
+                catch {
+                    // OTel export must never break or slow a tool call.
+                }
+            }
+        }
+    };
+}
+/** Record an event, swallowing any storage error. */
+async function recordSafely(storage, event) {
+    try {
+        await storage.recordEvent(event);
+    }
+    catch {
+        // A storage failure must never break or slow a tool call.
+    }
+}
+/**
+ * Install analytics on a server, ONLY when enabled (`ENPILINK_ANALYTICS`).
+ *
+ * When enabled: resolves a {@link StorageAdapter} via `resolveStorageAdapter()`
+ * (`ENPILINK_STORAGE` / `ENPILINK_DB_PATH`), `init()`s it, registers it as the
+ * active storage for the log sink + `getActiveStorage()`, and returns the
+ * built analytics middleware entry to splice into the chain.
+ *
+ * When disabled: resolves/initializes NOTHING and returns `null` — zero
+ * overhead, zero network, no `enpilink.db` created.
+ *
+ * @returns the active storage + middleware entry, or `null` when disabled.
+ */
+export async function installAnalytics(opts = {}) {
+    // `--mock` (ENPILINK_MOCK) force-enables analytics for the session even when
+    // the env-based gating is off, so demos work without setting both flags.
+    const mock = mockEnabled();
+    if (!mock && !analyticsEnabled()) {
+        return null;
+    }
+    let storage;
+    try {
+        storage = resolveSessionStorage(mock);
+        await storage.init();
+    }
+    catch (err) {
+        // Never let an analytics/storage failure break server startup.
+        console.error("[enpilink] analytics disabled: storage init failed:", err instanceof Error ? err.message : err);
+        return null;
+    }
+    setActiveStorage(storage);
+    // In `--mock` mode, seed the in-memory storage with a deterministic demo
+    // dataset so the Dashboard renders full immediately (no real traffic).
+    // Determinism: a fixed seed + a base timestamp captured once here.
+    if (mock) {
+        const now = (opts.now ?? Date.now)();
+        try {
+            await seedMockData(storage, { now });
+        }
+        catch {
+            // A seeding failure must never break server startup.
+        }
+    }
+    // Optional OTel export (M6): off by default, zero network/imports when unset.
+    // Initialized once here and fed by the middleware alongside storage. Mock mode
+    // never exports (it's dev-only demo data); requires the explicit env opt-in.
+    const otel = mock ? null : await initOtel();
+    const entry = {
+        // "request" matches every (non-notification) request so non-tool methods
+        // are counted too; the handler captures the tool name for tools/call.
+        filter: "request",
+        handler: createAnalyticsMiddleware(storage, opts.now, otel),
+    };
+    return { storage, entry, otel };
+}
+//# sourceMappingURL=analytics.js.map

package/dist/server/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/server/analytics.ts"],"names":[],"mappings":"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","sourcesContent":["import { setActiveStorage } from \"./log-sink.js\";\nimport type { McpMiddlewareEntry, McpMiddlewareFn } from \"./middleware.js\";\nimport { seedMockData } from \"./mock-seed.js\";\nimport { initOtel, type OtelSink } from \"./otel.js\";\nimport { resolveStorageAdapter } from \"./storage/index.js\";\nimport { MemoryStorageAdapter } from \"./storage/memory.js\";\nimport type { StorageAdapter } from \"./storage/types.js\";\n\n/**\n * Analytics + log capture (M2). Opt-in, env-gated, zero overhead when off.\n *\n * When enabled, a single {@link StorageAdapter} is resolved + `init()`ed at\n * server startup and shared in-process: the analytics middleware writes\n * `tool_call` events to it, the log sink mirrors server logs to it, and (M3)\n * the observability API reads from the very same instance via the\n * `server.storage` getter or {@link getActiveStorage}.\n *\n * Gating: OFF unless `ENPILINK_ANALYTICS` is `1` or `true` (case-insensitive).\n * When OFF, no adapter is resolved or initialized (so no `enpilink.db` is\n * created), no middleware is registered, and there is zero network activity.\n */\n\n/** Options for {@link installAnalytics}. */\nexport interface InstallAnalyticsOptions {\n  /**\n   * Inject a clock for deterministic tests. Defaults to `Date.now`.\n   */\n  now?: () => number;\n}\n\n/**\n * Resolve a storage adapter for the session. In `--mock` mode we force an\n * in-memory adapter (the demo seed must never touch disk and must vanish on\n * exit); otherwise the configured `ENPILINK_STORAGE` adapter is used.\n */\nfunction resolveSessionStorage(mock: boolean): StorageAdapter {\n  return mock ? new MemoryStorageAdapter() : resolveStorageAdapter();\n}\n\n/** Truthy values that enable analytics via {@link analyticsEnabled}. */\nconst TRUTHY = new Set([\"1\", \"true\", \"yes\", \"on\"]);\n\n/**\n * Whether analytics is enabled. OFF by default; enable with\n * `ENPILINK_ANALYTICS=1` (also accepts `true`/`yes`/`on`, case-insensitive).\n */\nexport function analyticsEnabled(): boolean {\n  const raw = process.env.ENPILINK_ANALYTICS;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Whether the `--mock` demo seed is enabled (`ENPILINK_MOCK`=1/true/yes/on).\n * Mock mode is opt-in only and IMPLIES analytics-on + in-memory storage for the\n * session, so the Dashboard renders full demo data with NO real traffic. It\n * NEVER touches disk and is never on by default.\n */\nexport function mockEnabled(): boolean {\n  // The demo seed is DEV-ONLY: it must never seed a real deployment. In\n  // production `ENPILINK_MOCK` is ignored entirely (read the literal so the\n  // guard survives DCE and is unambiguous).\n  if (process.env.NODE_ENV === \"production\") {\n    return false;\n  }\n  const raw = process.env.ENPILINK_MOCK;\n  return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n\n/**\n * Extract the tool name from a `tools/call` request's params. Returns\n * `undefined` for non-`tools/call` methods or malformed params, never throws.\n */\nfunction toolNameOf(\n  method: string,\n  params: Record<string, unknown>,\n): string | undefined {\n  if (method !== \"tools/call\") {\n    return undefined;\n  }\n  const name = params?.name;\n  return typeof name === \"string\" ? name : undefined;\n}\n\n/**\n * Build the analytics middleware entry. Times each request around `next()`,\n * records a `tool_call`-typed event (capturing the tool name for `tools/call`),\n * and ALWAYS swallows storage errors so a storage failure can never break or\n * slow a tool call. Recording is fire-and-forget (non-blocking).\n */\nexport function createAnalyticsMiddleware(\n  storage: StorageAdapter,\n  now: () => number = Date.now,\n  otel: OtelSink | null = null,\n): McpMiddlewareFn {\n  return async (request, _extra, next) => {\n    const start = now();\n    const tool = toolNameOf(request.method, request.params);\n    let ok = true;\n    let error: string | undefined;\n\n    try {\n      const result = await next();\n      // A tool result with `isError: true` is a soft (handled) failure.\n      if (\n        result &&\n        typeof result === \"object\" &&\n        (result as { isError?: unknown }).isError === true\n      ) {\n        ok = false;\n      }\n      return result;\n    } catch (err) {\n      // Record the failure, then rethrow so behavior is unchanged.\n      ok = false;\n      error = err instanceof Error ? err.message : String(err);\n      throw err;\n    } finally {\n      const ms = now() - start;\n      const event = {\n        ts: start,\n        type: \"tool_call\",\n        tool,\n        method: request.method,\n        ms,\n        ok,\n        error,\n      } as const;\n      // Fire-and-forget; never block or throw into the request path.\n      void recordSafely(storage, event);\n      // Optional OTel export — guarded, synchronous, error-swallowing.\n      if (otel) {\n        try {\n          otel.record(event);\n        } catch {\n          // OTel export must never break or slow a tool call.\n        }\n      }\n    }\n  };\n}\n\n/** Record an event, swallowing any storage error. */\nasync function recordSafely(\n  storage: StorageAdapter,\n  event: Parameters<StorageAdapter[\"recordEvent\"]>[0],\n): Promise<void> {\n  try {\n    await storage.recordEvent(event);\n  } catch {\n    // A storage failure must never break or slow a tool call.\n  }\n}\n\n/**\n * Install analytics on a server, ONLY when enabled (`ENPILINK_ANALYTICS`).\n *\n * When enabled: resolves a {@link StorageAdapter} via `resolveStorageAdapter()`\n * (`ENPILINK_STORAGE` / `ENPILINK_DB_PATH`), `init()`s it, registers it as the\n * active storage for the log sink + `getActiveStorage()`, and returns the\n * built analytics middleware entry to splice into the chain.\n *\n * When disabled: resolves/initializes NOTHING and returns `null` — zero\n * overhead, zero network, no `enpilink.db` created.\n *\n * @returns the active storage + middleware entry, or `null` when disabled.\n */\nexport async function installAnalytics(\n  opts: InstallAnalyticsOptions = {},\n): Promise<{\n  storage: StorageAdapter;\n  entry: McpMiddlewareEntry;\n  otel: OtelSink | null;\n} | null> {\n  // `--mock` (ENPILINK_MOCK) force-enables analytics for the session even when\n  // the env-based gating is off, so demos work without setting both flags.\n  const mock = mockEnabled();\n  if (!mock && !analyticsEnabled()) {\n    return null;\n  }\n\n  let storage: StorageAdapter;\n  try {\n    storage = resolveSessionStorage(mock);\n    await storage.init();\n  } catch (err) {\n    // Never let an analytics/storage failure break server startup.\n    console.error(\n      \"[enpilink] analytics disabled: storage init failed:\",\n      err instanceof Error ? err.message : err,\n    );\n    return null;\n  }\n\n  setActiveStorage(storage);\n\n  // In `--mock` mode, seed the in-memory storage with a deterministic demo\n  // dataset so the Dashboard renders full immediately (no real traffic).\n  // Determinism: a fixed seed + a base timestamp captured once here.\n  if (mock) {\n    const now = (opts.now ?? Date.now)();\n    try {\n      await seedMockData(storage, { now });\n    } catch {\n      // A seeding failure must never break server startup.\n    }\n  }\n\n  // Optional OTel export (M6): off by default, zero network/imports when unset.\n  // Initialized once here and fed by the middleware alongside storage. Mock mode\n  // never exports (it's dev-only demo data); requires the explicit env opt-in.\n  const otel = mock ? null : await initOtel();\n\n  const entry: McpMiddlewareEntry = {\n    // \"request\" matches every (non-notification) request so non-tool methods\n    // are counted too; the handler captures the tool name for tools/call.\n    filter: \"request\",\n    handler: createAnalyticsMiddleware(storage, opts.now, otel),\n  };\n\n  return { storage, entry, otel };\n}\n"]}

package/dist/server/analytics.test.d.ts

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

package/dist/server/analytics.test.js

@@ -0,0 +1,179 @@
+import { existsSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { analyticsEnabled, createAnalyticsMiddleware, installAnalytics, } from "./analytics.js";
+import { getActiveStorage, serverLog, setActiveStorage } from "./log-sink.js";
+import { MemoryStorageAdapter } from "./storage/memory.js";
+/** Flush the fire-and-forget recordEvent/appendLog microtasks. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+/** A fixed clock: 1000 at start, +5ms on the second read. */
+function fixedClock() {
+    const ticks = [1000, 1005];
+    let i = 0;
+    return () => ticks[Math.min(i++, ticks.length - 1)];
+}
+describe("analyticsEnabled", () => {
+    const original = process.env.ENPILINK_ANALYTICS;
+    afterEach(() => {
+        if (original === undefined) {
+            delete process.env.ENPILINK_ANALYTICS;
+        }
+        else {
+            process.env.ENPILINK_ANALYTICS = original;
+        }
+    });
+    it("is off by default", () => {
+        delete process.env.ENPILINK_ANALYTICS;
+        expect(analyticsEnabled()).toBe(false);
+    });
+    it("accepts 1/true/yes/on (case-insensitive)", () => {
+        for (const v of ["1", "true", "TRUE", "yes", "on", " True "]) {
+            process.env.ENPILINK_ANALYTICS = v;
+            expect(analyticsEnabled()).toBe(true);
+        }
+    });
+    it("rejects other values", () => {
+        for (const v of ["0", "false", "", "off", "no"]) {
+            process.env.ENPILINK_ANALYTICS = v;
+            expect(analyticsEnabled()).toBe(false);
+        }
+    });
+});
+describe("createAnalyticsMiddleware", () => {
+    let store;
+    beforeEach(async () => {
+        store = new MemoryStorageAdapter({ cap: 100 });
+        await store.init();
+    });
+    it("records a tool_call event on success with tool, ms, ok", async () => {
+        const mw = createAnalyticsMiddleware(store, fixedClock());
+        const result = { content: [{ type: "text", text: "hi" }] };
+        const ret = await mw({ method: "tools/call", params: { name: "greet" } }, undefined, async () => result);
+        await flush();
+        expect(ret).toBe(result);
+        const [e] = await store.queryEvents({});
+        expect(e).toMatchObject({
+            type: "tool_call",
+            tool: "greet",
+            method: "tools/call",
+            ms: 5,
+            ok: true,
+        });
+        expect(e?.ts).toBe(1000);
+        expect(e?.error).toBeUndefined();
+    });
+    it("records ok=false when the result has isError", async () => {
+        const mw = createAnalyticsMiddleware(store, fixedClock());
+        await mw({ method: "tools/call", params: { name: "boom" } }, undefined, async () => ({ isError: true, content: [] }));
+        await flush();
+        const [e] = await store.queryEvents({});
+        expect(e).toMatchObject({ tool: "boom", ok: false });
+    });
+    it("records the event AND rethrows on a thrown error", async () => {
+        const mw = createAnalyticsMiddleware(store, fixedClock());
+        await expect(mw({ method: "tools/call", params: { name: "kaboom" } }, undefined, async () => {
+            throw new Error("nope");
+        })).rejects.toThrow("nope");
+        await flush();
+        const [e] = await store.queryEvents({});
+        expect(e).toMatchObject({ tool: "kaboom", ok: false, error: "nope" });
+    });
+    it("captures the method but no tool for non-tools/call requests", async () => {
+        const mw = createAnalyticsMiddleware(store, fixedClock());
+        await mw({ method: "tools/list", params: {} }, undefined, async () => ({
+            tools: [],
+        }));
+        await flush();
+        const [e] = await store.queryEvents({});
+        expect(e?.method).toBe("tools/list");
+        expect(e?.tool).toBeUndefined();
+    });
+    it("never breaks the call when storage.recordEvent throws", async () => {
+        const broken = new MemoryStorageAdapter();
+        await broken.init();
+        broken.recordEvent = async () => {
+            throw new Error("storage down");
+        };
+        const mw = createAnalyticsMiddleware(broken, fixedClock());
+        const result = { content: [] };
+        await expect(mw({ method: "tools/call", params: { name: "x" } }, undefined, async () => result)).resolves.toBe(result);
+        await flush();
+    });
+});
+describe("installAnalytics gating", () => {
+    const originalAnalytics = process.env.ENPILINK_ANALYTICS;
+    const originalStorage = process.env.ENPILINK_STORAGE;
+    beforeEach(() => {
+        setActiveStorage(null);
+    });
+    afterEach(() => {
+        setActiveStorage(null);
+        if (originalAnalytics === undefined) {
+            delete process.env.ENPILINK_ANALYTICS;
+        }
+        else {
+            process.env.ENPILINK_ANALYTICS = originalAnalytics;
+        }
+        if (originalStorage === undefined) {
+            delete process.env.ENPILINK_STORAGE;
+        }
+        else {
+            process.env.ENPILINK_STORAGE = originalStorage;
+        }
+    });
+    it("returns null and creates no adapter when disabled", async () => {
+        delete process.env.ENPILINK_ANALYTICS;
+        const result = await installAnalytics();
+        expect(result).toBeNull();
+        expect(getActiveStorage()).toBeNull();
+    });
+    it("does NOT create a sqlite db file when disabled", async () => {
+        delete process.env.ENPILINK_ANALYTICS;
+        process.env.ENPILINK_STORAGE = "sqlite";
+        const dbPath = `${process.cwd()}/enpilink.db`;
+        const preexisting = existsSync(dbPath);
+        await installAnalytics();
+        if (!preexisting) {
+            expect(existsSync(dbPath)).toBe(false);
+        }
+    });
+    it("resolves + inits + registers the active storage when enabled", async () => {
+        process.env.ENPILINK_ANALYTICS = "1";
+        process.env.ENPILINK_STORAGE = "memory";
+        const result = await installAnalytics();
+        expect(result).not.toBeNull();
+        expect(result?.entry.filter).toBe("request");
+        expect(typeof result?.entry.handler).toBe("function");
+        expect(getActiveStorage()).toBe(result?.storage);
+        await result?.storage.close();
+    });
+});
+describe("serverLog capture", () => {
+    beforeEach(() => setActiveStorage(null));
+    afterEach(() => setActiveStorage(null));
+    it("is a no-op sink (no storage) when no active storage", () => {
+        expect(() => serverLog("info", "hello")).not.toThrow();
+    });
+    it("mirrors logs to the active storage when set", async () => {
+        const store = new MemoryStorageAdapter();
+        await store.init();
+        setActiveStorage(store);
+        serverLog("error", "boom", { code: 1 });
+        await flush();
+        const [l] = await store.queryLogs({});
+        expect(l).toMatchObject({ level: "error", msg: "boom" });
+        expect(l?.data).toEqual({ code: 1 });
+        await store.close();
+    });
+    it("swallows storage errors", async () => {
+        const store = new MemoryStorageAdapter();
+        await store.init();
+        store.appendLog = async () => {
+            throw new Error("down");
+        };
+        setActiveStorage(store);
+        expect(() => serverLog("info", "x")).not.toThrow();
+        await flush();
+        await store.close();
+    });
+});
+//# sourceMappingURL=analytics.test.js.map

package/dist/server/analytics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.test.js","sourceRoot":"","sources":["../../src/server/analytics.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\";\nimport { afterEach, beforeEach, describe, expect, it } from \"vitest\";\nimport {\n  analyticsEnabled,\n  createAnalyticsMiddleware,\n  installAnalytics,\n} from \"./analytics.js\";\nimport { getActiveStorage, serverLog, setActiveStorage } from \"./log-sink.js\";\nimport { MemoryStorageAdapter } from \"./storage/memory.js\";\nimport type { AnalyticsEvent } from \"./storage/types.js\";\n\n/** Flush the fire-and-forget recordEvent/appendLog microtasks. */\nconst flush = () => new Promise((r) => setTimeout(r, 0));\n\n/** A fixed clock: 1000 at start, +5ms on the second read. */\nfunction fixedClock(): () => number {\n  const ticks = [1000, 1005];\n  let i = 0;\n  return () => ticks[Math.min(i++, ticks.length - 1)] as number;\n}\n\ndescribe(\"analyticsEnabled\", () => {\n  const original = process.env.ENPILINK_ANALYTICS;\n  afterEach(() => {\n    if (original === undefined) {\n      delete process.env.ENPILINK_ANALYTICS;\n    } else {\n      process.env.ENPILINK_ANALYTICS = original;\n    }\n  });\n\n  it(\"is off by default\", () => {\n    delete process.env.ENPILINK_ANALYTICS;\n    expect(analyticsEnabled()).toBe(false);\n  });\n\n  it(\"accepts 1/true/yes/on (case-insensitive)\", () => {\n    for (const v of [\"1\", \"true\", \"TRUE\", \"yes\", \"on\", \" True \"]) {\n      process.env.ENPILINK_ANALYTICS = v;\n      expect(analyticsEnabled()).toBe(true);\n    }\n  });\n\n  it(\"rejects other values\", () => {\n    for (const v of [\"0\", \"false\", \"\", \"off\", \"no\"]) {\n      process.env.ENPILINK_ANALYTICS = v;\n      expect(analyticsEnabled()).toBe(false);\n    }\n  });\n});\n\ndescribe(\"createAnalyticsMiddleware\", () => {\n  let store: MemoryStorageAdapter;\n  beforeEach(async () => {\n    store = new MemoryStorageAdapter({ cap: 100 });\n    await store.init();\n  });\n\n  it(\"records a tool_call event on success with tool, ms, ok\", async () => {\n    const mw = createAnalyticsMiddleware(store, fixedClock());\n    const result = { content: [{ type: \"text\", text: \"hi\" }] };\n    const ret = await mw(\n      { method: \"tools/call\", params: { name: \"greet\" } },\n      undefined,\n      async () => result,\n    );\n    await flush();\n\n    expect(ret).toBe(result);\n    const [e] = await store.queryEvents({});\n    expect(e).toMatchObject<Partial<AnalyticsEvent>>({\n      type: \"tool_call\",\n      tool: \"greet\",\n      method: \"tools/call\",\n      ms: 5,\n      ok: true,\n    });\n    expect(e?.ts).toBe(1000);\n    expect(e?.error).toBeUndefined();\n  });\n\n  it(\"records ok=false when the result has isError\", async () => {\n    const mw = createAnalyticsMiddleware(store, fixedClock());\n    await mw(\n      { method: \"tools/call\", params: { name: \"boom\" } },\n      undefined,\n      async () => ({ isError: true, content: [] }),\n    );\n    await flush();\n    const [e] = await store.queryEvents({});\n    expect(e).toMatchObject({ tool: \"boom\", ok: false });\n  });\n\n  it(\"records the event AND rethrows on a thrown error\", async () => {\n    const mw = createAnalyticsMiddleware(store, fixedClock());\n    await expect(\n      mw(\n        { method: \"tools/call\", params: { name: \"kaboom\" } },\n        undefined,\n        async () => {\n          throw new Error(\"nope\");\n        },\n      ),\n    ).rejects.toThrow(\"nope\");\n    await flush();\n    const [e] = await store.queryEvents({});\n    expect(e).toMatchObject({ tool: \"kaboom\", ok: false, error: \"nope\" });\n  });\n\n  it(\"captures the method but no tool for non-tools/call requests\", async () => {\n    const mw = createAnalyticsMiddleware(store, fixedClock());\n    await mw({ method: \"tools/list\", params: {} }, undefined, async () => ({\n      tools: [],\n    }));\n    await flush();\n    const [e] = await store.queryEvents({});\n    expect(e?.method).toBe(\"tools/list\");\n    expect(e?.tool).toBeUndefined();\n  });\n\n  it(\"never breaks the call when storage.recordEvent throws\", async () => {\n    const broken = new MemoryStorageAdapter();\n    await broken.init();\n    broken.recordEvent = async () => {\n      throw new Error(\"storage down\");\n    };\n    const mw = createAnalyticsMiddleware(broken, fixedClock());\n    const result = { content: [] };\n    await expect(\n      mw(\n        { method: \"tools/call\", params: { name: \"x\" } },\n        undefined,\n        async () => result,\n      ),\n    ).resolves.toBe(result);\n    await flush();\n  });\n});\n\ndescribe(\"installAnalytics gating\", () => {\n  const originalAnalytics = process.env.ENPILINK_ANALYTICS;\n  const originalStorage = process.env.ENPILINK_STORAGE;\n\n  beforeEach(() => {\n    setActiveStorage(null);\n  });\n  afterEach(() => {\n    setActiveStorage(null);\n    if (originalAnalytics === undefined) {\n      delete process.env.ENPILINK_ANALYTICS;\n    } else {\n      process.env.ENPILINK_ANALYTICS = originalAnalytics;\n    }\n    if (originalStorage === undefined) {\n      delete process.env.ENPILINK_STORAGE;\n    } else {\n      process.env.ENPILINK_STORAGE = originalStorage;\n    }\n  });\n\n  it(\"returns null and creates no adapter when disabled\", async () => {\n    delete process.env.ENPILINK_ANALYTICS;\n    const result = await installAnalytics();\n    expect(result).toBeNull();\n    expect(getActiveStorage()).toBeNull();\n  });\n\n  it(\"does NOT create a sqlite db file when disabled\", async () => {\n    delete process.env.ENPILINK_ANALYTICS;\n    process.env.ENPILINK_STORAGE = \"sqlite\";\n    const dbPath = `${process.cwd()}/enpilink.db`;\n    const preexisting = existsSync(dbPath);\n    await installAnalytics();\n    if (!preexisting) {\n      expect(existsSync(dbPath)).toBe(false);\n    }\n  });\n\n  it(\"resolves + inits + registers the active storage when enabled\", async () => {\n    process.env.ENPILINK_ANALYTICS = \"1\";\n    process.env.ENPILINK_STORAGE = \"memory\";\n    const result = await installAnalytics();\n    expect(result).not.toBeNull();\n    expect(result?.entry.filter).toBe(\"request\");\n    expect(typeof result?.entry.handler).toBe(\"function\");\n    expect(getActiveStorage()).toBe(result?.storage);\n    await result?.storage.close();\n  });\n});\n\ndescribe(\"serverLog capture\", () => {\n  beforeEach(() => setActiveStorage(null));\n  afterEach(() => setActiveStorage(null));\n\n  it(\"is a no-op sink (no storage) when no active storage\", () => {\n    expect(() => serverLog(\"info\", \"hello\")).not.toThrow();\n  });\n\n  it(\"mirrors logs to the active storage when set\", async () => {\n    const store = new MemoryStorageAdapter();\n    await store.init();\n    setActiveStorage(store);\n    serverLog(\"error\", \"boom\", { code: 1 });\n    await flush();\n    const [l] = await store.queryLogs({});\n    expect(l).toMatchObject({ level: \"error\", msg: \"boom\" });\n    expect(l?.data).toEqual({ code: 1 });\n    await store.close();\n  });\n\n  it(\"swallows storage errors\", async () => {\n    const store = new MemoryStorageAdapter();\n    await store.init();\n    store.appendLog = async () => {\n      throw new Error(\"down\");\n    };\n    setActiveStorage(store);\n    expect(() => serverLog(\"info\", \"x\")).not.toThrow();\n    await flush();\n    await store.close();\n  });\n});\n"]}

package/dist/server/asset-base-url-transform-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "vite";
+export declare function isCssRequest(id: string): boolean;
+/**
+ * Transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`,
+ * so they work both locally and behind tunnels.
+ */
+export declare function assetBaseUrlTransform(code: string): string;
+/**
+ * Vite plugin that transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`.
+ */
+export declare function assetBaseUrlTransformPlugin(): Plugin;

package/dist/server/asset-base-url-transform-plugin.js

@@ -0,0 +1,48 @@
+// Mirrors Vite's own `isCSSRequest`: matches the css family of extensions
+// either at the end of the id or right before the query string. Catches both
+// plain `.css` requests and SFC style blocks (e.g. `Foo.vue?vue&type=style&lang.css`).
+const CSS_LANGS_RE = /\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)/;
+export function isCssRequest(id) {
+    return CSS_LANGS_RE.test(id);
+}
+/**
+ * Transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`,
+ * so they work both locally and behind tunnels.
+ */
+export function assetBaseUrlTransform(code) {
+    const assetStringPattern = /(?<!\bfrom\s)(?<!https?:\/\/)(["'`])(\/[^"'`]+\.(svg|png|jpeg|jpg|gif|webp|mp3|mp4|woff|woff2|ttf|eot))\1/g;
+    code = code.replace(assetStringPattern, (_match, _quote, assetPath) => {
+        return `(window.enpilink?.serverUrl ?? "") + "${assetPath}"`;
+    });
+    return code;
+}
+/**
+ * Vite plugin that transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`.
+ */
+export function assetBaseUrlTransformPlugin() {
+    return {
+        name: "asset-base-url-transform",
+        transform(code, id) {
+            if (!code) {
+                return null;
+            }
+            // Vite serves CSS modules as JS that embeds the stylesheet as a string
+            // literal. Rewriting `url("/foo.woff2")` inside that string to a JS
+            // concatenation expression produces invalid CSS once it lands in a
+            // <style> tag. CSS asset URLs are already handled at build time by
+            // `experimental.renderBuiltUrl`, so skip CSS requests here.
+            if (isCssRequest(id)) {
+                return null;
+            }
+            const transformedCode = assetBaseUrlTransform(code);
+            if (transformedCode === code) {
+                return null;
+            }
+            return {
+                code: transformedCode,
+                map: null,
+            };
+        },
+    };
+}
+//# sourceMappingURL=asset-base-url-transform-plugin.js.map

package/dist/server/asset-base-url-transform-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-base-url-transform-plugin.js","sourceRoot":"","sources":["../../src/server/asset-base-url-transform-plugin.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,6EAA6E;AAC7E,uFAAuF;AACvF,MAAM,YAAY,GAChB,6DAA6D,CAAC;AAEhE,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,kBAAkB,GACtB,4GAA4G,CAAC;IAE/G,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE;QACpE,OAAO,yCAAyC,SAAS,GAAG,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,SAAS,CAAC,IAAI,EAAE,EAAE;YAChB,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,IAAI,CAAC;YACd,CAAC;YAED,uEAAuE;YACvE,oEAAoE;YACpE,mEAAmE;YACnE,mEAAmE;YACnE,4DAA4D;YAC5D,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,eAAe,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAEpD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;gBAC7B,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,GAAG,EAAE,IAAI;aACV,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { Plugin } from \"vite\";\n\n// Mirrors Vite's own `isCSSRequest`: matches the css family of extensions\n// either at the end of the id or right before the query string. Catches both\n// plain `.css` requests and SFC style blocks (e.g. `Foo.vue?vue&type=style&lang.css`).\nconst CSS_LANGS_RE =\n  /\\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\\?)/;\n\nexport function isCssRequest(id: string): boolean {\n  return CSS_LANGS_RE.test(id);\n}\n\n/**\n * Transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`,\n * so they work both locally and behind tunnels.\n */\nexport function assetBaseUrlTransform(code: string): string {\n  const assetStringPattern =\n    /(?<!\\bfrom\\s)(?<!https?:\\/\\/)([\"'`])(\\/[^\"'`]+\\.(svg|png|jpeg|jpg|gif|webp|mp3|mp4|woff|woff2|ttf|eot))\\1/g;\n\n  code = code.replace(assetStringPattern, (_match, _quote, assetPath) => {\n    return `(window.enpilink?.serverUrl ?? \"\") + \"${assetPath}\"`;\n  });\n\n  return code;\n}\n\n/**\n * Vite plugin that transforms asset import paths to resolve at runtime via `window.enpilink.serverUrl`.\n */\nexport function assetBaseUrlTransformPlugin(): Plugin {\n  return {\n    name: \"asset-base-url-transform\",\n    transform(code, id) {\n      if (!code) {\n        return null;\n      }\n\n      // Vite serves CSS modules as JS that embeds the stylesheet as a string\n      // literal. Rewriting `url(\"/foo.woff2\")` inside that string to a JS\n      // concatenation expression produces invalid CSS once it lands in a\n      // <style> tag. CSS asset URLs are already handled at build time by\n      // `experimental.renderBuiltUrl`, so skip CSS requests here.\n      if (isCssRequest(id)) {\n        return null;\n      }\n\n      const transformedCode = assetBaseUrlTransform(code);\n\n      if (transformedCode === code) {\n        return null;\n      }\n\n      return {\n        code: transformedCode,\n        map: null,\n      };\n    },\n  };\n}\n"]}

package/dist/server/asset-base-url-transform-plugin.test.d.ts

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

package/dist/server/asset-base-url-transform-plugin.test.js

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { assetBaseUrlTransform, assetBaseUrlTransformPlugin, isCssRequest, } from "./asset-base-url-transform-plugin.js";
+describe("assetBaseUrlTransform", () => {
+    it("should transform asset paths to use window.enpilink.serverUrl", () => {
+        const cases = [
+            {
+                desc: "single-quoted",
+                code: `const image = '/assets/logo.png';`,
+                expected: `const image = (window.enpilink?.serverUrl ?? "") + "/assets/logo.png";`,
+            },
+            {
+                desc: "double-quoted",
+                code: `const image = "/assets/logo.png";`,
+                expected: `const image = (window.enpilink?.serverUrl ?? "") + "/assets/logo.png";`,
+            },
+            {
+                desc: "backtick-quoted",
+                code: "const image = `/assets/logo.png`;",
+                expected: `const image = (window.enpilink?.serverUrl ?? "") + "/assets/logo.png";`,
+            },
+        ];
+        for (const { code, expected } of cases) {
+            const result = assetBaseUrlTransform(code);
+            expect(result).toBe(expected);
+        }
+    });
+    it("should transform multiple asset paths", () => {
+        const code = `
+      const logo = '/assets/logo.png';
+      const icon = '/assets/icon.svg';
+      const font = '/assets/font.woff2';
+    `;
+        const result = assetBaseUrlTransform(code);
+        expect(result).toContain(`(window.enpilink?.serverUrl ?? "") + "/assets/logo.png"`);
+        expect(result).toContain(`(window.enpilink?.serverUrl ?? "") + "/assets/icon.svg"`);
+        expect(result).toContain(`(window.enpilink?.serverUrl ?? "") + "/assets/font.woff2"`);
+    });
+    it("should not transform already absolute URLs", () => {
+        const code = `
+      const local = '/assets/logo.png';
+      const http = 'http://example.com/image.png';
+      const https = 'https://example.com/image.png';
+    `;
+        const result = assetBaseUrlTransform(code);
+        expect(result).toContain(`(window.enpilink?.serverUrl ?? "") + "/assets/logo.png"`);
+        expect(result).toContain("http://example.com/image.png");
+        expect(result).toContain("https://example.com/image.png");
+    });
+    it("should not transform code without asset paths", () => {
+        const code = `const text = "Hello World";`;
+        const result = assetBaseUrlTransform(code);
+        expect(result).toBe(code);
+    });
+    it("should not transform asset paths inside static `import ... from` clauses", () => {
+        // Reproducer for #713: a dep does `import * as sprite from './icons.svg'`,
+        // Vite resolves the relative path to absolute, then this transform used
+        // to rewrite the resolved string — producing invalid JS like
+        // `import * as sprite from (expr) + "..."` that crashes vite:import-analysis.
+        const cases = [
+            `import * as sprite from "/Users/me/proj/node_modules/pkg/icons.svg";`,
+            `import sprite from '/assets/icons.svg';`,
+            `import sprite from "/assets/icons.svg";`,
+            `export { default } from "/assets/icons.svg";`,
+            `export * from '/assets/sprites.svg';`,
+        ];
+        for (const code of cases) {
+            expect(assetBaseUrlTransform(code)).toBe(code);
+        }
+    });
+    it("should still transform value-position asset paths in files that also have unrelated imports", () => {
+        const code = [
+            `import { foo } from "./foo.js";`,
+            `import * as sprite from "/assets/sprite.svg";`,
+            `const logo = "/assets/logo.png";`,
+        ].join("\n");
+        const result = assetBaseUrlTransform(code);
+        // Imports untouched
+        expect(result).toContain(`from "./foo.js"`);
+        expect(result).toContain(`from "/assets/sprite.svg"`);
+        // Value-position rewritten
+        expect(result).toContain(`const logo = (window.enpilink?.serverUrl ?? "") + "/assets/logo.png";`);
+    });
+});
+describe("isCssRequest", () => {
+    it("returns true for CSS-family extensions", () => {
+        expect(isCssRequest("/src/styles.css")).toBe(true);
+        expect(isCssRequest("/src/styles.module.css")).toBe(true);
+        expect(isCssRequest("/src/styles.scss")).toBe(true);
+        expect(isCssRequest("/src/styles.sass")).toBe(true);
+        expect(isCssRequest("/src/styles.less")).toBe(true);
+        expect(isCssRequest("/src/styles.styl")).toBe(true);
+    });
+    it("returns true for CSS modules with Vite query strings", () => {
+        expect(isCssRequest("/src/styles.css?direct")).toBe(true);
+        expect(isCssRequest("/src/styles.css?inline")).toBe(true);
+        expect(isCssRequest("/src/styles.css?used")).toBe(true);
+        expect(isCssRequest("/src/Foo.vue?vue&type=style&lang.css")).toBe(true);
+    });
+    it("returns false for non-CSS modules", () => {
+        expect(isCssRequest("/src/index.tsx")).toBe(false);
+        expect(isCssRequest("/src/utils.ts")).toBe(false);
+        expect(isCssRequest("/src/Logo.svg")).toBe(false);
+        expect(isCssRequest("/src/notes.cssx")).toBe(false);
+    });
+});
+describe("assetBaseUrlTransformPlugin", () => {
+    function runTransform(id, code) {
+        const plugin = assetBaseUrlTransformPlugin();
+        const hook = plugin.transform;
+        if (!hook) {
+            throw new Error("plugin.transform is not defined");
+        }
+        const handler = typeof hook === "function" ? hook : hook.handler;
+        return handler.call(
+        // biome-ignore lint/suspicious/noExplicitAny: vitest harness for plugin hook
+        {}, code, id, { moduleType: "js" });
+    }
+    it("rewrites asset paths in JS modules", () => {
+        const result = runTransform("/src/widget.tsx", `const logo = "/assets/logo.png";`);
+        expect(result?.code).toContain(`(window.enpilink?.serverUrl ?? "") + "/assets/logo.png"`);
+    });
+    // Reproducer for #697: CSS imports are served as JS modules with the
+    // stylesheet embedded as a string. Rewriting url("/foo.woff2") inside that
+    // string would produce invalid CSS once the styles are injected.
+    it("does not rewrite asset paths when transforming a CSS module", () => {
+        const cssCode = `__vite__updateStyle("style-id", "@font-face { src: url(\\"/fonts/Brand.woff2\\") format(\\"woff2\\"); }");`;
+        expect(runTransform("/src/fonts.css", cssCode)).toBeNull();
+        expect(runTransform("/src/fonts.css?direct", cssCode)).toBeNull();
+        expect(runTransform("/src/fonts.css?inline", cssCode)).toBeNull();
+        expect(runTransform("/src/styles.scss", cssCode)).toBeNull();
+        expect(runTransform("/src/Foo.vue?vue&type=style&lang.css", cssCode)).toBeNull();
+    });
+});
+//# sourceMappingURL=asset-base-url-transform-plugin.test.js.map