@miragon/pulse-analytics-connector 0.0.0-stage → 0.21.0

package/src/module.ts

@@ -0,0 +1,211 @@
+import { z } from "zod"
+import type { AppPlugin } from "@miragon/mcp-toolkit-core"
+import type { MCPServer } from "mcp-use"
+import { createPlugin } from "./plugin.js"
+import { analyticsToolsets } from "./toolsets.js"
+import { analyticsInstructions } from "./instructions.js"
+import type { FetchBpmnXml } from "./bpmn-name-lookup.js"
+import type { ProfileSource } from "./server-locale.js"
+import { NO_ENGINE_SCOPE_MESSAGE } from "./engine-ids.js"
+
+/**
+ * Self-contained module definition for host apps: everything the app needs to
+ * mount the analytics module without knowing its config surface. Conforms
+ * structurally to the app's `ModuleDefinition` port — no import of the app.
+ */
+
+/** The longest delay a Node timer holds — a longer deadline would fire at once. */
+const MAX_TIMEOUT_MS = 2_147_483_647
+
+const HEADERS_ERROR =
+  'PROMETHEUS_HEADERS must be a JSON object of string header values, e.g. {"X-Scope-OrgID":"tenant-a"}'
+
+/** `PROMETHEUS_HEADERS` JSON text (env) or an object (direct caller) → a header record. */
+const headersSchema = z
+  .union([
+    z.record(z.string(), z.string()),
+    z.string().transform((text, ctx) => {
+      try {
+        return JSON.parse(text) as unknown
+      } catch {
+        // Never echo the text: header values are often secrets (API keys).
+        ctx.addIssue({ code: "custom", message: HEADERS_ERROR })
+        return z.NEVER
+      }
+    }),
+  ])
+  .pipe(z.record(z.string(), z.string({ error: HEADERS_ERROR }), { error: HEADERS_ERROR }))
+
+const analyticsConfigSchema = z.object({
+  url: z.string().default("http://localhost:9090"),
+  /**
+   * Prometheus auth (all optional): a bearer token, OR basic auth — explicit
+   * username + password or userinfo in `url` — plus extra headers (tenant
+   * ids). The client rejects ambiguous combinations at boot and keeps every
+   * credential out of model-visible errors.
+   */
+  bearerToken: z.string().optional(),
+  username: z.string().optional(),
+  password: z.string().optional(),
+  headers: headersSchema.optional(),
+  // PROMETHEUS_TIMEOUT_MS — strict: a typo fails the boot instead of being
+  // coerced into some other deadline. Unset = the client default (30 s).
+  timeoutMs: z
+    .union([
+      z.number(),
+      z
+        .string()
+        .regex(/^\d+$/, "PROMETHEUS_TIMEOUT_MS must be a whole number of milliseconds")
+        .transform(Number),
+    ])
+    .pipe(
+      z
+        .number()
+        .int("PROMETHEUS_TIMEOUT_MS must be a whole number of milliseconds")
+        .min(1, "PROMETHEUS_TIMEOUT_MS must be at least 1 ms")
+        .max(MAX_TIMEOUT_MS, `PROMETHEUS_TIMEOUT_MS must be at most ${MAX_TIMEOUT_MS} ms`),
+    )
+    .optional(),
+  /**
+   * `ANALYTICS_ENGINE_IDS` — the engine ids a STANDALONE analytics boot may
+   * read (comma-separated `engine_id` values). Only the fallback: when the
+   * composition root injects its configured engines (`shared.engineIds`,
+   * from camunda7) those win. See `engine-ids.ts`.
+   */
+  engineIds: z
+    .union([
+      z.array(z.string()),
+      z.string().transform((text) =>
+        text
+          .split(",")
+          .map((id) => id.trim())
+          .filter((id) => id.length > 0),
+      ),
+    ])
+    .optional(),
+  /**
+   * The effective toolset the composition root resolved from the
+   * `MCP_ACTIVE_MODULES` suffix — always a concrete declared name there. The
+   * module's tools are read-only by nature; the toolset only gates the one
+   * durable write, `analytics_save_settings` (`standard` only). Kept a plain
+   * string here so a direct caller's unknown name still fails closed (warning
+   * + `read-only`) instead of throwing — `createPlugin` below resolves it.
+   */
+  toolset: z.string().optional(),
+})
+
+/** Cross-module resources the host app threads in (structural, app-owned). */
+interface AnalyticsModuleShared {
+  profileStore?: ProfileSource
+  fetchBpmnXml?: FetchBpmnXml
+  /**
+   * The engine ids this server is configured for (the camunda7 module's
+   * engines) — analytics reads only these. Wins over `ANALYTICS_ENGINE_IDS`.
+   */
+  engineIds?: readonly string[]
+}
+
+/**
+ * The engine ids analytics covers: the injected ones, else
+ * `ANALYTICS_ENGINE_IDS`, else none (fail-closed). Warns at boot for the two
+ * surprising cases — no scope at all, and an env list the injected one
+ * overrides.
+ */
+function effectiveEngineIds(
+  injected: readonly string[] | undefined,
+  fromEnv: readonly string[] | undefined,
+): readonly string[] {
+  if (injected && injected.length > 0) {
+    if (fromEnv && fromEnv.length > 0) {
+      console.warn(
+        `[analytics] ANALYTICS_ENGINE_IDS is ignored: the server's configured engines (${injected.join(", ")}) scope analytics.`,
+      )
+    }
+    return injected
+  }
+  if (fromEnv && fromEnv.length > 0) return fromEnv
+  console.warn(`[analytics] ${NO_ENGINE_SCOPE_MESSAGE}`)
+  return []
+}
+
+export const analyticsModule = {
+  name: "analytics",
+
+  /**
+   * Pure env → raw-config mapping. `PROMETHEUS_URL` is trimmed so an empty
+   * assignment (`PROMETHEUS_URL=` left in a .env or compose env_file) falls
+   * through to the schema default instead of producing an invalid-URL client.
+   */
+  configFromEnv(env: NodeJS.ProcessEnv): Record<string, unknown> {
+    // Blank = unset for every variable (a `KEY=` left in a .env file).
+    // Credentials are passed verbatim otherwise — never trimmed into another secret.
+    const trimmed = (name: string) => env[name]?.trim() || undefined
+    const verbatim = (name: string) => (env[name]?.trim() ? env[name] : undefined)
+    return {
+      url: trimmed("PROMETHEUS_URL"),
+      bearerToken: verbatim("PROMETHEUS_BEARER_TOKEN"),
+      username: verbatim("PROMETHEUS_USERNAME"),
+      password: verbatim("PROMETHEUS_PASSWORD"),
+      headers: trimmed("PROMETHEUS_HEADERS"),
+      timeoutMs: trimmed("PROMETHEUS_TIMEOUT_MS"),
+      engineIds: trimmed("ANALYTICS_ENGINE_IDS"),
+    }
+  },
+
+  /** This module's slice of the app's unknown-env-var typo warner. */
+  knownEnvVars: [
+    "PROMETHEUS_URL",
+    "PROMETHEUS_BEARER_TOKEN",
+    "PROMETHEUS_USERNAME",
+    "PROMETHEUS_PASSWORD",
+    "PROMETHEUS_HEADERS",
+    "PROMETHEUS_TIMEOUT_MS",
+    "ANALYTICS_ENGINE_IDS",
+  ] as const,
+
+  /**
+   * `read-only` (the floor) | `standard` (adds the caller's own settings save,
+   * `analytics_save_settings`; everything else is read-only anyway). No suffix
+   * means `read-only` without OAuth and `standard` with it; an empty or unknown
+   * suffix falls back to `read-only`. See `toolsets.ts`.
+   */
+  toolsets: analyticsToolsets,
+
+  /**
+   * Boot-time hints for active deployments. The code default (:9090) matches a
+   * bare Prometheus, NOT the repo's compose stack (:8460) — without the hint
+   * every analytics query 404s silently.
+   */
+  bootWarnings(env: NodeJS.ProcessEnv): string[] {
+    if (env.PROMETHEUS_URL?.trim()) return []
+    return [
+      "PROMETHEUS_URL is not set — defaulting to http://localhost:9090. The repo's Compose stack publishes Prometheus on :8460 (PROMETHEUS_URL=http://localhost:8460).",
+    ]
+  },
+
+  /**
+   * The module's server-instructions snippet: what `engine` means here (a
+   * metric filter over the configured engines — their fleet aggregate when
+   * omitted, camunda7's saved default does not apply), the periods and the
+   * health routing.
+   */
+  instructions(): string {
+    return analyticsInstructions()
+  },
+
+  createPlugin(
+    config: Record<string, unknown>,
+    shared: AnalyticsModuleShared,
+  ): AppPlugin<MCPServer> {
+    const { toolset, engineIds, ...parsed } = analyticsConfigSchema.parse(config)
+    return createPlugin({
+      ...parsed,
+      engineIds: effectiveEngineIds(shared.engineIds, engineIds),
+      // Resolved once, here: missing → the read-only floor, unknown → warning +
+      // floor. The plugin only ever sees a declared name.
+      toolset: analyticsToolsets.resolve(toolset),
+      fetchBpmnXml: shared.fetchBpmnXml,
+      profileStore: shared.profileStore,
+    })
+  },
+}

