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

package/src/prometheus-wiring.test.ts

@@ -0,0 +1,174 @@
+import http from "node:http"
+import type { AddressInfo } from "node:net"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+import type { MCPServer } from "mcp-use"
+import { analyticsModule } from "./module.js"
+import { ANALYTICS_ENGINE_LANDSCAPE_DATA } from "./tool-names.js"
+
+/**
+ * #325 through the module: env → config → plugin → Prometheus client → tool.
+ * A real local HTTP server plays Prometheus, so the auth headers, the
+ * deadline and the caller's cancellation are observed on the wire.
+ */
+
+type ToolCallback = (
+  args: Record<string, unknown>,
+  ctx?: unknown,
+) => Promise<{ isError?: boolean; content: Array<{ type: string; text: string }> }>
+
+const seenAuth: Array<string | undefined> = []
+const seenTenant: Array<string | string[] | undefined> = []
+let hang = false
+
+const prometheus = http.createServer((req, res) => {
+  seenAuth.push(req.headers.authorization)
+  seenTenant.push(req.headers["x-scope-orgid"])
+  if (hang) return
+  res.writeHead(200, { "Content-Type": "application/json" })
+  res.end(JSON.stringify({ status: "success", data: { resultType: "vector", result: [] } }))
+})
+
+let url = ""
+
+beforeAll(async () => {
+  await new Promise<void>((resolve) => prometheus.listen(0, "127.0.0.1", resolve))
+  url = `http://127.0.0.1:${(prometheus.address() as AddressInfo).port}`
+})
+
+afterAll(async () => {
+  prometheus.closeAllConnections()
+  await new Promise<void>((resolve) => prometheus.close(() => resolve()))
+})
+
+/** A standalone analytics boot names the engines it may read (`engine-ids.ts`). */
+const ENGINES = { ANALYTICS_ENGINE_IDS: "prod-a,prod-b" }
+
+/** Boots the module from env the way the composition root does; returns its tools. */
+function boot(env: NodeJS.ProcessEnv) {
+  const tools = new Map<string, ToolCallback>()
+  const server = {
+    tool: (definition: { name: string }, callback: ToolCallback) => {
+      tools.set(definition.name, callback)
+    },
+    use: () => {},
+  } as unknown as MCPServer
+  const plugin = analyticsModule.createPlugin(
+    {
+      ...analyticsModule.configFromEnv({ PROMETHEUS_URL: url, ...ENGINES, ...env }),
+      toolset: "read-only",
+    },
+    {},
+  )
+  plugin.registerTools?.(server)
+  plugin.registerWidgetTools?.(server)
+  return tools
+}
+
+describe("Prometheus config reaches the wire", () => {
+  it("PROMETHEUS_BEARER_TOKEN authenticates every query of a registrar tool", async () => {
+    hang = false
+    seenAuth.length = 0
+    const tools = boot({ PROMETHEUS_BEARER_TOKEN: "tok-123" })
+    const result = await tools.get("analytics_engine_landscape")!({})
+    expect(result.isError).toBeFalsy()
+    expect(seenAuth.length).toBeGreaterThan(0)
+    expect(seenAuth.every((auth) => auth === "Bearer tok-123")).toBe(true)
+  })
+
+  it("PROMETHEUS_HEADERS and PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD reach every query", async () => {
+    hang = false
+    seenAuth.length = 0
+    seenTenant.length = 0
+    const tools = boot({
+      PROMETHEUS_HEADERS: '{"X-Scope-OrgID":"tenant-a"}',
+      PROMETHEUS_USERNAME: "grafana",
+      PROMETHEUS_PASSWORD: "hunter2-pass",
+    })
+    const result = await tools.get("analytics_engine_landscape")!({})
+    expect(result.isError).toBeFalsy()
+    expect(seenTenant.length).toBeGreaterThan(0)
+    expect(seenTenant.every((tenant) => tenant === "tenant-a")).toBe(true)
+    const basic = `Basic ${Buffer.from("grafana:hunter2-pass").toString("base64")}`
+    expect(seenAuth.every((auth) => auth === basic)).toBe(true)
+  })
+
+  it("PROMETHEUS_TIMEOUT_MS bounds a hung Prometheus", async () => {
+    hang = true
+    const tools = boot({ PROMETHEUS_TIMEOUT_MS: "60" })
+    const result = await tools.get("analytics_engine_landscape")!({})
+    expect(result.isError).toBe(true)
+    expect(result.content[0].text).toBe("Prometheus did not respond within 60 ms (timeout)")
+  })
+
+  it("EVERY widget tool and feed hands ctx.signal to its queries", async () => {
+    hang = false
+    const tools = new Map<string, ToolCallback>()
+    const server = {
+      tool: (definition: { name: string }, callback: ToolCallback) => {
+        tools.set(definition.name, callback)
+      },
+    } as unknown as MCPServer
+    analyticsModule
+      .createPlugin(
+        {
+          ...analyticsModule.configFromEnv({ PROMETHEUS_URL: url, ...ENGINES }),
+          toolset: "read-only",
+        },
+        {},
+      )
+      .registerWidgetTools?.(server)
+    // Each handler runs twice with args every tool accepts: unsignalled it
+    // must reach Prometheus, with an already-aborted ctx.signal it must not —
+    // a handler that drops ctx would still query. Tools that never query are
+    // named.
+    const args = {
+      processDefinitionKey: "order",
+      // Handlers called directly get no schema defaults: the compare windows.
+      windowDays: 7,
+      windowBeforeDays: 3,
+      windowAfterDays: 3,
+      // Relative to now: compare windows are held inside the retention.
+      deploymentTimestamp: new Date(Date.now() - 3 * 86_400_000).toISOString(),
+      engineA: "prod-a",
+      engineB: "prod-b",
+    }
+    const queriesOf = async (name: string, ctx: { signal?: AbortSignal }) => {
+      const before = seenAuth.length
+      await tools.get(name)!(args, ctx)
+      return seenAuth.length - before
+    }
+    const neverQuery: string[] = []
+    for (const name of tools.keys()) {
+      if ((await queriesOf(name, {})) === 0) {
+        neverQuery.push(name)
+        continue
+      }
+      expect({ name, queries: await queriesOf(name, { signal: AbortSignal.abort() }) }).toEqual({
+        name,
+        queries: 0,
+      })
+    }
+    // The settings and the heatmap's diagram (read from the engine) never ask Prometheus.
+    expect(neverQuery.sort()).toEqual([
+      "analytics_bpmn_xml_data",
+      "analytics_settings_data",
+      "analytics_show_settings",
+    ])
+    expect(tools.size - neverQuery.length).toBeGreaterThanOrEqual(11)
+  })
+
+  it("a widget feed's ctx.signal cancels its queries before the deadline", async () => {
+    hang = true
+    const tools = boot({ PROMETHEUS_TIMEOUT_MS: "10000" })
+    const controller = new AbortController()
+    setTimeout(() => controller.abort(), 30)
+    const started = Date.now()
+    const result = await tools.get(ANALYTICS_ENGINE_LANDSCAPE_DATA)!(
+      {},
+      { signal: controller.signal },
+    )
+    expect(Date.now() - started).toBeLessThan(5_000)
+    expect(result.isError).toBe(true)
+    expect(result.content[0].text).toBe("Prometheus query cancelled by the caller")
+  })
+})

