@miragon/pulse-analytics-connector 0.0.0-bootstrap.0 → 0.21.0

package/dist/tools/performance.d.ts

@@ -0,0 +1,8 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client";
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools";
+import type { ProfileSource } from "../server-locale.js";
+import { type AnalyticsEngineScope } from "../engine-ids.js";
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>;
+export declare function registerPerformanceTools(register: Register, engineScope: AnalyticsEngineScope, profileStore?: ProfileSource): void;
+export {};
+//# sourceMappingURL=performance.d.ts.map

package/dist/tools/performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../src/tools/performance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAE7E,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,gBAAgB,CAAC,CAAC,CAAA;AAExE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,oBAAoB,EACjC,YAAY,CAAC,EAAE,aAAa,QAyB7B"}

package/dist/tools/performance.js

@@ -0,0 +1,25 @@
+import { schemas, queries } from "@miragon/pulse-analytics-client";
+import { optionalPeriod, settingsFor } from "../settings.js";
+import { withEngineScope } from "../engine-ids.js";
+export function registerPerformanceTools(register, engineScope, profileStore) {
+    register({
+        name: "analytics_analyze_process_performance",
+        category: "analytics",
+        description: "Analyze process performance from metrics over a rolling window: starts, completions, incidents created (incidents, not failed instances) per 100 starts, P50/P95 duration of the instances that ENDED in the window (null when none did), and a per-activity breakdown.",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        inputSchema: { ...schemas.analyzePerformanceInput.shape, period: optionalPeriod },
+        handler: async (ch, args, ctx) => queries.analyzePerformance(ch, {
+            ...withEngineScope(engineScope, args),
+            period: args.period ?? (await settingsFor(profileStore, ctx)).defaultPeriod,
+        }),
+    });
+    register({
+        name: "analytics_compare_execution_periods",
+        category: "analytics",
+        description: "Compare process execution metrics between two explicit time windows (before/after a change, regression analysis), using PromQL historical windows. Windows are clamped to now and the 30-day retention and reported as measured (`partial` when cut short); a reversed or wholly out-of-range window is refused. Compare windows of different length by started_per_day.",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        inputSchema: schemas.comparePeriodsInput.shape,
+        handler: async (ch, args) => queries.comparePeriods(ch, withEngineScope(engineScope, args)),
+    });
+}
+//# sourceMappingURL=performance.js.map

package/dist/tools/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../src/tools/performance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAGlE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,EAAE,eAAe,EAA6B,MAAM,kBAAkB,CAAA;AAI7E,MAAM,UAAU,wBAAwB,CACtC,QAAkB,EAClB,WAAiC,EACjC,YAA4B;IAE5B,QAAQ,CAAC;QACP,IAAI,EAAE,uCAAuC;QAC7C,QAAQ,EAAE,WAAW;QACrB,WAAW,EACT,yQAAyQ;QAC3Q,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAC9E,WAAW,EAAE,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE;QACjF,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAC/B,OAAO,CAAC,kBAAkB,CAAC,EAAE,EAAE;YAC7B,GAAG,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC;YACrC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa;SAC5E,CAAC;KACL,CAAC,CAAA;IAEF,QAAQ,CAAC;QACP,IAAI,EAAE,qCAAqC;QAC3C,QAAQ,EAAE,WAAW;QACrB,WAAW,EACT,0WAA0W;QAC5W,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAC9E,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,KAAK;QAC9C,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;KAC5F,CAAC,CAAA;AACJ,CAAC"}

package/dist/tools/performance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=performance.test.d.ts.map

package/dist/tools/performance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.test.d.ts","sourceRoot":"","sources":["../../src/tools/performance.test.ts"],"names":[],"mappings":""}

package/dist/tools/performance.test.js