package/src/named-views.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from "vitest"
+import type {
+  AnalyticsDashboardData,
+  EngineLandscapeResult,
+  FailureDashboardData,
+} from "@miragon/pulse-analytics-client"
+import { namedDashboard, namedFailureDashboard, namedLandscape } from "./named-views.js"
+import { createNameLookup, type NameLookup } from "./bpmn-name-lookup.js"
+import { elementNameOf, processNameOf } from "./bpmn-names.js"
+
+/**
+ * Every view asks for the names of exactly the ids it lists, no more, by
+ * priority, on the engines its rows come from.
+ */
+describe("named views", () => {
+  const lookup = () => vi.fn<NameLookup>(() => Promise.resolve({}))
+
+  it("the dashboard: its scope, the elements of its activities, then its definitions", async () => {
+    const namesFor = lookup()
+    const data = {
+      processDefinitionKey: "order",
+      engines: ["prod-b", "prod-a", "prod-c"],
+      reportingEngines: ["prod-a", "prod-b"],
+      definitionBreakdown: [{ processDefinitionKey: "order" }, { processDefinitionKey: "refund" }],
+      activityBreakdown: [
+        { processDefinitionKey: "order", activityId: "Task_A" },
+        { processDefinitionKey: "order", activityId: "Task_B" },
+      ],
+    } as unknown as AnalyticsDashboardData
+    const named = await namedDashboard(data, namesFor)
+    expect(named.names).toEqual({})
+    const [keys, request] = namesFor.mock.calls[0]
+    expect([...keys]).toEqual(["order", "order", "order", "order", "refund"])
+    expect(request?.elementIds).toEqual({ order: ["Task_A", "Task_B"], refund: [] })
+    // The reporting engines, in the scope's (configuration) order; a silent one has no rows.
+    expect(request?.engines).toEqual(["prod-b", "prod-a"])
+  })
+
+  it("the dashboard reads on its whole scope when the payload does not say which engines report", async () => {
+    const namesFor = lookup()
+    await namedDashboard(
+      {
+        processDefinitionKey: null,
+        engines: ["prod-a", "prod-b"],
+        definitionBreakdown: [],
+        activityBreakdown: [],
+      } as unknown as AnalyticsDashboardData,
+      namesFor,
+    )
+    expect(namesFor.mock.calls[0][1]?.engines).toEqual(["prod-a", "prod-b"])
+  })
+
+  it("names a process key such as constructor like any other", async () => {
+    const namesFor = lookup()
+    await namedDashboard(
+      {
+        processDefinitionKey: null,
+        engines: null,
+        definitionBreakdown: [{ processDefinitionKey: "constructor" }],
+        activityBreakdown: [{ processDefinitionKey: "constructor", activityId: "Task_A" }],
+      } as unknown as AnalyticsDashboardData,
+      namesFor,
+    )
+    expect(namesFor.mock.calls[0][1]?.elementIds).toEqual({ constructor: ["Task_A"] })
+    expect(namesFor.mock.calls[0][1]?.engines).toBeNull()
+  })
+
+  // The lookup reads at most 40 models per view: a fleet with more
+  // definitions must not lose the names of its bottleneck activities to the
+  // long tail of the breakdown (sorted by starts).
+  it("keeps the activities' names when the fleet has more than 40 definitions", async () => {
+    const fetchBpmnXml = vi.fn((key: string) =>
+      Promise.resolve(
+        `<process id="${key}" name="Process ${key}"><userTask id="Task_Slow" name="Review"/></process>`,
+      ),
+    )
+    const definitions = Array.from({ length: 45 }, (_, i) => ({ processDefinitionKey: `p${i}` }))
+    const data = {
+      processDefinitionKey: null,
+      engines: ["prod-a"],
+      reportingEngines: ["prod-a"],
+      definitionBreakdown: definitions,
+      // A long-running, low-volume process: the last of the breakdown.
+      activityBreakdown: [{ processDefinitionKey: "p44", activityId: "Task_Slow" }],
+    } as unknown as AnalyticsDashboardData
+    const { names } = await namedDashboard(data, createNameLookup(fetchBpmnXml))
+    expect(elementNameOf(names, "p44", "Task_Slow")).toBe("Review")
+    expect(processNameOf(names, "p44")).toBe("Process p44")
+    expect(fetchBpmnXml).toHaveBeenCalledTimes(40)
+    // The cap falls on the end of the breakdown instead.
+    expect(processNameOf(names, "p0")).toBe("Process p0")
+    expect(processNameOf(names, "p40")).toBeNull()
+  })
+
+  it("the failure dashboard: process names only, its most affected first, on its engines", async () => {
+    const failures = lookup()
+    await namedFailureDashboard(
+      {
+        engines: ["prod-a", "prod-b"],
+        errorPatterns: [{ processDefinitionKey: "a" }],
+        processBreakdown: [{ processDefinitionKey: "b" }],
+        mostAffectedProcess: "b",
+      } as unknown as FailureDashboardData,
+      failures,
+    )
+    expect([...failures.mock.calls[0][0]]).toEqual(["b", "a", "b"])
+    expect(failures.mock.calls[0][1]).toEqual({
+      elementIds: { a: [], b: [] },
+      engines: ["prod-a", "prod-b"],
+    })
+
+    const none = lookup()
+    await namedFailureDashboard(
+      {
+        engines: ["prod-a"],
+        errorPatterns: [],
+        processBreakdown: [],
+        mostAffectedProcess: null,
+      } as unknown as FailureDashboardData,
+      none,
+    )
+    expect([...none.mock.calls[0][0]]).toEqual([])
+  })
+
+  it("the landscape: each process read on the engines it runs on", async () => {
+    const landscape = lookup()
+    await namedLandscape(
+      {
+        processes: [
+          { processDefinitionKey: "c", engineIds: ["prod-b", "prod-c"] },
+          { processDefinitionKey: "d", engineIds: ["prod-a"] },
+        ],
+      } as unknown as EngineLandscapeResult,
+      landscape,
+    )
+    expect(landscape.mock.calls[0][1]).toEqual({
+      elementIds: { c: [], d: [] },
+      enginesByKey: { c: ["prod-b", "prod-c"], d: ["prod-a"] },
+    })
+  })
+})