package/src/server-locale.ts

@@ -0,0 +1,59 @@
+import {
+  createLocalizeFor,
+  createLocalizeViewFor,
+  resolveAuthUserId,
+  resolveProfileKey,
+} from "@miragon/pulse-widget-shell/server"
+import { translator } from "./messages/index.js"
+
+/**
+ * The profile port + key resolution come from the shared server kit, NOT from a
+ * module-local copy: every module reads and writes the same profile record, so
+ * a divergent key precedence (or a differently-spelled anonymous fallback)
+ * would silently split a user's settings across two records. Re-exported under
+ * this module's names so the call sites read in analytics vocabulary.
+ *
+ * `ProfileSource` is the minimal read/write view a module needs — the locale
+ * plus its own slice under `modules.analytics`. camunda7's `ProfileStore`
+ * satisfies it structurally, without analytics depending on the camunda7
+ * module; `save` merges per module key on the store side, so writing
+ * `modules.analytics` never touches other modules' slices.
+ */
+export type { ProfileSlice, ProfileSource } from "@miragon/pulse-widget-shell/server"
+
+/**
+ * Resolve the profile key for the in-flight request: the OAuth caller (off the
+ * tool-handler `ctx`), else `anonymous` for an explicitly declared local
+ * caller (stdio, tests). A request without OAuth resolves `undefined` — reads
+ * fall back to defaults, saves fail visibly, so unrelated callers never
+ * cross-share one record.
+ */
+export const resolveSettingsKey = resolveProfileKey
+
+/**
+ * Just the OAuth half of {@link resolveSettingsKey} — the save path stamps it
+ * onto the record as its owner (`opts.userId`).
+ */
+export const resolveSettingsAuthUserId = resolveAuthUserId
+
+/** A locale-bound translate for summaries; a show tool's summary translate + view title. */
+export type { ServerT, ViewLocale } from "@miragon/pulse-widget-shell/server"
+
+/**
+ * Resolve the request locale and return a translate bound to it + the analytics
+ * catalogs — `const t = await localizeFor(store, ctx); … summary: t("key", { … })`.
+ * Pass the tool-handler `ctx` so an auth user id resolves the same record the
+ * save path writes. Locale resolution + the fail-soft rules (no store, no key,
+ * store OUTAGE → English) come from the shared `createLocalizeFor`.
+ */
+export const localizeFor = createLocalizeFor(translator)
+
+/**
+ * {@link localizeFor} plus the view title, from ONE profile read — the kit's
+ * one title rule for every module's show tools: a view is titled only in a
+ * language the profile names; with "system" (the default), no caller or a
+ * store outage it carries no title, and the widget's own heading names it in
+ * the host's language (#322 U3). Summaries stay `t`:
+ * `const { t, title } = await localizeViewFor(store, ctx); … title: title("key")`.
+ */
+export const localizeViewFor = createLocalizeViewFor(translator)