@@ -0,0 +1,176 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { increaseIn } from "@miragon/pulse-analytics-client";
+import { createEngineScope } from "../engine-ids.js";
+import { registerPerformanceTools } from "./performance.js";
+const scope = createEngineScope(["prod-a", "prod-b"]);
+const register = (r) => registerPerformanceTools(r, scope);
+/** Registrar stand-in that captures each tool's handler instead of an MCPServer. */
+function captureHandlers(registerModule) {
+    const handlers = new Map();
+    const register = Object.assign((config) => {
+        handlers.set(config.name, config.handler);
+    }, { getRegisteredTools: () => [] });
+    registerModule(register);
+    return handlers;
+}
+/** PrometheusClient that records every instant PromQL string and returns no samples. */
+function recordingClient() {
+    const queries = [];
+    return {
+        client: {
+            instant: (query) => {
+                queries.push(query);
+                return Promise.resolve([]);
+            },
+        },
+        queries,
+    };
+}
+describe("analytics_analyze_process_performance PromQL", () => {
+    it("emits the exact KPI + activity-breakdown queries, scoped to key and engine", async () => {
+        const handlers = captureHandlers(register);
+        const { client, queries } = recordingClient();
+        await handlers.get("analytics_analyze_process_performance")(client, {
+            processDefinitionKey: "order",
+            period: "7d",
+            includeActivityBreakdown: true,
+            engine: "prod-a",
+        });
+        const sel = '{process_definition_key="order",engine_id="prod-a"}';
+        const completedSel = '{process_definition_key="order",engine_id="prod-a",state="COMPLETED"}';
+        const count = (series) => increaseIn(series, { range: "7d" });
+        const instance = "camunda_process_instance_duration_milliseconds";
+        const activity = "camunda_activity_duration_milliseconds";
+        expect(queries).toEqual([
+            `sum(${count(`camunda_process_instance_started_total${sel}`)})`,
+            `sum(${count(`camunda_process_instance_ended_total${completedSel}`)})`,
+            `sum(${count(`camunda_incident_created_total${sel}`)})`,
+            `sum(${count(`${instance}_sum${sel}`)}) / sum(${count(`${instance}_count${sel}`)})`,
+            `histogram_quantile(0.5, sum by (le)(${count(`${instance}_bucket${sel}`)}))`,
+            `histogram_quantile(0.95, sum by (le)(${count(`${instance}_bucket${sel}`)}))`,
+            `sum by (activity_id, activity_type)(${count(`camunda_activity_ended_total${sel}`)})`,
+            `sum by (activity_id)(${count(`${activity}_sum${sel}`)})`,
+            `histogram_quantile(0.5, sum by (activity_id, le)(${count(`${activity}_bucket${sel}`)}))`,
+            `histogram_quantile(0.95, sum by (activity_id, le)(${count(`${activity}_bucket${sel}`)}))`,
+        ]);
+    });
+    it("skips the activity-breakdown queries; engine omitted reads the configured fleet", async () => {
+        const handlers = captureHandlers(register);
+        const { client, queries } = recordingClient();
+        await handlers.get("analytics_analyze_process_performance")(client, {
+            processDefinitionKey: "order",
+            period: "30d",
+            includeActivityBreakdown: false,
+        });
+        expect(queries).toHaveLength(6);
+        expect(queries.every((q) => q.includes('process_definition_key="order"'))).toBe(true);
+        expect(queries.every((q) => q.includes("[30d]"))).toBe(true);
+        // Never every engine a shared Prometheus holds (N138).
+        expect(queries.every((q) => q.includes('engine_id=~"prod-a|prod-b"'))).toBe(true);
+        expect(queries.some((q) => q.includes("camunda_activity_"))).toBe(false);
+    });
+});
+describe("analytics_compare_execution_periods PromQL", () => {
+    // Explicit windows are clamped to [now − retention, now] — pin now.
+    beforeAll(() => {
+        vi.useFakeTimers({ toFake: ["Date"], now: Date.parse("2026-02-10T00:00:00Z") });
+    });
+    afterAll(() => {
+        vi.useRealTimers();
+    });
+    it("queries each period via `[duration] @ end` historical windows", async () => {
+        const handlers = captureHandlers(register);
+        const { client, queries } = recordingClient();
+        await handlers.get("analytics_compare_execution_periods")(client, {
+            processDefinitionKey: "order",
+            periodAFrom: "2026-01-20T00:00:00Z",
+            periodATo: "2026-01-21T00:00:00Z",
+            periodBFrom: "2026-02-01T00:00:00Z",
+            periodBTo: "2026-02-03T00:00:00Z",
+            includeActivityBreakdown: false,
+        });
+        const atA = Date.parse("2026-01-21T00:00:00Z") / 1000;
+        const atB = Date.parse("2026-02-03T00:00:00Z") / 1000;
+        const windowA = `[86400s] @ ${atA}`;
+        const windowB = `[172800s] @ ${atB}`;
+        const fleet = 'engine_id=~"prod-a|prod-b"';
+        // 6 KPI queries per period, period A first.
+        expect(queries).toHaveLength(12);
+        expect(queries.slice(0, 6).every((q) => q.includes(windowA))).toBe(true);
+        expect(queries.slice(6).every((q) => q.includes(windowB))).toBe(true);
+        const started = `camunda_process_instance_started_total{process_definition_key="order",${fleet}}`;
+        expect(queries[0]).toBe(`sum(${increaseIn(started, { range: "86400s", at: atA })})`);
+        expect(queries[6]).toBe(`sum(${increaseIn(started, { range: "172800s", at: atB })})`);
+    });
+});
+describe("analytics_compare_execution_periods windows (N79)", () => {
+    beforeAll(() => {
+        vi.useFakeTimers({ toFake: ["Date"], now: Date.parse("2026-02-10T00:00:00Z") });
+    });
+    afterAll(() => {
+        vi.useRealTimers();
+    });
+    const base = { processDefinitionKey: "order", includeActivityBreakdown: false };
+    it("clamps a window reaching past now to now and reports what was measured", async () => {
+        const handlers = captureHandlers(register);
+        const { client, queries } = recordingClient();
+        const result = (await handlers.get("analytics_compare_execution_periods")(client, {
+            ...base,
+            periodAFrom: "2026-02-01T00:00:00Z",
+            periodATo: "2026-02-05T00:00:00Z",
+            periodBFrom: "2026-02-05T00:00:00Z",
+            periodBTo: "2026-02-15T00:00:00Z",
+        }));
+        const now = Date.parse("2026-02-10T00:00:00Z") / 1000;
+        // No `@` anchor in the future: Prometheus would answer with the elapsed
+        // part while the window is reported at full length.
+        expect(queries.slice(6).every((q) => q.includes(`[432000s] @ ${now}`))).toBe(true);
+        expect(result.kpiComparison[1]).toMatchObject({
+            window_to: "2026-02-10T00:00:00.000Z",
+            window_days: 5,
+            partial: true,
+        });
+    });
+    it("refuses a reversed window instead of measuring a 1-second one", async () => {
+        const handlers = captureHandlers(register);
+        const { client, queries } = recordingClient();
+        await expect(handlers.get("analytics_compare_execution_periods")(client, {
+            ...base,
+            periodAFrom: "2026-02-05T00:00:00Z",
+            periodATo: "2026-02-01T00:00:00Z",
+            periodBFrom: "2026-02-05T00:00:00Z",
+            periodBTo: "2026-02-08T00:00:00Z",
+        })).rejects.toThrow(/periodA: the window ends before it starts/);
+        expect(queries).toEqual([]);
+    });
+    it("refuses a window entirely before the retention", async () => {
+        const handlers = captureHandlers(register);
+        const { client } = recordingClient();
+        await expect(handlers.get("analytics_compare_execution_periods")(client, {
+            ...base,
+            periodAFrom: "2025-10-01T00:00:00Z",
+            periodATo: "2025-10-08T00:00:00Z",
+            periodBFrom: "2026-02-01T00:00:00Z",
+            periodBTo: "2026-02-08T00:00:00Z",
+        })).rejects.toThrow(/periodA: the window lies before the 30-day Prometheus retention/);
+    });
+});
+describe("analytics_analyze_process_performance saved defaults", () => {
+    it("resolves the CALLER's saved period from the handler ctx the registrar hands it", async () => {
+        const store = {
+            get: (key) => Promise.resolve(key === "user-1" ? { modules: { analytics: { defaultPeriod: "30d" } } } : undefined),
+        };
+        const handlers = captureHandlers((r) => registerPerformanceTools(r, scope, store));
+        const handler = handlers.get("analytics_analyze_process_performance");
+        const firstQueryFor = async (ctx) => {
+            const { client, queries } = recordingClient();
+            await handler(client, { processDefinitionKey: "order" }, ctx);
+            return queries[0];
+        };
+        expect(await firstQueryFor({ auth: { user: { id: "user-1" } } })).toContain("[30d]");
+        // Another caller, and a request without any identity, get the schema default.
+        expect(await firstQueryFor({ auth: { user: { id: "user-2" } } })).toContain("[7d]");
+        expect(await firstQueryFor()).toContain("[7d]");
+    });
+});
+//# sourceMappingURL=performance.test.js.map

