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

package/src/settings.test.ts

@@ -0,0 +1,402 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { parseToolResult } from "@miragon/mcp-toolkit-ui"
+import type { MCPServer } from "mcp-use"
+import {
+  createInMemoryProfileStore,
+  runWithMcpRequestInfo,
+} from "@miragon/pulse-widget-shell/server"
+import {
+  analyticsSettingsSaveInput,
+  analyticsSettingsSchema,
+  parseAnalyticsSettings,
+  settingsFor,
+} from "./settings.js"
+import { registerSettingsTools } from "./settings-tools.js"
+import { ANALYTICS_SAVE_SETTINGS, ANALYTICS_SETTINGS_DATA } from "./tool-names.js"
+import { localizeFor, type ProfileSource } from "./server-locale.js"
+import type { AnalyticsToolset } from "./toolsets.js"
+
+/** A feed's payload as the widget reads it (feeds answer in JSON text only). */
+const feedData = <T = Record<string, unknown>>(result: unknown): T => parseToolResult<T>(result)
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+/** A signed-in caller's handler ctx (mcp-use's flattened `ctx.auth`). */
+const CTX = { auth: { user: { id: "user-1" } } }
+
+describe("analyticsSettingsSchema", () => {
+  it("fills every default from an empty object", () => {
+    expect(analyticsSettingsSchema.parse({})).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+  })
+})
+
+describe("analyticsSettingsSaveInput", () => {
+  // Zod 4 re-applies `.default()`s through `.partial()` — the save input must
+  // stay default-free so a single-field save can't reset the other saved value
+  // at the tool boundary.
+  it("keeps omitted fields ABSENT instead of materializing defaults", () => {
+    expect(analyticsSettingsSaveInput.parse({ minBucketSize: 5 })).toEqual({ minBucketSize: 5 })
+    expect(analyticsSettingsSaveInput.parse({})).toEqual({})
+  })
+})
+
+describe("parseAnalyticsSettings", () => {
+  it("returns defaults when the slice is absent", () => {
+    expect(parseAnalyticsSettings(undefined)).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+    expect(parseAnalyticsSettings({})).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+  })
+
+  it("returns defaults for a garbage slice (fail-soft)", () => {
+    expect(parseAnalyticsSettings({ analytics: "nope" })).toEqual({
+      defaultPeriod: "7d",
+      minBucketSize: 10,
+    })
+    expect(parseAnalyticsSettings({ analytics: { defaultPeriod: "yesterday" } })).toEqual({
+      defaultPeriod: "7d",
+      minBucketSize: 10,
+    })
+  })
+
+  it("degrades per FIELD: one invalid value keeps the other saved preference", () => {
+    expect(
+      parseAnalyticsSettings({ analytics: { defaultPeriod: "yesterday", minBucketSize: 5 } }),
+    ).toEqual({ defaultPeriod: "7d", minBucketSize: 5 })
+  })
+
+  it("parses a valid slice and fills missing fields with defaults", () => {
+    expect(parseAnalyticsSettings({ analytics: { defaultPeriod: "30d" } })).toEqual({
+      defaultPeriod: "30d",
+      minBucketSize: 10,
+    })
+  })
+
+  it("ignores other modules' slices", () => {
+    expect(parseAnalyticsSettings({ other: { defaultPeriod: "1d" } })).toEqual({
+      defaultPeriod: "7d",
+      minBucketSize: 10,
+    })
+  })
+})
+
+describe("settingsFor", () => {
+  it("returns defaults without a store", async () => {
+    expect(await settingsFor(undefined)).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+  })
+
+  it("reads the slice off the profile record", async () => {
+    const store: ProfileSource = {
+      get: () =>
+        Promise.resolve({ modules: { analytics: { defaultPeriod: "14d", minBucketSize: 3 } } }),
+    }
+    expect(await settingsFor(store, CTX)).toEqual({ defaultPeriod: "14d", minBucketSize: 3 })
+    // No caller identity → the defaults, never someone else's slice.
+    expect(await settingsFor(store)).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+  })
+
+  it("falls back to defaults when the store throws (outage must not fail analytics reads)", async () => {
+    const store: ProfileSource = {
+      get: () => Promise.reject(new Error("connection refused")),
+    }
+    expect(await settingsFor(store, CTX)).toEqual({ defaultPeriod: "7d", minBucketSize: 10 })
+  })
+})
+
+describe("localizeFor", () => {
+  it("binds the translate to the profile language", async () => {
+    const store: ProfileSource = { get: () => Promise.resolve({ language: "de" }) }
+    const t = await localizeFor(store, CTX)
+    expect(t("aSettings.heading")).toBe("Analyse-Einstellungen")
+  })
+
+  it("falls back to English on a store OUTAGE, like settingsFor", async () => {
+    const store: ProfileSource = { get: () => Promise.reject(new Error("connection refused")) }
+    const t = await localizeFor(store, CTX)
+    expect(t("aSettings.heading")).toBe("Analytics settings")
+  })
+})
+
+describe("registerSettingsTools", () => {
+  // `toolset` is a plain string here on purpose: an untyped (JS) caller can
+  // hand the gate any name, and the gate must still resolve it fail-closed.
+  function registeredToolNames(store?: ProfileSource, toolset?: string): string[] {
+    const tool = vi.fn()
+    const server = { tool } as unknown as MCPServer
+    registerSettingsTools(server, store, toolset as AnalyticsToolset | undefined)
+    return tool.mock.calls.map((c) => (c[0] as { name: string }).name)
+  }
+
+  const writable: ProfileSource = {
+    get: () => Promise.resolve(undefined),
+    save: () => Promise.resolve({}),
+  }
+
+  it('registers the save tool with a writable store in the "standard" toolset', () => {
+    expect(registeredToolNames(writable, "standard")).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+      ANALYTICS_SAVE_SETTINGS,
+    ])
+  })
+
+  it("stays read-only without a writable store (no save tool), even in standard", () => {
+    const readOnly: ProfileSource = { get: () => Promise.resolve(undefined) }
+    expect(registeredToolNames(readOnly, "standard")).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+    ])
+    expect(registeredToolNames(undefined, "standard")).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+    ])
+  })
+
+  it("fails closed WITHOUT a toolset: a writable store alone registers no save tool", () => {
+    // A missing toolset is the read-only floor (silently — it is the
+    // documented default of a direct caller, not a misconfiguration).
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    expect(registeredToolNames(writable)).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+    ])
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('drops the durable save tool in the "read-only" toolset, fails closed on unknown names', () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    expect(registeredToolNames(writable, "read-only")).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+    ])
+    expect(registeredToolNames(writable, "nonsense")).toEqual([
+      "analytics_show_settings",
+      ANALYTICS_SETTINGS_DATA,
+    ])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('Unknown toolset "nonsense"'))
+  })
+
+  it("a save-less section reports canSave false even for an identified caller", async () => {
+    const tool = vi.fn()
+    registerSettingsTools({ tool } as unknown as MCPServer, writable, "read-only")
+    const data = tool.mock.calls.find(
+      (c) => (c[0] as { name: string }).name === ANALYTICS_SETTINGS_DATA,
+    )![1] as () => Promise<unknown>
+    const view = await runWithMcpRequestInfo({ authUserId: "user-7" }, () => data())
+    expect(feedData(view).canSave).toBe(false)
+  })
+
+  it("the model summary points at the save tool only when it is registered", async () => {
+    type ShowResult = {
+      content: Array<{ text: string }>
+      structuredContent: Record<string, unknown>
+    }
+    const show = async (toolset: AnalyticsToolset): Promise<ShowResult> => {
+      const tool = vi.fn()
+      registerSettingsTools({ tool } as unknown as MCPServer, writable, toolset)
+      const handler = tool.mock.calls.find(
+        (c) => (c[0] as { name: string }).name === "analytics_show_settings",
+      )![1] as () => Promise<ShowResult>
+      return runWithMcpRequestInfo({ authUserId: "user-7" }, () => handler())
+    }
+    const defaults = { defaultPeriod: "7d", minBucketSize: 10 }
+
+    const standard = await show("standard")
+    expect(standard.content[0].text).toBe(
+      "Analytics settings: default period 7d, min bucket size 10. Change via analytics_save_settings.",
+    )
+    // A caller whose profile names no language follows the host: the server
+    // sets no view title (an English one would sit over a German view), and
+    // the section's own heading names the view (#322 U3).
+    expect(standard.structuredContent.title).toBeUndefined()
+    expect(standard.structuredContent).toMatchObject({
+      layout: [{ row: [{ widget: "analytics:settings" }] }],
+      context: {
+        stepData: {
+          result: {
+            data: { settings: defaults, canSave: true },
+            _app: "analytics",
+            _dataType: "analytics:settings",
+          },
+        },
+      },
+    })
+
+    // On the read-only floor the save tool does not exist — advertising it to
+    // the model would send it to an unknown tool.
+    const readOnly = await show("read-only")
+    expect(readOnly.content[0].text).toBe(
+      "Analytics settings: default period 7d, min bucket size 10.",
+    )
+    expect(readOnly.structuredContent).toMatchObject({
+      context: { stepData: { result: { data: { settings: defaults, canSave: false } } } },
+    })
+  })
+
+  it("declares honest metadata for the settings triple", () => {
+    const tool = vi.fn()
+    registerSettingsTools({ tool } as unknown as MCPServer, writable, "standard")
+    const definitions = tool.mock.calls.map(
+      (c) =>
+        c[0] as {
+          name: string
+          title?: string
+          description?: string
+          annotations?: Record<string, boolean>
+        },
+    )
+    const readOnlyRead = { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    expect(definitions.map(({ name, annotations }) => [name, annotations])).toEqual([
+      ["analytics_show_settings", readOnlyRead],
+      [ANALYTICS_SETTINGS_DATA, readOnlyRead],
+      [
+        ANALYTICS_SAVE_SETTINGS,
+        { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      ],
+    ])
+    for (const { name, title, description } of definitions) {
+      expect(title, `${name} title`).toBeTruthy()
+      expect(description, `${name} description`).toBeTruthy()
+    }
+  })
+
+  it("round-trips a save through the caller's record", async () => {
+    const store = createInMemoryProfileStore()
+    const tool = vi.fn()
+    registerSettingsTools({ tool } as unknown as MCPServer, store, "standard")
+    type Handler = (
+      params: unknown,
+      ctx?: unknown,
+    ) => Promise<{
+      structuredContent?: Record<string, unknown>
+      content?: Array<{ type?: string; text?: string }>
+    }>
+    const handlerFor = (name: string): Handler => {
+      const call = tool.mock.calls.find((c) => (c[0] as { name: string }).name === name)
+      if (!call) throw new Error(`tool ${name} not registered`)
+      return call[1] as Handler
+    }
+
+    const saved = await handlerFor(ANALYTICS_SAVE_SETTINGS)({ defaultPeriod: "30d" }, CTX)
+    // The widget reads the EFFECTIVE slice back from structuredContent; the
+    // model gets the localized confirmation.
+    expect(saved.structuredContent).toEqual({ defaultPeriod: "30d", minBucketSize: 10 })
+    expect(saved.content).toEqual([
+      {
+        type: "text",
+        text: "Analytics settings saved: default period 30d, min bucket size 10.",
+      },
+    ])
+    // Only the provided field is persisted — no defaults materialized into
+    // storage, so a later default change applies to fields never set.
+    expect((await store.get("user-1"))?.modules).toEqual({
+      analytics: { defaultPeriod: "30d" },
+    })
+    const data = await handlerFor(ANALYTICS_SETTINGS_DATA)({}, CTX)
+    expect(feedData(data).settings).toEqual({ defaultPeriod: "30d", minBucketSize: 10 })
+  })
+
+  it("a partial save keeps the other saved value (the store merges the patch)", async () => {
+    const store = createInMemoryProfileStore()
+    const tool = vi.fn()
+    registerSettingsTools({ tool } as unknown as MCPServer, store, "standard")
+    const call = tool.mock.calls.find(
+      (c) => (c[0] as { name: string }).name === ANALYTICS_SAVE_SETTINGS,
+    )
+    const save = call![1] as (
+      params: unknown,
+      ctx: unknown,
+    ) => Promise<{ structuredContent?: unknown }>
+
+    await save({ defaultPeriod: "30d" }, CTX)
+    const saved = await save({ minBucketSize: 5 }, CTX)
+    expect((await store.get("user-1"))?.modules).toEqual({
+      analytics: { defaultPeriod: "30d", minBucketSize: 5 },
+    })
+    // The report is the SAVED slice, not just this call's patch.
+    expect(saved.structuredContent).toEqual({ defaultPeriod: "30d", minBucketSize: 5 })
+  })
+
+  it("concurrent saves of the two fields keep both, even when one already held a value", async () => {
+    // Writes land after a round-trip, like a database's: the second save runs
+    // while the first one's write is still in flight. A save that handed the
+    // store a slice pre-read outside its lock would write the stale period back.
+    const inner = createInMemoryProfileStore()
+    await inner.save("user-1", { modules: { analytics: { defaultPeriod: "7d" } } })
+    const store: ProfileSource = {
+      get: (key) => inner.get(key),
+      save: async (key, input, opts) => {
+        await new Promise((resolve) => setTimeout(resolve, 10))
+        return inner.save(key, input, opts)
+      },
+    }
+    const tool = vi.fn()
+    registerSettingsTools({ tool } as unknown as MCPServer, store, "standard")
+    const save = tool.mock.calls.find(
+      (c) => (c[0] as { name: string }).name === ANALYTICS_SAVE_SETTINGS,
+    )![1] as (params: unknown, ctx: unknown) => Promise<unknown>
+
+    const first = save({ defaultPeriod: "30d" }, CTX)
+    await new Promise((resolve) => setTimeout(resolve, 1))
+    await Promise.all([first, save({ minBucketSize: 25 }, CTX)])
+    expect((await inner.get("user-1"))?.modules).toEqual({
+      analytics: { defaultPeriod: "30d", minBucketSize: 25 },
+    })
+  })
+
+  // HTTP without OAuth: the ambient request info exists but carries no
+  // identity — the section must go read-only and the save tool must refuse
+  // with an actionable cause.
+  it("identity gating: canSave false + save refusal without identity, true with an auth user", async () => {
+    const tool = vi.fn()
+    registerSettingsTools(
+      { tool } as unknown as MCPServer,
+      { get: () => Promise.resolve(undefined), save: () => Promise.resolve({}) },
+      "standard",
+    )
+    type Handler = (
+      params: unknown,
+      ctx?: unknown,
+    ) => Promise<{
+      structuredContent?: Record<string, unknown>
+      content?: Array<{ text?: string }>
+      isError?: boolean
+    }>
+    const handlerFor = (name: string): Handler => {
+      const call = tool.mock.calls.find((c) => (c[0] as { name: string }).name === name)
+      if (!call) throw new Error(`tool ${name} not registered`)
+      return call[1] as Handler
+    }
+
+    const bare = await runWithMcpRequestInfo({}, () => handlerFor(ANALYTICS_SETTINGS_DATA)({}))
+    expect(feedData(bare).canSave).toBe(false)
+    const refused = await runWithMcpRequestInfo({}, () =>
+      handlerFor(ANALYTICS_SAVE_SETTINGS)({ defaultPeriod: "30d" }),
+    )
+    expect(refused.isError).toBe(true)
+    expect(refused.content?.[0]?.text).toContain("MCP_OAUTH")
+
+    const authed = await runWithMcpRequestInfo({ authUserId: "user-7" }, () =>
+      handlerFor(ANALYTICS_SETTINGS_DATA)({}),
+    )
+    expect(feedData(authed).canSave).toBe(true)
+  })
+
+  it("stamps the OAuth caller on the saved record as its owner", async () => {
+    const save = vi.fn<NonNullable<ProfileSource["save"]>>(() => Promise.resolve({}))
+    const tool = vi.fn()
+    registerSettingsTools(
+      { tool } as unknown as MCPServer,
+      { get: () => Promise.resolve(undefined), save },
+      "standard",
+    )
+    const handler = tool.mock.calls.find(
+      (c) => (c[0] as { name: string }).name === ANALYTICS_SAVE_SETTINGS,
+    )![1] as (params: unknown) => Promise<unknown>
+
+    await runWithMcpRequestInfo({ authUserId: "user-7" }, () => handler({ minBucketSize: 5 }))
+    expect(save).toHaveBeenCalledOnce()
+    expect(save.mock.calls[0][1]).toEqual({ modules: { analytics: { minBucketSize: 5 } } })
+    expect(save.mock.calls[0][2]).toEqual({ userId: "user-7" })
+  })
+})