package/src/settings-tools.ts

@@ -0,0 +1,170 @@
+import type { MCPServer } from "mcp-use"
+import {
+  appOnly,
+  buildDataFeedResult,
+  buildSingleWidgetView,
+  requireProfileKey,
+  saveModuleSlice,
+  showToolBinding,
+  withToolErrors,
+  strictToolInput,
+} from "@miragon/pulse-widget-shell/server"
+import { ANALYTICS_SAVE_SETTINGS, ANALYTICS_SETTINGS_DATA } from "./tool-names.js"
+import {
+  localizeFor,
+  localizeViewFor,
+  resolveSettingsAuthUserId,
+  resolveSettingsKey,
+  type ProfileSource,
+  type ServerT,
+} from "./server-locale.js"
+import {
+  ANALYTICS_MODULE_KEY,
+  analyticsSettingsSaveInput,
+  parseAnalyticsSettings,
+  settingsFor,
+  type AnalyticsSettings,
+} from "./settings.js"
+import { allowsDurableWrites, type AnalyticsToolset } from "./toolsets.js"
+
+/**
+ * The analytics module's settings section — its own show/data/save tool triple
+ * (the three render paths), so the module plugs into the settings page without
+ * camunda7 owning any analytics vocabulary. The slice persists under
+ * `modules.analytics` in the shared profile record; the shared store merges
+ * per module key, so this never touches other modules' slices.
+ */
+
+/** What the settings widget renders: the effective slice + whether saving is wired. */
+export interface AnalyticsSettingsView {
+  settings: AnalyticsSettings
+  /**
+   * False without a writable store, in the `read-only` toolset (also what a
+   * missing toolset resolves to), or when the request carries no caller
+   * identity (no OAuth — see `resolveProfileKey`) — the widget hides Save.
+   */
+  canSave: boolean
+}
+
+export function registerSettingsTools(
+  server: MCPServer,
+  profileStore?: ProfileSource,
+  toolset?: AnalyticsToolset,
+): void {
+  // The save tool is a durable write registered OUTSIDE the tool registrar, so
+  // it gates itself against the module's toolset (see `allowsDurableWrites`):
+  // only `standard` saves. A missing toolset resolves to the `read-only`
+  // floor, and an unknown name from an untyped caller warns and degrades to it.
+  const store = profileStore
+  const save = allowsDurableWrites(toolset) ? store?.save?.bind(store) : undefined
+
+  const loadView = async (ctx: unknown): Promise<AnalyticsSettingsView> => ({
+    settings: await settingsFor(store, ctx),
+    // Store/toolset gate AND per-request identity: without a profile key the
+    // save tool refuses, so the section must render read-only instead of a
+    // Save button whose click errors.
+    canSave: Boolean(save) && resolveSettingsKey(ctx) !== undefined,
+  })
+
+  const summarize = (t: ServerT, view: AnalyticsSettingsView): string =>
+    t("aSum.settings", {
+      period: view.settings.defaultPeriod,
+      minBucketSize: view.settings.minBucketSize,
+      changeHint: view.canSave ? t("aSum.settingsChangeHint") : "",
+    })
+
+  server.tool(
+    {
+      name: "analytics_show_settings",
+      title: "Analytics Settings",
+      description:
+        "Open the analytics settings section: the default look-back period and the minimum comparison bucket size applied when analytics calls omit them.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput({}),
+      ...showToolBinding("analytics_show_settings", "Analytics Settings"),
+    },
+    withToolErrors(async (_params, ctx) => {
+      const view = await loadView(ctx)
+      const { t, title } = await localizeViewFor(store, ctx)
+      return buildSingleWidgetView({
+        widget: "analytics:settings",
+        app: "analytics",
+        dataType: "analytics:settings",
+        data: { ...view },
+        // The view title in the language the profile names (the section
+        // heading's own key); none with "system", where the heading names it.
+        title: title("aSettings.heading"),
+        summary: summarize(t, view),
+      })
+    }),
+  )
+
+  server.tool(
+    {
+      name: ANALYTICS_SETTINGS_DATA,
+      title: "Analytics settings data (internal)",
+      description:
+        "Internal JSON feed (no UI) for the analytics settings section's self-fetch. Prefer analytics_show_settings.",
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: strictToolInput({}),
+      ...appOnly,
+    },
+    withToolErrors(async (_params, ctx) => buildDataFeedResult({ ...(await loadView(ctx)) })),
+  )
+
+  // Without a writable store (or on the `read-only` floor) there is nothing to
+  // save into — the section stays read-only (canSave: false) and the tool
+  // surface honestly reflects that.
+  if (!save || !store) return
+
+  server.tool(
+    {
+      name: ANALYTICS_SAVE_SETTINGS,
+      title: "Save analytics settings",
+      description:
+        "Update the caller's analytics defaults. Only the provided fields change; omitted fields keep their value. The saved defaults apply whenever an analytics call omits `period` or `minBucketSize`.",
+      // The module's only non-read-only tool, and explicitly NOT destructive
+      // (MCP presumes a write destructive unless told otherwise): it merges
+      // the caller's own slice, nothing is deleted or overwritten wholesale.
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: strictToolInput(analyticsSettingsSaveInput.shape),
+      // No view binding / app visibility: a normal model-visible tool; the
+      // settings widget also calls it and reads the saved slice back from
+      // structuredContent.
+    },
+    withToolErrors(async (params, ctx) => {
+      // Keyless refusal + a patch-only slice save are the shared slice-write
+      // contract (`@miragon/pulse-widget-shell/server`) — every module's save
+      // tool uses the same pair. The store merges the patch under its per-key
+      // lock, so a concurrent save of the other field is never reverted.
+      const key = requireProfileKey(ctx)
+      // The OAuth caller is stamped as the record's owner.
+      const savedSlice = await saveModuleSlice(
+        { get: (k) => store.get(k), save },
+        key,
+        ANALYTICS_MODULE_KEY,
+        params,
+        { userId: resolveSettingsAuthUserId(ctx) },
+      )
+      const effective = parseAnalyticsSettings({ [ANALYTICS_MODULE_KEY]: savedSlice })
+      const t = await localizeFor(store, ctx)
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: t("aSum.settingsSaved", {
+              period: effective.defaultPeriod,
+              minBucketSize: effective.minBucketSize,
+            }),
+          },
+        ],
+        structuredContent: effective as unknown as Record<string, unknown>,
+      }
+    }),
+  )
+}