package/dist/tools/performance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.test.js","sourceRoot":"","sources":["../../src/tools/performance.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AACtE,OAAO,EAAE,UAAU,EAAyB,MAAM,iCAAiC,CAAA;AAEnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAE3D,MAAM,KAAK,GAAG,iBAAiB,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;AACrD,MAAM,QAAQ,GAAG,CAAC,CAAQ,EAAE,EAAE,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;AAIjE,oFAAoF;AACpF,SAAS,eAAe,CAAC,cAAyC;IAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAA;IAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAC5B,CAAC,MAAoC,EAAE,EAAE;QACvC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC,EACD,EAAE,kBAAkB,EAAE,GAAyB,EAAE,CAAC,EAAE,EAAE,CACvD,CAAA;IACD,cAAc,CAAC,QAAiB,CAAC,CAAA;IACjC,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,wFAAwF;AACxF,SAAS,eAAe;IACtB,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,OAAO;QACL,MAAM,EAAE;YACN,OAAO,EAAE,CAAC,KAAa,EAAE,EAAE;gBACzB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;YAC5B,CAAC;SACF;QACD,OAAO;KACR,CAAA;AACH,CAAC;AAED,QAAQ,CAAC,8CAA8C,EAAE,GAAG,EAAE;IAC5D,EAAE,CAAC,4EAA4E,EAAE,KAAK,IAAI,EAAE;QAC1F,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;QAE7C,MAAM,QAAQ,CAAC,GAAG,CAAC,uCAAuC,CAAE,CAAC,MAAM,EAAE;YACnE,oBAAoB,EAAE,OAAO;YAC7B,MAAM,EAAE,IAAI;YACZ,wBAAwB,EAAE,IAAI;YAC9B,MAAM,EAAE,QAAQ;SACjB,CAAC,CAAA;QAEF,MAAM,GAAG,GAAG,qDAAqD,CAAA;QACjE,MAAM,YAAY,GAAG,uEAAuE,CAAA;QAC5F,MAAM,KAAK,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QACrE,MAAM,QAAQ,GAAG,gDAAgD,CAAA;QACjE,MAAM,QAAQ,GAAG,wCAAwC,CAAA;QACzD,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC;YACtB,OAAO,KAAK,CAAC,yCAAyC,GAAG,EAAE,CAAC,GAAG;YAC/D,OAAO,KAAK,CAAC,uCAAuC,YAAY,EAAE,CAAC,GAAG;YACtE,OAAO,KAAK,CAAC,iCAAiC,GAAG,EAAE,CAAC,GAAG;YACvD,OAAO,KAAK,CAAC,GAAG,QAAQ,OAAO,GAAG,EAAE,CAAC,WAAW,KAAK,CAAC,GAAG,QAAQ,SAAS,GAAG,EAAE,CAAC,GAAG;YACnF,uCAAuC,KAAK,CAAC,GAAG,QAAQ,UAAU,GAAG,EAAE,CAAC,IAAI;YAC5E,wCAAwC,KAAK,CAAC,GAAG,QAAQ,UAAU,GAAG,EAAE,CAAC,IAAI;YAC7E,uCAAuC,KAAK,CAAC,+BAA+B,GAAG,EAAE,CAAC,GAAG;YACrF,wBAAwB,KAAK,CAAC,GAAG,QAAQ,OAAO,GAAG,EAAE,CAAC,GAAG;YACzD,oDAAoD,KAAK,CAAC,GAAG,QAAQ,UAAU,GAAG,EAAE,CAAC,IAAI;YACzF,qDAAqD,KAAK,CAAC,GAAG,QAAQ,UAAU,GAAG,EAAE,CAAC,IAAI;SAC3F,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iFAAiF,EAAE,KAAK,IAAI,EAAE;QAC/F,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;QAE7C,MAAM,QAAQ,CAAC,GAAG,CAAC,uCAAuC,CAAE,CAAC,MAAM,EAAE;YACnE,oBAAoB,EAAE,OAAO;YAC7B,MAAM,EAAE,KAAK;YACb,wBAAwB,EAAE,KAAK;SAChC,CAAC,CAAA;QAEF,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;QAC/B,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,gCAAgC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrF,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5D,uDAAuD;QACvD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjF,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,4CAA4C,EAAE,GAAG,EAAE;IAC1D,oEAAoE;IACpE,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAA;IACjF,CAAC,CAAC,CAAA;IACF,QAAQ,CAAC,GAAG,EAAE;QACZ,EAAE,CAAC,aAAa,EAAE,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;QAE7C,MAAM,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAE,CAAC,MAAM,EAAE;YACjE,oBAAoB,EAAE,OAAO;YAC7B,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;YACjC,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;YACjC,wBAAwB,EAAE,KAAK;SAChC,CAAC,CAAA;QAEF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAA;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAA;QACrD,MAAM,OAAO,GAAG,cAAc,GAAG,EAAE,CAAA;QACnC,MAAM,OAAO,GAAG,eAAe,GAAG,EAAE,CAAA;QACpC,MAAM,KAAK,GAAG,4BAA4B,CAAA;QAC1C,4CAA4C;QAC5C,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;QAChC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACxE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACrE,MAAM,OAAO,GAAG,yEAAyE,KAAK,GAAG,CAAA;QACjG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;QACpF,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;IACvF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,mDAAmD,EAAE,GAAG,EAAE;IACjE,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAA;IACjF,CAAC,CAAC,CAAA;IACF,QAAQ,CAAC,GAAG,EAAE;QACZ,EAAE,CAAC,aAAa,EAAE,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,EAAE,oBAAoB,EAAE,OAAO,EAAE,wBAAwB,EAAE,KAAK,EAAE,CAAA;IAE/E,EAAE,CAAC,wEAAwE,EAAE,KAAK,IAAI,EAAE;QACtF,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;QAE7C,MAAM,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAE,CAAC,MAAM,EAAE;YACjF,GAAG,IAAI;YACP,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;YACjC,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;SAClC,CAAC,CAA2F,CAAA;QAE7F,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAA;QACrD,wEAAwE;QACxE,oDAAoD;QACpD,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAClF,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;YAC5C,SAAS,EAAE,0BAA0B;YACrC,WAAW,EAAE,CAAC;YACd,OAAO,EAAE,IAAI;SACd,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;QAC7C,MAAM,MAAM,CACV,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAE,CAAC,MAAM,EAAE;YAC3D,GAAG,IAAI;YACP,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;YACjC,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;SAClC,CAAC,CACH,CAAC,OAAO,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAA;QAC9D,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,EAAE,CAAA;QACpC,MAAM,MAAM,CACV,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAE,CAAC,MAAM,EAAE;YAC3D,GAAG,IAAI;YACP,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;YACjC,WAAW,EAAE,sBAAsB;YACnC,SAAS,EAAE,sBAAsB;SAClC,CAAC,CACH,CAAC,OAAO,CAAC,OAAO,CAAC,iEAAiE,CAAC,CAAA;IACtF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACpE,EAAE,CAAC,gFAAgF,EAAE,KAAK,IAAI,EAAE;QAC9F,MAAM,KAAK,GAAG;YACZ,GAAG,EAAE,CAAC,GAAW,EAAE,EAAE,CACnB,OAAO,CAAC,OAAO,CACb,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CACpF;SACJ,CAAA;QACD,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;QAClF,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,uCAAuC,CAAE,CAAA;QACtE,MAAM,aAAa,GAAG,KAAK,EAAE,GAAa,EAAE,EAAE;YAC5C,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAA;YAC7C,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,oBAAoB,EAAE,OAAO,EAAE,EAAE,GAAY,CAAC,CAAA;YACtE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAA;QACnB,CAAC,CAAA;QAED,MAAM,CAAC,MAAM,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QACpF,8EAA8E;QAC9E,MAAM,CAAC,MAAM,aAAa,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QACnF,MAAM,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;IACjD,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/tools/version-compare.d.ts