package/src/settings.ts

@@ -0,0 +1,114 @@
+import { z } from "zod"
+import { PERIODS } from "@miragon/pulse-analytics-client"
+import { parseModuleSlice } from "@miragon/pulse-widget-shell/server"
+import type { ProfileSource } from "./server-locale.js"
+import { resolveSettingsKey } from "./server-locale.js"
+
+/**
+ * The analytics module's OWN settings slice, persisted under
+ * `profile.modules.analytics` in the shared profile record (see the camunda7
+ * `modules` field — the profile transports the slice, this module owns its
+ * schema). Read fail-soft: a missing/foreign slice yields the defaults, so a
+ * stale or hand-edited record can never break analytics tools.
+ */
+export const analyticsSettingsSchema = z.object({
+  defaultPeriod: z
+    .enum(PERIODS)
+    .default("7d")
+    .describe("Default look-back window applied when an analytics call omits `period`."),
+  minBucketSize: z
+    .number()
+    .int()
+    .min(1)
+    .default(10)
+    .describe(
+      "Default minimum per-window instance count before comparison results are flagged `suppressed`, applied when a compare call omits `minBucketSize`.",
+    ),
+})
+
+export type AnalyticsSettings = z.infer<typeof analyticsSettingsSchema>
+
+/**
+ * The save tool's input — deliberately default-FREE: zod 4 re-applies
+ * `.default()`s through `.partial()` on parse, so a defaulted partial would
+ * materialize omitted fields at the tool boundary and a "single-field" save
+ * would silently reset the other saved value. With this shape, omitted keys
+ * stay absent and the handler's merge keeps them unchanged.
+ *
+ * Spelled out by hand because the save descriptions differ from the schema's
+ * ("Omitted → unchanged" is what the model needs at a write boundary). When the
+ * descriptions can be shared, derive it instead:
+ * `z.object(withoutDefaults(analyticsSettingsSchema.shape)).partial()`
+ * (`withoutDefaults` from `@miragon/pulse-widget-shell/server`) — which is what
+ * camunda7's `userProfileSaveInput` does.
+ */
+export const analyticsSettingsSaveInput = z.object({
+  defaultPeriod: z
+    .enum(PERIODS)
+    .optional()
+    .describe("New default look-back period. Omitted → unchanged."),
+  minBucketSize: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("New minimum comparison bucket size. Omitted → unchanged."),
+})
+
+/**
+ * `period` at the tool boundary is optional (no zod default) so an omitted
+ * value is distinguishable and can fall back to the user's saved analytics
+ * default before the schema default applies. Derived from PERIODS — never a
+ * copied enum. Shared by the widget tools and the registrar tools.
+ */
+export const optionalPeriod = z
+  .enum(PERIODS)
+  .optional()
+  .describe("Analysis time period. Omitted → the user's saved analytics default (else 7d).")
+
+/** Same optional-at-the-boundary treatment for `minBucketSize`. */
+export const optionalMinBucketSize = z
+  .number()
+  .int()
+  .min(1)
+  .optional()
+  .describe(
+    "Minimum per-window instance count before results are flagged `suppressed`. Omitted → the user's saved analytics default (else 10).",
+  )
+
+/** The module's slice key inside `profile.modules`. */
+export const ANALYTICS_MODULE_KEY = "analytics"
+
+/**
+ * The slice parsed leniently: garbage or absence yields the defaults —
+ * per FIELD (shared `parseModuleSlice`), so one invalid value keeps the
+ * other saved preference intact.
+ */
+export function parseAnalyticsSettings(
+  modules: Record<string, unknown> | undefined,
+): AnalyticsSettings {
+  return parseModuleSlice(analyticsSettingsSchema, modules?.[ANALYTICS_MODULE_KEY])
+}
+
+/**
+ * Resolve the request's effective analytics settings from the shared profile
+ * store — the single place tools apply the "explicit arg > saved setting >
+ * schema default" precedence for `period`/`minBucketSize`. Fail-soft on every
+ * axis: no store, no resolvable key, or a store OUTAGE all yield the schema
+ * defaults — a profile-store hiccup must never fail an analytics read that
+ * only needs Prometheus.
+ */
+export async function settingsFor(
+  store: ProfileSource | undefined,
+  ctx?: unknown,
+): Promise<AnalyticsSettings> {
+  if (!store) return analyticsSettingsSchema.parse({})
+  const key = resolveSettingsKey(ctx)
+  if (!key) return analyticsSettingsSchema.parse({})
+  try {
+    const profile = await store.get(key)
+    return parseAnalyticsSettings(profile?.modules)
+  } catch {
+    return analyticsSettingsSchema.parse({})
+  }
+}