package/src/named-views.ts

@@ -0,0 +1,97 @@
+import type {
+  AnalyticsDashboardData,
+  EngineLandscapeResult,
+  FailureDashboardData,
+} from "@miragon/pulse-analytics-client"
+import type { NameLookup } from "./bpmn-name-lookup.js"
+import type { Named } from "./bpmn-names.js"
+
+/**
+ * The names behind the ids a view lists (U13), added to its payload once,
+ * here — the show tool, its `*_data` feed and the pipeline step of a view
+ * all pass their figures through the same function, so the three paths show
+ * the same names. Names are enrichment: a model that cannot be read leaves
+ * its key out of `names` and the view shows the id, never fails.
+ *
+ * Each model is read on the engines the view's rows come from (a process
+ * that runs only on the third engine is still named), and a view names its
+ * keys by priority: the lookup reads at most so many models per view.
+ */
+
+/**
+ * The dashboard: its scope, then the processes of the activity breakdown
+ * (whose element names the activity table shows: a bottleneck in a
+ * low-volume process must not lose its names to the long tail of the
+ * breakdown), then the per-definition breakdown. Its models are read on the
+ * engines in scope that report, in configuration order.
+ */
+export async function namedDashboard(
+  data: AnalyticsDashboardData,
+  namesFor: NameLookup,
+): Promise<Named<AnalyticsDashboardData>> {
+  const keys = [
+    ...(data.processDefinitionKey ? [data.processDefinitionKey] : []),
+    ...data.activityBreakdown.map((a) => a.processDefinitionKey),
+    ...data.definitionBreakdown.map((d) => d.processDefinitionKey),
+  ]
+  const elementIds = new Map<string, string[]>(keys.map((key) => [key, []]))
+  for (const a of data.activityBreakdown) elementIds.get(a.processDefinitionKey)?.push(a.activityId)
+  return {
+    ...data,
+    names: await namesFor(keys, {
+      elementIds: Object.fromEntries(elementIds),
+      engines: reportingInOrder(data.engines, data.reportingEngines),
+    }),
+  }
+}
+
+/** The failure dashboard: the processes of its incident groups and its per-process table. */
+export async function namedFailureDashboard(
+  data: FailureDashboardData,
+  namesFor: NameLookup,
+): Promise<Named<FailureDashboardData>> {
+  const keys = [
+    ...(data.mostAffectedProcess ? [data.mostAffectedProcess] : []),
+    ...data.errorPatterns.map((p) => p.processDefinitionKey),
+    ...data.processBreakdown.map((p) => p.processDefinitionKey),
+  ]
+  return {
+    ...data,
+    names: await namesFor(keys, { elementIds: noElements(keys), engines: data.engines }),
+  }
+}
+
+/** The landscape: the processes of its what-runs-where matrix, each read on the engines it runs on. */
+export async function namedLandscape(
+  data: EngineLandscapeResult,
+  namesFor: NameLookup,
+): Promise<Named<EngineLandscapeResult>> {
+  const keys = data.processes.map((p) => p.processDefinitionKey)
+  return {
+    ...data,
+    names: await namesFor(keys, {
+      elementIds: noElements(keys),
+      enginesByKey: Object.fromEntries(
+        data.processes.map((p) => [p.processDefinitionKey, p.engineIds]),
+      ),
+    }),
+  }
+}
+
+/** Process names only: no element of these models is on screen. */
+function noElements(keys: readonly string[]): Record<string, string[]> {
+  return Object.fromEntries(keys.map((key) => [key, []]))
+}
+
+/**
+ * The engines in scope (configuration order: the default engine first) that
+ * report metrics: the rows come from them, a silent engine has none. All of
+ * the scope when the payload does not say which report.
+ */
+function reportingInOrder(
+  engines: readonly string[] | null,
+  reporting: readonly string[] | undefined,
+): readonly string[] | null {
+  if (!engines || !reporting) return engines ?? reporting ?? null
+  return engines.filter((id) => reporting.includes(id))
+}