@@ -0,0 +1,8 @@
+import type { PrometheusClient } from "@miragon/pulse-analytics-client";
+import type { createToolRegistrar } from "@miragon/mcp-toolkit-core/tools";
+import type { ProfileSource } from "../server-locale.js";
+import { type AnalyticsEngineScope } from "../engine-ids.js";
+type Register = ReturnType<typeof createToolRegistrar<PrometheusClient>>;
+export declare function registerVersionCompareTools(register: Register, engineScope: AnalyticsEngineScope, profileStore?: ProfileSource): void;
+export {};
+//# sourceMappingURL=version-compare.d.ts.map

package/dist/tools/version-compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.d.ts","sourceRoot":"","sources":["../../src/tools/version-compare.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,EAAmB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAE7E,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,gBAAgB,CAAC,CAAC,CAAA;AAExE,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,oBAAoB,EACjC,YAAY,CAAC,EAAE,aAAa,QAe7B"}

package/dist/tools/version-compare.js

@@ -0,0 +1,17 @@
+import { schemas, queries } from "@miragon/pulse-analytics-client";
+import { optionalMinBucketSize, settingsFor } from "../settings.js";
+import { withEngineScope } from "../engine-ids.js";
+export function registerVersionCompareTools(register, engineScope, profileStore) {
+    register({
+        name: "analytics_version_compare",
+        category: "analytics",
+        description: "Compare KPIs between two deployed process definition versions of the same processDefinitionKey over a shared rolling window, from metrics. The version is an exact label on the process-instance and incident series, so instance counts, completed counts, incidents, the incident rate and durations (avg, p95) per version plus their deltas are precise. Process-wide: the element_incident_* fields stay null. Flagged `suppressed` when either version has fewer than minBucketSize started or completed instances. Pair with camunda7_list_process_definitions to discover versions.",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        inputSchema: { ...schemas.versionCompareInput.shape, minBucketSize: optionalMinBucketSize },
+        handler: async (ch, args, ctx) => queries.versionCompare(ch, {
+            ...withEngineScope(engineScope, args),
+            minBucketSize: args.minBucketSize ?? (await settingsFor(profileStore, ctx)).minBucketSize,
+        }),
+    });
+}
+//# sourceMappingURL=version-compare.js.map