package/src/steps/app-config.ts

@@ -0,0 +1,75 @@
+import { PERIODS, type PrometheusClient, type Period } from "@miragon/pulse-analytics-client"
+import type { AnalyticsEngineScope } from "../engine-ids.js"
+import type { ProfileSource } from "../server-locale.js"
+import { settingsFor } from "../settings.js"
+import type { NameLookup } from "../bpmn-name-lookup.js"
+
+/** What the analytics plugin hands its pipeline steps (`appConfig` in `plugin.ts`). */
+export interface AnalyticsAppConfig {
+  client: PrometheusClient
+  /** The server's configured engine ids — a step never reads an engine outside them. */
+  engineScope: AnalyticsEngineScope
+  /** The shared profile store — the source of the caller's saved analytics defaults. */
+  profileStore?: ProfileSource
+  /** The process names behind the ids, the same lookup the tools use (absent → ids). */
+  namesFor?: NameLookup
+}
+
+/*
+ * Step keys arrive unchecked: render-view and the builder accept them as a
+ * free-form record and pass them through untouched. So each reader below holds
+ * the line the tools' strict inputs hold — a malformed value is refused naming
+ * its key, never read as "omitted" (which would widen `analytics:engine` to the
+ * whole fleet, or swap in a default period nobody asked for).
+ */
+
+/** The optional `analytics:engine` scoping key both steps read. */
+export const ENGINE_KEY_DECLARATION = {
+  key: "analytics:engine",
+  description:
+    "Engine id, or a list of ids, to scope to (one of the server's configured engines). When omitted, every configured engine is aggregated — the result's `engines` names them.",
+}
+
+/** The step's `analytics:engine` key resolved to configured ids (omitted = all of them). */
+export function stepEngines(
+  keys: Record<string, unknown>,
+  engineScope: AnalyticsEngineScope,
+): string[] {
+  const raw = keys[ENGINE_KEY_DECLARATION.key]
+  const wellFormed =
+    raw === undefined ||
+    typeof raw === "string" ||
+    (Array.isArray(raw) && raw.every((id) => typeof id === "string"))
+  if (!wellFormed) {
+    throw new Error(
+      `${ENGINE_KEY_DECLARATION.key} must be an engine id or a list of engine ids — omit it to cover every configured engine.`,
+    )
+  }
+  return engineScope.resolve(raw)
+}
+
+/**
+ * The step's `analytics:period`: the key when set, else the CALLER's saved
+ * analytics default (resolved from the ambient request — a step gets no
+ * handler ctx), else the module default — the tools' precedence.
+ */
+export async function stepPeriod(
+  keys: Record<string, unknown>,
+  profileStore: ProfileSource | undefined,
+): Promise<Period> {
+  const raw = keys["analytics:period"]
+  if (raw === undefined) return (await settingsFor(profileStore)).defaultPeriod
+  if (PERIODS.includes(raw as Period)) return raw as Period
+  throw new Error(
+    `analytics:period must be one of ${PERIODS.join(", ")} — omit it for the caller's saved default.`,
+  )
+}
+
+/** The step's optional `analytics:processDefinitionKey` (omitted = every process). */
+export function stepProcessKey(keys: Record<string, unknown>): string | undefined {
+  const raw = keys["analytics:processDefinitionKey"]
+  if (raw === undefined || typeof raw === "string") return raw
+  throw new Error(
+    "analytics:processDefinitionKey must be a process definition key (a string) — omit it to cover every process.",
+  )
+}