package/src/plugin.ts

@@ -0,0 +1,94 @@
+import type { AppPlugin } from "@miragon/mcp-toolkit-core"
+import type { MCPServer } from "mcp-use"
+import { installMcpRequestContext } from "@miragon/pulse-widget-shell/server"
+import { createPrometheusClient, type PrometheusConfig } from "@miragon/pulse-analytics-client"
+import { registerTools } from "./tools/index.js"
+import { registerSettingsTools } from "./settings-tools.js"
+import { registerWidgetTools } from "./widget-tools.js"
+import { createNameLookup, type FetchBpmnXml } from "./bpmn-name-lookup.js"
+import { definition } from "./definition.js"
+import type { ProfileSource } from "./server-locale.js"
+import { analyticsToolsets } from "./toolsets.js"
+import { createEngineScope } from "./engine-ids.js"
+import type { AnalyticsAppConfig } from "./steps/app-config.js"
+
+/**
+ * `PrometheusConfig` carries the connection: the base URL (e.g.
+ * http://localhost:9090), optional bearer/basic auth + extra headers, and the
+ * per-query deadline (`timeoutMs`).
+ */
+export interface AnalyticsPluginConfig extends PrometheusConfig {
+  /**
+   * Optional BPMN-XML lookup used by widget tools that enrich metric data with
+   * engine lookups — the BPMN heatmap's diagram, and the process and activity
+   * names the dashboards, the failure dashboard and the landscape show in
+   * place of ids. Injected by the host app (which owns the engine client) so
+   * this module stays free of engine SDKs. When absent, the heatmap degrades
+   * to a non-diagram fallback and the views show ids.
+   */
+  fetchBpmnXml?: FetchBpmnXml
+  /**
+   * Profile store (shared with camunda7): locale for model-facing summaries,
+   * plus this module's own settings slice (`modules.analytics`) — read for
+   * period/minBucketSize defaults, written by `analytics_save_settings`.
+   */
+  profileStore?: ProfileSource
+  /**
+   * The module's toolset (`analyticsModule` passes the one the composition
+   * root resolved). `"read-only"` — also what an ABSENT or unknown toolset
+   * resolves to (an unknown name warns) — registers no settings save tool;
+   * `"standard"` registers it, given a writable `profileStore`. Typed `string`
+   * like camunda7's, so callers can pass a configured value through; it is
+   * resolved fail-closed here.
+   */
+  toolset?: string
+  /**
+   * The engine ids analytics may read — the server's configured engines.
+   * Empty or absent: every engine-reading tool refuses (fail-closed), see
+   * `engine-ids.ts`.
+   */
+  engineIds?: readonly string[]
+}
+
+export function createPlugin(config: AnalyticsPluginConfig): AppPlugin<MCPServer> {
+  const client = createPrometheusClient({
+    url: config.url,
+    bearerToken: config.bearerToken,
+    username: config.username,
+    password: config.password,
+    headers: config.headers,
+    timeoutMs: config.timeoutMs,
+  })
+  const engineScope = createEngineScope(config.engineIds)
+  // ONE name lookup (and its per-caller cache) for the tools, the feeds and the steps.
+  const namesFor = createNameLookup(config.fetchBpmnXml)
+  // The steps get the profile store too: a step's omitted period resolves to
+  // the caller's saved default, like every tool's.
+  const appConfig = {
+    client,
+    engineScope,
+    profileStore: config.profileStore,
+    namesFor,
+  } satisfies AnalyticsAppConfig
+  return {
+    definition,
+    appConfig,
+    // Tools and feeds resolve the caller (saved defaults, summary locale) from
+    // the handler ctx. The pipeline steps get none, so their saved-period
+    // lookup reads the ambient request info — installed here like camunda7
+    // does (idempotent; the host installs it too).
+    registerTools: (server) => {
+      installMcpRequestContext(server)
+      registerTools(server, client, engineScope, config.profileStore)
+    },
+    registerWidgetTools: (server) => {
+      registerWidgetTools(server, client, {
+        fetchBpmnXml: config.fetchBpmnXml,
+        namesFor,
+        profileStore: config.profileStore,
+        engineScope,
+      })
+      registerSettingsTools(server, config.profileStore, analyticsToolsets.resolve(config.toolset))
+    },
+  }
+}