package/dist/tools/version-compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.js","sourceRoot":"","sources":["../../src/tools/version-compare.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAGlE,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAA6B,MAAM,kBAAkB,CAAA;AAI7E,MAAM,UAAU,2BAA2B,CACzC,QAAkB,EAClB,WAAiC,EACjC,YAA4B;IAE5B,QAAQ,CAAC;QACP,IAAI,EAAE,2BAA2B;QACjC,QAAQ,EAAE,WAAW;QACrB,WAAW,EACT,6jBAA6jB;QAC/jB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAC9E,WAAW,EAAE,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE;QAC3F,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAC/B,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE;YACzB,GAAG,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC;YACrC,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,CAAC,MAAM,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,aAAa;SAC1F,CAAC;KACL,CAAC,CAAA;AACJ,CAAC"}

package/dist/tools/version-compare.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=version-compare.test.d.ts.map

package/dist/tools/version-compare.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.test.d.ts","sourceRoot":"","sources":["../../src/tools/version-compare.test.ts"],"names":[],"mappings":""}

package/dist/tools/version-compare.test.js

@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { createEngineScope } from "../engine-ids.js";
+import { registerVersionCompareTools } from "./version-compare.js";
+/** Registrar stand-in that captures the tool's full config instead of an MCPServer. */
+function captureConfig() {
+    const configs = [];
+    const register = Object.assign((config) => configs.push(config), {
+        getRegisteredTools: () => [],
+    });
+    registerVersionCompareTools(register, createEngineScope(["prod-a"]));
+    expect(configs.map((c) => c.name)).toEqual(["analytics_version_compare"]);
+    return configs[0];
+}
+/** PrometheusClient that records every instant PromQL string and answers 20 per query. */
+function recordingClient() {
+    const queries = [];
+    return {
+        client: {
+            instant: (query) => {
+                queries.push(query);
+                return Promise.resolve([{ metric: {}, value: 20 }]);
+            },
+        },
+        queries,
+    };
+}
+const args = { processDefinitionKey: "order", versionA: 1, versionB: 2, windowDays: 14 };
+describe("analytics_version_compare", () => {
+    // Captured per test (not at collection time), so a registration that
+    // registers nothing fails a test instead of the file's collection.
+    let config;
+    beforeEach(() => {
+        config = captureConfig();
+    });
+    it("reads incidents per version, on the version label (#337)", async () => {
+        const { client, queries } = recordingClient();
+        const res = (await config.handler(client, { ...args }));
+        const incidentQueries = queries.filter((q) => q.includes("camunda_incident_created_total"));
+        expect(incidentQueries).toHaveLength(2);
+        expect(incidentQueries.map((q) => /process_definition_version="(\d+)"/.exec(q)?.[1])).toEqual([
+            "1",
+            "2",
+        ]);
+        for (const kpi of res.kpis) {
+            expect(kpi).toMatchObject({
+                instance_count: 20,
+                incident_count: 20,
+                incident_rate_pct: 100,
+                element_incident_count: null,
+                element_incident_rate_pct: null,
+            });
+        }
+        expect(res.delta.incident_rate_delta_pp).toBe(0);
+    });
+    it("tells the model the incident figures are per version and the comparison process-wide", () => {
+        expect(config.description).toContain("process-instance and incident series");
+        expect(config.description).toContain("element_incident_* fields stay null");
+    });
+    it("accepts the version-compare input plus the optional minBucketSize override", () => {
+        expect(Object.keys(config.inputSchema ?? {})).toEqual(expect.arrayContaining(["processDefinitionKey", "versionA", "versionB", "minBucketSize"]));
+    });
+    it("registers as a read-only external read under the analytics category", () => {
+        expect(config.category).toBe("analytics");
+        expect(config.annotations).toEqual({
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        });
+    });
+    it("prefers an explicit minBucketSize over the resolved setting", async () => {
+        const { client } = recordingClient();
+        const explicit = (await config.handler(client, {
+            ...args,
+            minBucketSize: 3,
+        }));
+        const fallback = (await config.handler(client, { ...args }));
+        expect(explicit.minBucketSize).toBe(3);
+        // Without a store the registrar path lands on the schema default.
+        expect(fallback.minBucketSize).toBe(10);
+    });
+});
+//# sourceMappingURL=version-compare.test.js.map