package/src/steps/dashboard.ts

@@ -0,0 +1,73 @@
+import type { PipelineStepDefinition } from "@miragon/mcp-toolkit-core"
+import { PERIODS, queries } from "@miragon/pulse-analytics-client"
+import { analyticsSettingsSchema, settingsFor } from "../settings.js"
+import { NO_NAMES } from "../bpmn-name-lookup.js"
+import { namedDashboard } from "../named-views.js"
+import {
+  ENGINE_KEY_DECLARATION,
+  stepEngines,
+  stepPeriod,
+  stepProcessKey,
+  type AnalyticsAppConfig,
+} from "./app-config.js"
+import { builderText } from "../builder-texts.js"
+
+/** The period a caller without a saved default gets — the settings schema's default. */
+const MODULE_DEFAULT_PERIOD = analyticsSettingsSchema.shape.defaultPeriod.parse(undefined)
+
+/**
+ * Loads the dashboard figures from Prometheus — window flows plus the live
+ * state, the same `dashboardData` as `analytics_show_dashboard`. Consumed by
+ * `analytics:dashboard`. Reads optional filter keys:
+ * - `analytics:processDefinitionKey`
+ * - `analytics:period` (1d | 3d | 7d | 14d | 30d; omitted = the caller's saved default)
+ * - `analytics:engine` (configured engine id(s); omitted = all of them)
+ */
+export const loadDashboardStep: PipelineStepDefinition<AnalyticsAppConfig> = {
+  id: "analytics:load-dashboard",
+  ...builderText("step.load-dashboard"),
+  description:
+    "Process metrics: what happened within a time window (instances started/completed, incidents created/resolved, durations of the instances that ended) plus the live state right now (instances running, incidents open), per process definition and per (process, activity). Powers the four dashboard widgets (execution-summary-kpi, execution-performance-kpi, process-definition-breakdown, activity-bottleneck-table).",
+  dataType: "analytics:dashboard",
+  requires: [],
+  optionalKeys: [
+    {
+      key: "analytics:processDefinitionKey",
+      description:
+        "Scope the dashboard to a single process definition (e.g. 'miraveloLeasing'). When omitted, all processes are aggregated.",
+    },
+    {
+      key: "analytics:period",
+      description: `Time window. When omitted, the caller's saved analytics default (else '${MODULE_DEFAULT_PERIOD}').`,
+      enum: [...PERIODS],
+    },
+    ENGINE_KEY_DECLARATION,
+  ],
+  produces: ["analytics:dashboardData"],
+  execute: async (context, appConfig) => {
+    // Every key is checked before the first query is sent.
+    const processDefinitionKey = stepProcessKey(context.keys)
+    const engine = stepEngines(context.keys, appConfig.engineScope)
+    const period = await stepPeriod(context.keys, appConfig.profileStore)
+    // The floor for judging the incident rate against the previous period:
+    // the caller's saved minBucketSize, like the tools'.
+    const { minBucketSize } = await settingsFor(appConfig.profileStore)
+
+    const data = await namedDashboard(
+      await queries.dashboardData(appConfig.client, {
+        processDefinitionKey,
+        period,
+        engine,
+        minBucketSize,
+      }),
+      appConfig.namesFor ?? NO_NAMES,
+    )
+
+    return {
+      data,
+      keys: { "analytics:dashboardData": data },
+      _app: "analytics",
+      _step: "load-dashboard",
+    }
+  },
+}