package/dist/tools/version-compare.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compare.test.js","sourceRoot":"","sources":["../../src/tools/version-compare.test.ts"],"names":[],"mappings":"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"}

package/dist/toolsets.d.ts

@@ -0,0 +1,17 @@
+export declare const ANALYTICS_TOOLSETS: readonly ["read-only", "standard"];
+export type AnalyticsToolset = (typeof ANALYTICS_TOOLSETS)[number];
+/** The vocabulary the module declares to the composition root (`analyticsModule.toolsets`). */
+export declare const analyticsToolsets: import("@miragon/pulse-widget-shell/server").ToolsetVocabulary<"read-only" | "standard">;
+export declare function isAnalyticsToolset(value: string): value is AnalyticsToolset;
+/**
+ * Whether the toolset permits the module's durable writes
+ * (`analytics_save_settings`). Registered outside the tool registrar, that save
+ * has to gate itself — no registrar filter ever sees it.
+ *
+ * Decided by the vocabulary, never by an ad-hoc `toolset === "read-only"`
+ * compare (which fails open for every other name): a missing toolset resolves
+ * to the read-only floor, an unknown one warns and degrades to it, and only a
+ * toolset above the floor (`standard`) writes.
+ */
+export declare function allowsDurableWrites(toolset?: string): boolean;
+//# sourceMappingURL=toolsets.d.ts.map

package/dist/toolsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.d.ts","sourceRoot":"","sources":["../src/toolsets.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,kBAAkB,oCAAqC,CAAA;AACpE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAElE,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,0FAO7B,CAAA;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/toolsets.js

@@ -0,0 +1,47 @@
+/**
+ * The analytics module's toolset vocabulary. Module peers own their toolset
+ * NAMES; the fail-closed SEMANTICS are shared (`createToolsetVocabulary` from
+ * `@miragon/pulse-widget-shell/server`):
+ *
+ * - `read-only` — the floor: every analytics read, no durable write (the
+ *   settings save tool is not registered);
+ * - `standard` — the full analytics surface, including the caller's own
+ *   settings save. Analytics has no admin tier: it reads Prometheus and never
+ *   writes to an engine, so there is nothing wider to name.
+ *
+ * Which one a boot runs with (`MCP_ACTIVE_MODULES=analytics:<toolset>`):
+ *
+ * - no suffix → `read-only` on an unauthenticated boot, `standard` when the
+ *   root installed OAuth;
+ * - an empty or unknown suffix → warns and degrades to `read-only` — a suffix
+ *   always meant to restrict, so a typo never grants the write it tried to
+ *   take away;
+ * - nothing ever resolves to "everything".
+ *
+ * The composition root resolves the suffix once per boot and hands the module
+ * a concrete name; a direct `createPlugin` caller that passes none gets the
+ * floor.
+ */
+import { createToolsetVocabulary } from "@miragon/pulse-widget-shell/server";
+export const ANALYTICS_TOOLSETS = ["read-only", "standard"];
+/** The vocabulary the module declares to the composition root (`analyticsModule.toolsets`). */
+export const analyticsToolsets = createToolsetVocabulary("analytics", ANALYTICS_TOOLSETS, "read-only", {
+    authenticatedDefault: "standard",
+});
+export function isAnalyticsToolset(value) {
+    return analyticsToolsets.isKnown(value);
+}
+/**
+ * Whether the toolset permits the module's durable writes
+ * (`analytics_save_settings`). Registered outside the tool registrar, that save
+ * has to gate itself — no registrar filter ever sees it.
+ *
+ * Decided by the vocabulary, never by an ad-hoc `toolset === "read-only"`
+ * compare (which fails open for every other name): a missing toolset resolves
+ * to the read-only floor, an unknown one warns and degrades to it, and only a
+ * toolset above the floor (`standard`) writes.
+ */
+export function allowsDurableWrites(toolset) {
+    return analyticsToolsets.allowsDurableWrites(analyticsToolsets.resolve(toolset));
+}
+//# sourceMappingURL=toolsets.js.map

package/dist/toolsets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.js","sourceRoot":"","sources":["../src/toolsets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAA;AAE5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,UAAU,CAAU,CAAA;AAGpE,+FAA+F;AAC/F,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CACtD,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX;IACE,oBAAoB,EAAE,UAAU;CACjC,CACF,CAAA;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO,iBAAiB,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;AAClF,CAAC"}

package/dist/toolsets.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=toolsets.test.d.ts.map

package/dist/toolsets.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.test.d.ts","sourceRoot":"","sources":["../src/toolsets.test.ts"],"names":[],"mappings":""}

package/dist/toolsets.test.js

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { allowsDurableWrites, ANALYTICS_TOOLSETS, analyticsToolsets, isAnalyticsToolset, } from "./toolsets.js";
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("analyticsToolsets (the vocabulary the module declares)", () => {
+    it("declares exactly read-only and standard — analytics has no admin tier", () => {
+        expect(ANALYTICS_TOOLSETS).toEqual(["read-only", "standard"]);
+        expect(analyticsToolsets.module).toBe("analytics");
+        expect(analyticsToolsets.names).toEqual(["read-only", "standard"]);
+    });
+    it("floors at read-only and defaults to standard under OAuth", () => {
+        expect(analyticsToolsets.fallback).toBe("read-only");
+        expect(analyticsToolsets.authenticatedDefault).toBe("standard");
+    });
+    it("no suffix: read-only without OAuth, standard with it — never 'everything'", () => {
+        expect(analyticsToolsets.effective(undefined, { authenticated: false })).toEqual({
+            toolset: "read-only",
+            source: "default",
+        });
+        expect(analyticsToolsets.effective(undefined, { authenticated: true })).toEqual({
+            toolset: "standard",
+            source: "default",
+        });
+    });
+    it("a named suffix wins over the auth-dependent default, in both directions", () => {
+        expect(analyticsToolsets.effective("standard", { authenticated: false })).toEqual({
+            toolset: "standard",
+            source: "suffix",
+        });
+        expect(analyticsToolsets.effective("read-only", { authenticated: true })).toEqual({
+            toolset: "read-only",
+            source: "suffix",
+        });
+    });
+    it("an empty or unknown suffix (incl. camunda7's 'admin') falls back to the floor, with a warning", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        for (const suffix of ["", "admin"]) {
+            expect(analyticsToolsets.effective(suffix, { authenticated: true })).toEqual({
+                toolset: "read-only",
+                source: "fallback",
+            });
+        }
+        expect(warn).toHaveBeenCalledTimes(2);
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("[analytics]"));
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('Unknown toolset "admin"'));
+    });
+});
+describe("isAnalyticsToolset", () => {
+    it("accepts every declared name and nothing else", () => {
+        for (const toolset of ANALYTICS_TOOLSETS) {
+            expect(isAnalyticsToolset(toolset)).toBe(true);
+        }
+        expect(isAnalyticsToolset("admin")).toBe(false);
+        expect(isAnalyticsToolset("")).toBe(false);
+    });
+});
+describe("allowsDurableWrites", () => {
+    it("forbids writes when no toolset is configured — a missing toolset is the read-only floor", () => {
+        // Fail-closed: a direct `createPlugin` caller that passes no toolset gets
+        // the floor, never the full surface.
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        expect(allowsDurableWrites(undefined)).toBe(false);
+        expect(allowsDurableWrites()).toBe(false);
+        expect(warn).not.toHaveBeenCalled();
+    });
+    it("forbids writes in the module's read-only toolset", () => {
+        expect(allowsDurableWrites("read-only")).toBe(false);
+    });
+    it("permits writes in the standard toolset (the user's own settings save)", () => {
+        expect(allowsDurableWrites("standard")).toBe(true);
+    });
+    it("fails CLOSED on an unknown toolset name, with a warning", () => {
+        // A typo'd `analytics:standrad`, or camunda7's `operations`, must not
+        // grant the one write — unknown names degrade to `read-only`.
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        expect(allowsDurableWrites("operations")).toBe(false);
+        expect(warn).toHaveBeenCalledOnce();
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('Unknown toolset "operations"'));
+    });
+    it("decides by declared name, not by an ad-hoc string compare", () => {
+        // The regression this guards: a `toolset === "read-only"` check silently
+        // fails open for every name that is NOT that literal. Every declared
+        // toolset is a deliberate decision: only the floor forbids the write.
+        expect(ANALYTICS_TOOLSETS.map((toolset) => [toolset, allowsDurableWrites(toolset)])).toEqual([
+            ["read-only", false],
+            ["standard", true],
+        ]);
+    });
+});
+//# sourceMappingURL=toolsets.test.js.map

package/dist/toolsets.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.test.js","sourceRoot":"","sources":["../src/toolsets.test.ts"],"names":[],"mappings":"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"}

package/dist/view-title.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=view-title.test.d.ts.map

package/dist/view-title.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-title.test.d.ts","sourceRoot":"","sources":["../src/view-title.test.ts"],"names":[],"mappings":""}