@databricks/appkit 0.61.0 → 0.62.0

package/dist/testing/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","names":[],"sources":["../../src/testing/fixtures.ts"],"sourcesContent":["import type { Span, SpanOptions } from \"@opentelemetry/api\";\nimport type { IAppRouter } from \"shared\";\nimport { afterEach, beforeEach, vi } from \"vitest\";\n\nimport { CacheManager } from \"../cache\";\nimport type { ServiceContextState } from \"../context/service-context\";\nimport { ServiceContext } from \"../context/service-context\";\nimport type { InstrumentConfig, ITelemetry } from \"../telemetry/types\";\n\n// Test fixtures intentionally use loose shapes; `noExplicitAny` is disabled\n// repo-wide (see biome.json), so a local alias keeps the intent readable.\ntype Any = any;\n\n/**\n * Creates a mock telemetry provider for testing. Every span/meter/logger is a\n * `vi.fn()` no-op, so plugins that trace, count, or log run without a live\n * OpenTelemetry pipeline. Passed into {@link createTestPluginContext} as the one\n * injectable production seam.\n */\nexport function createMockTelemetry(): ITelemetry {\n  const mockSpan: Span = {\n    addLink: vi.fn(),\n    addLinks: vi.fn(),\n    end: vi.fn(),\n    setAttribute: vi.fn(),\n    setAttributes: vi.fn(),\n    setStatus: vi.fn(),\n    recordException: vi.fn(),\n    updateName: vi.fn(),\n    addEvent: vi.fn(),\n    isRecording: vi.fn().mockReturnValue(false),\n    spanContext: vi.fn(),\n  };\n\n  return {\n    getTracer: vi.fn().mockReturnValue({\n      startActiveSpan: vi.fn().mockImplementation((...args: Any[]) => {\n        const fn = args[args.length - 1];\n        if (typeof fn === \"function\") {\n          return fn(mockSpan);\n        }\n        return undefined;\n      }),\n    }),\n    getMeter: vi.fn().mockReturnValue({\n      createCounter: vi.fn().mockReturnValue({ add: vi.fn() }),\n      createHistogram: vi.fn().mockReturnValue({ record: vi.fn() }),\n    }),\n    getLogger: vi.fn().mockReturnValue({\n      emit: vi.fn(),\n    }),\n    emit: vi.fn(),\n    startActiveSpan: vi\n      .fn()\n      .mockImplementation(\n        async (\n          _name: string,\n          _options: SpanOptions,\n          fn: (span: Span) => Promise<Any>,\n          _tracerOptions?: InstrumentConfig,\n        ) => {\n          return await fn(mockSpan);\n        },\n      ),\n    registerInstrumentations: vi.fn(),\n  };\n}\n\n/**\n * Creates a mock Express router that captures registered handlers so a test\n * can pull a handler back out by method + path and invoke it directly.\n */\nexport function createMockRouter(): {\n  router: IAppRouter;\n  handlers: Record<string, Any>;\n  getHandler: (method: string, path: string) => Any;\n} {\n  const handlers: Record<string, Any> = {};\n\n  const mockRouter = {\n    get: vi.fn((path: string, handler: Any) => {\n      handlers[`GET:${path}`] = handler;\n    }),\n    post: vi.fn((path: string, handler: Any) => {\n      handlers[`POST:${path}`] = handler;\n    }),\n    put: vi.fn((path: string, handler: Any) => {\n      handlers[`PUT:${path}`] = handler;\n    }),\n    delete: vi.fn((path: string, handler: Any) => {\n      handlers[`DELETE:${path}`] = handler;\n    }),\n    patch: vi.fn((path: string, handler: Any) => {\n      handlers[`PATCH:${path}`] = handler;\n    }),\n  } as unknown as IAppRouter;\n\n  return {\n    router: mockRouter,\n    handlers,\n    getHandler: (method: string, path: string) =>\n      handlers[`${method.toUpperCase()}:${path}`],\n  };\n}\n\n/**\n * On-behalf-of shorthand for {@link createMockRequest}. `true` uses the default\n * test user; an object picks the identity. Sets the forwarded headers the real\n * `Plugin.asUser` reads (`x-forwarded-access-token`, `x-forwarded-user`, and —\n * when given — `x-forwarded-email`), so an OBO test is one flag instead of\n * hand-rolled headers.\n */\nexport type OboOption =\n  | boolean\n  | {\n      /** `x-forwarded-user` — defaults to `\"test-user\"`. */\n      userId?: string;\n      /** `x-forwarded-access-token` — defaults to `\"test-user-token\"`. */\n      token?: string;\n      /** `x-forwarded-email` — omitted unless provided. */\n      email?: string;\n    };\n\n/** Build the forwarded identity headers an `obo` option implies. */\nfunction oboHeaders(obo: Exclude<OboOption, false>): Record<string, string> {\n  const opts = obo === true ? {} : obo;\n  const headers: Record<string, string> = {\n    \"x-forwarded-access-token\": opts.token ?? \"test-user-token\",\n    \"x-forwarded-user\": opts.userId ?? \"test-user\",\n  };\n  if (opts.email) headers[\"x-forwarded-email\"] = opts.email;\n  return headers;\n}\n\n/**\n * Creates a mock Express request. Pass `overrides` to set `params`, `query`,\n * `body`, `headers`, etc.\n *\n * For on-behalf-of tests, pass `obo` instead of hand-adding forwarded headers —\n * `createMockRequest({ obo: true })` sets the identity headers the real\n * `asUser` requires. Any explicit `headers` you also pass win over the ones\n * `obo` generates, so you can override a single field.\n *\n * @example\n * ```ts\n * createMockRequest({ obo: true });                 // default test user + token\n * createMockRequest({ obo: { userId: \"alice\" } });  // pick the user\n * ```\n */\nexport function createMockRequest(overrides: Any = {}) {\n  const { obo, headers: headerOverrides, ...rest } = overrides;\n\n  // `obo` seeds the forwarded identity headers; an explicit `headers` override\n  // still wins (merged last) so a test can tweak or drop a single field.\n  //\n  // Keys are lowercased on the way in, the way Node's parser gives them to\n  // Express. `header()` looks up lowercased, so storing as-given would file a\n  // mixed-case override under a second key and leave the obo one winning.\n  const headers: Record<string, unknown> = Object.fromEntries(\n    Object.entries({\n      ...(obo ? oboHeaders(obo) : {}),\n      ...headerOverrides,\n    }).map(([name, value]) => [name.toLowerCase(), value]),\n  );\n\n  const req = {\n    params: {},\n    query: {},\n    body: {},\n    header: function (name: string) {\n      return this.headers[name.toLowerCase()];\n    },\n    // `...rest` keeps the original override power over every default above;\n    // `headers` is applied last as the one managed field (obo + overrides).\n    ...rest,\n    headers,\n  };\n  return req;\n}\n\n/**\n * Creates a mock Express response object. `write`/`send`/`setHeader` flip\n * `headersSent`, `end` flips `writableEnded` and fires any `close` listener —\n * enough for streaming handlers that branch on those flags.\n *\n * Every chunk passed to `write` (and a final chunk to `end`) is captured, so a\n * streaming route's real SSE output can be replayed: pass the response straight\n * to {@link expectStream}, or call `sseResponse()` for a real `Response`.\n *\n * @example Assert what a streaming route emitted\n * ```ts\n * const res = createMockResponse();\n * await plugin._handleStream(req, res);\n * await expectStream(res).toEmit(\"status\", \"result\");\n * ```\n */\nexport function createMockResponse() {\n  const eventListeners: Record<string, Array<(...args: Any[]) => void>> = {};\n  const chunks: string[] = [];\n\n  const res = {\n    // Flips to true once headers/body have gone out — mirrors Express so\n    // streaming handlers can branch between a JSON error (pre-headers) and\n    // aborting the socket (mid-stream).\n    headersSent: false,\n    status: vi.fn().mockReturnThis(),\n    json: vi.fn().mockReturnThis(),\n    send: vi.fn(function (this: Any) {\n      this.headersSent = true;\n      return this;\n    }),\n    sendStatus: vi.fn().mockReturnThis(),\n    end: vi.fn(function (this: Any, chunk?: unknown) {\n      // Express allows `end(chunk)` and `end(callback)`; capture only a data\n      // chunk, never the completion callback.\n      if (chunk != null && typeof chunk !== \"function\") {\n        chunks.push(String(chunk));\n      }\n      this.writableEnded = true;\n      if (eventListeners.close) {\n        for (const handler of eventListeners.close) {\n          handler();\n        }\n      }\n      return this;\n    }),\n    write: vi.fn(function (this: Any, chunk?: unknown) {\n      this.headersSent = true;\n      if (chunk != null) chunks.push(String(chunk));\n      // Return `this` (truthy) rather than a boolean: handlers that gate on\n      // backpressure (`if (res.write(buf)) …`) then take the no-wait path.\n      return this;\n    }),\n    setHeader: vi.fn(function (this: Any) {\n      this.headersSent = true;\n      return this;\n    }),\n    flushHeaders: vi.fn().mockReturnThis(),\n    destroy: vi.fn().mockReturnThis(),\n    on: vi.fn(function (\n      this: Any,\n      event: string,\n      handler: (...args: Any[]) => void,\n    ) {\n      if (!eventListeners[event]) {\n        eventListeners[event] = [];\n      }\n      eventListeners[event].push(handler);\n      return this;\n    }),\n    off: vi.fn(function (\n      this: Any,\n      event: string,\n      handler: (...args: Any[]) => void,\n    ) {\n      if (eventListeners[event]) {\n        eventListeners[event] = eventListeners[event].filter(\n          (h) => h !== handler,\n        );\n      }\n      return this;\n    }),\n    writableEnded: false,\n    /**\n     * The SSE body captured so far, as a real `Response` — the bridge from a\n     * `res.write`-based handler into {@link expectStream}. `expectStream`\n     * detects this method and calls it for you, so `expectStream(res)` and\n     * `expectStream(res.sseResponse())` are equivalent.\n     */\n    sseResponse(): Response {\n      return new Response(chunks.join(\"\"));\n    },\n  };\n  return res;\n}\n\n/**\n * Sets up common environment variables for Databricks testing so code that\n * reads `DATABRICKS_HOST` / `DATABRICKS_WAREHOUSE_ID` finds test values.\n */\nexport function setupDatabricksEnv(overrides: Record<string, string> = {}) {\n  process.env.DATABRICKS_HOST = \"https://test.databricks.com\";\n  process.env.DATABRICKS_WAREHOUSE_ID = \"test-warehouse-id\";\n  Object.assign(process.env, overrides);\n}\n\n/**\n * Clears AppKit's process-wide cache singleton so cached values don't leak\n * between tests in the same file.\n *\n * The cache `attach()` seeds is shared by every test in a file (Vitest isolates\n * files, not tests within a file). Call this in `beforeEach` when one test's\n * cached value must not be seen by the next, or mid-test to force a cache miss\n * before asserting a subsequent hit.\n *\n * No-ops when the cache has not been initialized yet, so it is safe to call\n * before any `attach()`.\n *\n * @example\n * ```ts\n * beforeEach(async () => {\n *   await resetTestCache();\n * });\n * ```\n */\nexport async function resetTestCache(): Promise<void> {\n  let cache: ReturnType<typeof CacheManager.getInstanceSync>;\n  try {\n    cache = CacheManager.getInstanceSync();\n  } catch {\n    // Not initialized yet — nothing to clear.\n    return;\n  }\n  await cache.clear();\n}\n\n/**\n * Context options for running tests with mocked service/user context\n */\nexport interface TestContextOptions {\n  /** Mock WorkspaceClient for service principal operations */\n  serviceDatabricksClient?: Any;\n  /** Mock WorkspaceClient for user operations */\n  userDatabricksClient?: Any;\n  /** User ID for user context */\n  userId?: string;\n  /** Service user ID */\n  serviceUserId?: string;\n  /** Warehouse ID */\n  warehouseId?: string;\n  /** Workspace ID */\n  workspaceId?: string;\n}\n\n/**\n * Creates a default mock WorkspaceClient for testing (SQL succeeds, warehouse\n * RUNNING).\n */\nexport function createMockWorkspaceClient() {\n  return {\n    statementExecution: {\n      executeStatement: vi.fn().mockResolvedValue({\n        status: { state: \"SUCCEEDED\" },\n        result: { data: [] },\n      }),\n    },\n    // Analytics route now calls `warehouses.get` before issuing SQL to\n    // ensure the warehouse is RUNNING. Default to RUNNING so existing\n    // tests that only care about SQL behaviour aren't affected.\n    warehouses: {\n      get: vi.fn().mockResolvedValue({ state: \"RUNNING\" }),\n      start: vi.fn().mockResolvedValue(undefined),\n    },\n  };\n}\n\n/**\n * Builds a {@link ServiceContextState} value for testing without touching the\n * singleton. Internal building block for {@link mockServiceContext}, which\n * installs the state as spies — that installer is the public entry point.\n */\nfunction buildServiceContextState(\n  options: TestContextOptions = {},\n): ServiceContextState {\n  return {\n    client: (options.serviceDatabricksClient ||\n      createMockWorkspaceClient()) as Any,\n    serviceUserId: options.serviceUserId || \"test-service-user\",\n    warehouseId: Promise.resolve(options.warehouseId || \"test-warehouse-id\"),\n    workspaceId: Promise.resolve(options.workspaceId || \"test-workspace-id\"),\n  };\n}\n\n/**\n * Mocks the `ServiceContext` singleton for testing — spies `get`,\n * `initialize`, `isInitialized`, and `createUserContext` so code that resolves\n * the service principal or an on-behalf-of user context gets test doubles.\n * Call in `beforeEach`; call the returned `restore()` in `afterEach`.\n *\n * @returns The mock context plus the spies and a `restore()` helper.\n */\nexport function mockServiceContext(options: TestContextOptions = {}) {\n  const serviceContext = buildServiceContextState(options);\n\n  const getSpy = vi\n    .spyOn(ServiceContext, \"get\")\n    .mockReturnValue(serviceContext);\n\n  const initSpy = vi\n    .spyOn(ServiceContext, \"initialize\")\n    .mockResolvedValue(serviceContext);\n\n  const isInitializedSpy = vi\n    .spyOn(ServiceContext, \"isInitialized\")\n    .mockReturnValue(true);\n\n  const createUserContextSpy = vi\n    .spyOn(ServiceContext, \"createUserContext\")\n    .mockImplementation((_token: string, userId: string, userName?: string) => {\n      return {\n        client: (options.userDatabricksClient ||\n          createMockWorkspaceClient()) as Any,\n        userId,\n        userName,\n        warehouseId: serviceContext.warehouseId,\n        workspaceId: serviceContext.workspaceId,\n        isUserContext: true,\n      };\n    });\n\n  return {\n    serviceContext,\n    getSpy,\n    initSpy,\n    isInitializedSpy,\n    createUserContextSpy,\n    restore: () => {\n      getSpy.mockRestore();\n      initSpy.mockRestore();\n      isInitializedSpy.mockRestore();\n      createUserContextSpy.mockRestore();\n    },\n  };\n}\n\n/** The handle {@link mockServiceContext} returns (spies + `restore`). */\nexport type ServiceContextMock = ReturnType<typeof mockServiceContext>;\n\n/**\n * Registers a fresh {@link mockServiceContext} before each test and restores it\n * after — the whole `beforeEach`/`afterEach` dance in one line.\n *\n * Call it at the top of a `describe` block (or module top-level), NOT inside a\n * test: Vitest's `beforeEach`/`afterEach` only register during collection, so a\n * call from within a test body registers nothing for that test.\n *\n * Returns a **live** accessor, not the handle: each `beforeEach` builds fresh\n * spies, so reading `.current` inside a test always sees that test's mock. A\n * handle captured once would go stale after the first hook runs.\n *\n * @example\n * ```ts\n * describe(\"my plugin\", () => {\n *   const ctx = useServiceContextMock({ warehouseId: \"wh-1\" });\n *\n *   test(\"resolves the warehouse\", async () => {\n *     await myHandler(req, res);\n *     expect(ctx.current.getSpy).toHaveBeenCalled();\n *   });\n * });\n * ```\n *\n * @returns `{ current }` — the active {@link ServiceContextMock} for the test.\n */\nexport function useServiceContextMock(options: TestContextOptions = {}): {\n  readonly current: ServiceContextMock;\n} {\n  let handle: ServiceContextMock | undefined;\n\n  beforeEach(() => {\n    handle = mockServiceContext(options);\n  });\n\n  afterEach(() => {\n    handle?.restore();\n    handle = undefined;\n  });\n\n  return {\n    get current(): ServiceContextMock {\n      if (!handle) {\n        throw new Error(\n          \"useServiceContextMock: no active mock. Call useServiceContextMock() \" +\n            \"at the top of a describe block (not inside a test), and read \" +\n            \"`.current` from within a test.\",\n        );\n      }\n      return handle;\n    },\n  };\n}\n\n/**\n * Runs a test function within a mocked service context: installs the mock,\n * runs `fn`, and restores the singleton afterward.\n */\nexport async function runWithRequestContext<T>(\n  fn: () => T | Promise<T>,\n  context?: TestContextOptions,\n): Promise<T> {\n  const mocks = mockServiceContext(context);\n\n  try {\n    return await fn();\n  } finally {\n    mocks.restore();\n  }\n}\n\n/**\n * Builds a SUCCEEDED SQL statement response with a synthetic statement id,\n * `data_array` rows, and a manifest schema derived from `columns`.\n */\nexport function createSuccessfulSQLResponse(\n  data: Any[][],\n  columns: Array<{ name: string; type_name?: string }>,\n) {\n  return {\n    status: { state: \"SUCCEEDED\" },\n    statement_id: `stmt-${Date.now()}`,\n    result: {\n      data_array: data,\n    },\n    manifest: {\n      schema: {\n        columns: columns.map((col) => ({\n          name: col.name,\n          type_name: col.type_name ?? \"STRING\",\n        })),\n      },\n    },\n  };\n}\n\n/** Builds a FAILED SQL statement response carrying `errorMessage`. */\nexport function createFailedSQLResponse(errorMessage: string) {\n  return {\n    status: {\n      state: \"FAILED\",\n      error: {\n        message: errorMessage,\n      },\n    },\n    statement_id: `stmt-${Date.now()}`,\n  };\n}\n\n/**\n * A WorkspaceClient whose `executeStatement`/`getStatement` are bare `vi.fn()`s\n * (no default resolution) so a test can script exactly what SQL returns.\n * `warehouses.get` defaults to RUNNING.\n */\nexport function createConfigurableMockWorkspaceClient() {\n  const executeStatement = vi.fn();\n  const getStatement = vi.fn();\n  // Analytics route now calls `warehouses.get` before issuing SQL; default to\n  // RUNNING so callers that don't care about warehouse readiness don't have\n  // to wire it up.\n  const warehousesGet = vi.fn().mockResolvedValue({ state: \"RUNNING\" });\n  const warehousesStart = vi.fn().mockResolvedValue(undefined);\n\n  const client = {\n    statementExecution: {\n      executeStatement,\n      getStatement,\n    },\n    warehouses: {\n      get: warehousesGet,\n      start: warehousesStart,\n    },\n  };\n\n  return {\n    client,\n    mocks: {\n      executeStatement,\n      getStatement,\n      warehousesGet,\n      warehousesStart,\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+import { PluginContext } from "../core/plugin-context.js";
+import { CapturedSSEResponse, ExpectStreamOptions, StreamAssertion, StreamEvent, StreamSource, expectStream, parseSSEResponse } from "./expect-stream.js";
+import { OboOption, ServiceContextMock, TestContextOptions, createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock } from "./fixtures.js";
+import { FakeProvider, FakeProviders, FakeToolResponse, RecordedRoute, RecordedToolCall, TestPluginContext, createTestPluginContext } from "./test-plugin-context.js";
+export { type CapturedSSEResponse, type ExpectStreamOptions, type FakeProvider, type FakeProviders, type FakeToolResponse, type OboOption, type PluginContext, type RecordedRoute, type RecordedToolCall, type ServiceContextMock, type StreamAssertion, type StreamEvent, type StreamSource, type TestContextOptions, type TestPluginContext, createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, createTestPluginContext, expectStream, mockServiceContext, parseSSEResponse, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+import { expectStream, parseSSEResponse } from "./expect-stream.js";
+import { createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, mockServiceContext, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock } from "./fixtures.js";
+import { createTestPluginContext } from "./test-plugin-context.js";
+
+export { createConfigurableMockWorkspaceClient, createFailedSQLResponse, createMockRequest, createMockResponse, createMockRouter, createMockTelemetry, createMockWorkspaceClient, createSuccessfulSQLResponse, createTestPluginContext, expectStream, mockServiceContext, parseSSEResponse, resetTestCache, runWithRequestContext, setupDatabricksEnv, useServiceContextMock };

package/dist/testing/test-plugin-context.d.ts

@@ -0,0 +1,158 @@
+import { AgentToolDefinition } from "../shared/src/agent.js";
+import "../shared/src/index.js";
+import { ITelemetry } from "../telemetry/types.js";
+import "../telemetry/index.js";
+import { PluginContext } from "../core/plugin-context.js";
+import { Plugin } from "../plugin/plugin.js";
+import "../plugin/index.js";
+import express from "express";
+
+//#region src/testing/test-plugin-context.d.ts
+/**
+ * A concrete (non-function) fake tool response — returned as-is. Covers the
+ * JSON-serializable shapes a tool call yields (rows, objects, primitives,
+ * nullish). A bare `unknown` is intentionally not used here: unioned with the
+ * function form below it would collapse to `unknown` and strip contextual
+ * types from the callback's parameters.
+ */
+type FakeToolValue = Record<string, unknown> | unknown[] | string | number | boolean | null;
+/**
+ * A canned tool response. Either a static {@link FakeToolValue} returned
+ * as-is, or a function of the call arguments (and the abort signal
+ * `PluginContext.executeTool` composes) so a fake can assert on inputs or
+ * simulate slow/aborting work. Returning a promise is supported (the return
+ * type is intentionally `unknown`, which also covers `Promise<...>`).
+ */
+type FakeToolResponse = FakeToolValue | ((args: unknown, signal?: AbortSignal) => unknown);
+/**
+ * Fake connector responses, keyed by plugin name and then tool name:
+ *
+ * ```ts
+ * createTestPluginContext({ analytics: { query: fixtureRows } });
+ * ```
+ *
+ * Each top-level key registers a fake {@link ToolProvider} under that plugin
+ * name; each inner key becomes a tool that returns the mapped response.
+ */
+type FakeProviders = Record<string, Record<string, FakeToolResponse>>;
+/** A single dispatch observed by a fake provider. */
+interface RecordedToolCall {
+  /** Registered plugin name (the key in {@link FakeProviders}). */
+  plugin: string;
+  /** Tool name passed to `executeAgentTool`. */
+  tool: string;
+  /** Arguments the tool received. */
+  args: unknown;
+  /** The abort signal `executeTool` composed (timeout ∘ caller). */
+  signal?: AbortSignal;
+  /**
+   * Whether the dispatch was resolved through the on-behalf-of (`asUser`)
+   * path. `PluginContext.executeTool` always calls `provider.asUser(req)`, so
+   * for a tool reached through `executeTool` this is `true` — and, because the
+   * fake `asUser` enforces the same token precondition as the real
+   * {@link Plugin.asUser}, a request with no `x-forwarded-access-token` makes
+   * that call **throw** rather than record `asUser: true`. The meaningful
+   * assertions are therefore: a well-formed request records `asUser: true`
+   * with {@link userId} set, and a token-less request rejects.
+   *
+   * The fake replicates the token precondition only, not the real dev-mode
+   * OTel `isDevOboFallback()` marker — assert OBO here, not via that flag.
+   */
+  asUser: boolean;
+  /**
+   * The user the on-behalf-of scope resolved to (from `x-forwarded-user`), or
+   * `undefined` for a service-principal call (`asUser: false`). Lets a test
+   * assert the tool ran as the expected end user, not just that OBO was used.
+   */
+  userId?: string;
+}
+/** A single route registered through the context's `addRoute`/`addMiddleware`. */
+interface RecordedRoute {
+  method: string;
+  path: string;
+  /**
+   * The raw handlers as passed to `addRoute` — before `PluginContext` wraps
+   * them with `forwardAsyncErrors`. Recorded here so aliasing assertions
+   * ("both routes mount the same handler") can compare the original
+   * references, which the wrapped express-level handlers no longer share.
+   */
+  handlers: express.RequestHandler[];
+}
+/** A fake tool provider registered on a mock context. */
+interface FakeProvider {
+  /** Every `asUser(req)` the context resolved for this provider. */
+  asUserRequests: express.Request[];
+  /** Definitions returned from `getAgentTools()`. */
+  tools: AgentToolDefinition[];
+}
+/**
+ * The result of {@link createTestPluginContext}: the real `PluginContext` plus the
+ * seams a test needs to drive and inspect it.
+ */
+interface TestPluginContext {
+  /** The real {@link PluginContext}, constructed with mock telemetry. */
+  ctx: PluginContext;
+  /**
+   * The mock telemetry provider injected into the {@link PluginContext}.
+   * Captures the spans the *context* opens (notably `executeTool`) — not the
+   * plugin's own spans: `attachContext` rebuilds the plugin's `this.telemetry`
+   * from the real `TelemetryManager`, so plugin-internal spans do not land here.
+   */
+  telemetry: ITelemetry;
+  /**
+   * Tool dispatches observed across all fake providers, in call order. Live —
+   * read it after the action under test runs.
+   */
+  toolCalls: RecordedToolCall[];
+  /**
+   * Routes registered through the context, in registration order. Live —
+   * populated when the plugin calls `addRoute`/`addMiddleware`.
+   */
+  routes: RecordedRoute[];
+  /** Fake providers by plugin name, for direct assertions. */
+  providers: Map<string, FakeProvider>;
+  /**
+   * Register (or replace) a fake tool provider after construction.
+   * Same shape as one {@link FakeProviders} entry.
+   */
+  registerProvider(name: string, tools: Record<string, FakeToolResponse>): void;
+  /**
+   * Attach this context to a plugin the production way: seed an in-memory
+   * cache (if AppKit hasn't already), then call `plugin.attachContext`, which
+   * also rebuilds the plugin's telemetry and flips `isReady` to `true`. Await
+   * it before exercising handlers that read `this.context`, `this.cache`, or
+   * gate on `isReady`. Returns the same plugin for chaining.
+   */
+  attach<P extends Plugin>(plugin: P): Promise<P>;
+}
+/**
+ * Build a real {@link PluginContext} with faked edges for testing — no live
+ * workspace, no OpenTelemetry pipeline, no network.
+ *
+ * The context is the *real* class, so route buffering, the tool registry,
+ * timeout composition, and the on-behalf-of (`asUser`) path all run for real.
+ * Only three edges are faked, matching the seams the class actually has:
+ *
+ * - **Telemetry** is a mock provider injected into the context (the one
+ *   injectable production seam); it records the context's own spans, not the
+ *   plugin's.
+ * - **Tool providers** are fakes registered through the existing public
+ *   `registerToolProvider`; their `asUser`/`executeAgentTool` are recorded.
+ * - **Routes** are captured by wrapping the public `addRoute`/`addMiddleware`.
+ *
+ * Nothing about `PluginContext` is reimplemented.
+ *
+ * @param fakes - Canned tool responses keyed by plugin then tool name.
+ *
+ * @example
+ * ```ts
+ * const mock = createTestPluginContext({ analytics: { query: fixtureRows } });
+ * await mock.attach(agentsPlugin);
+ * // ...exercise a handler that dispatches analytics.query...
+ * expect(mock.toolCalls[0]).toMatchObject({ plugin: "analytics", asUser: true });
+ * ```
+ */
+declare function createTestPluginContext(fakes?: FakeProviders): TestPluginContext;
+//#endregion
+export { FakeProvider, FakeProviders, FakeToolResponse, RecordedRoute, RecordedToolCall, TestPluginContext, createTestPluginContext };
+//# sourceMappingURL=test-plugin-context.d.ts.map

package/dist/testing/test-plugin-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-plugin-context.d.ts","names":[],"sources":["../../src/testing/test-plugin-context.ts"],"mappings":";;;;;;;;;;;;;;;AAa+C;;KAU1C,aAAA,GACD,MAAA;;;AAcJ;;;;;KAAY,gBAAA,GACR,aAAA,KACE,IAAA,WAAe,MAAA,GAAS,WAAA;;;;;AAY9B;;;;;;KAAY,aAAA,GAAgB,MAAA,SAAe,MAAA,SAAe,gBAAA;;UAGzC,gBAAA;EAH0B;EAKzC,MAAA;EALwE;EAOxE,IAAA;EAJe;EAMf,IAAA;;EAEA,MAAA,GAAS,WAAA;EANT;;;;;;;;;AA8BF;;;;EAVE,MAAA;EAYA;;;;;EANA,MAAA;AAAA;;UAIe,aAAA;EACf,MAAA;EACA,IAAA;EAagB;;;;;;EANhB,QAAA,EAAU,OAAA,CAAQ,cAAA;AAAA;;UAIH,YAAA;EAoBJ;EAlBX,cAAA,EAAgB,OAAA,CAAQ,OAAA;EA4BhB;EA1BR,KAAA,EAAO,mBAAA;AAAA;;;;;UAOQ,iBAAA;EAkCsB;EAhCrC,GAAA,EAAK,aAAA;EAgCuC;;;;;;EAzB5C,SAAA,EAAW,UAAA;EAUX;;;;EALA,SAAA,EAAW,gBAAA;EAYX;;;;EAPA,MAAA,EAAQ,aAAA;EAeR;EAbA,SAAA,EAAW,GAAA,SAAY,YAAA;EAaN;;;;EARjB,gBAAA,CAAiB,IAAA,UAAc,KAAA,EAAO,MAAA,SAAe,gBAAA;EAQP;;AA8BhD;;;;;EA9BE,MAAA,WAAiB,MAAA,EAAQ,MAAA,EAAQ,CAAA,GAAI,OAAA,CAAQ,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8B/B,uBAAA,CACd,KAAA,GAAO,aAAA,GACN,iBAAA"}

package/dist/testing/test-plugin-context.js

@@ -0,0 +1,139 @@
+import { AuthenticationError } from "../errors/authentication.js";
+import "../errors/index.js";
+import { InMemoryStorage } from "../cache/storage/memory.js";
+import "../cache/storage/index.js";
+import { CacheManager } from "../cache/index.js";
+import { PluginContext, isToolProvider } from "../core/plugin-context.js";
+import { createMockTelemetry } from "./fixtures.js";
+
+//#region src/testing/test-plugin-context.ts
+/**
+* Build a real {@link PluginContext} with faked edges for testing — no live
+* workspace, no OpenTelemetry pipeline, no network.
+*
+* The context is the *real* class, so route buffering, the tool registry,
+* timeout composition, and the on-behalf-of (`asUser`) path all run for real.
+* Only three edges are faked, matching the seams the class actually has:
+*
+* - **Telemetry** is a mock provider injected into the context (the one
+*   injectable production seam); it records the context's own spans, not the
+*   plugin's.
+* - **Tool providers** are fakes registered through the existing public
+*   `registerToolProvider`; their `asUser`/`executeAgentTool` are recorded.
+* - **Routes** are captured by wrapping the public `addRoute`/`addMiddleware`.
+*
+* Nothing about `PluginContext` is reimplemented.
+*
+* @param fakes - Canned tool responses keyed by plugin then tool name.
+*
+* @example
+* ```ts
+* const mock = createTestPluginContext({ analytics: { query: fixtureRows } });
+* await mock.attach(agentsPlugin);
+* // ...exercise a handler that dispatches analytics.query...
+* expect(mock.toolCalls[0]).toMatchObject({ plugin: "analytics", asUser: true });
+* ```
+*/
+function createTestPluginContext(fakes = {}) {
+	const telemetry = createMockTelemetry();
+	const ctx = new PluginContext({ telemetry });
+	const toolCalls = [];
+	const routes = [];
+	const providers = /* @__PURE__ */ new Map();
+	const realAddRoute = ctx.addRoute.bind(ctx);
+	ctx.addRoute = (method, path, ...handlers) => {
+		routes.push({
+			method,
+			path,
+			handlers
+		});
+		realAddRoute(method, path, ...handlers);
+	};
+	const realAddMiddleware = ctx.addMiddleware.bind(ctx);
+	ctx.addMiddleware = (path, ...handlers) => {
+		routes.push({
+			method: "use",
+			path,
+			handlers
+		});
+		realAddMiddleware(path, ...handlers);
+	};
+	function registerProvider(name, tools) {
+		const record = {
+			asUserRequests: [],
+			tools: Object.keys(tools).map((toolName) => ({
+				name: toolName,
+				description: `Fake tool ${name}.${toolName}`,
+				parameters: { type: "object" }
+			}))
+		};
+		providers.set(name, record);
+		const resolve = async (toolName, args, signal, asUser, userId) => {
+			toolCalls.push({
+				plugin: name,
+				tool: toolName,
+				args,
+				signal,
+				asUser,
+				userId
+			});
+			if (!Object.hasOwn(tools, toolName)) throw new Error(`createTestPluginContext: plugin "${name}" has no fake tool "${toolName}". Available: ${Object.keys(tools).join(", ") || "(none)"}`);
+			const response = tools[toolName];
+			return typeof response === "function" ? await response(args, signal) : response;
+		};
+		const base = {
+			getAgentTools: () => record.tools,
+			executeAgentTool: (toolName, args, signal) => resolve(toolName, args, signal, false, void 0)
+		};
+		const asUser = (req) => {
+			record.asUserRequests.push(req);
+			const token = req.header?.("x-forwarded-access-token")?.trim();
+			const userId = req.header?.("x-forwarded-user")?.trim();
+			const isDev = process.env.NODE_ENV === "development";
+			if (!token && !isDev) throw AuthenticationError.missingToken("user token");
+			if (token && !userId && !isDev) throw AuthenticationError.missingUserId();
+			return {
+				...base,
+				executeAgentTool: (toolName, args, signal) => resolve(toolName, args, signal, true, userId)
+			};
+		};
+		const provider = {
+			name,
+			setup: async () => {},
+			injectRoutes: () => {},
+			getEndpoints: () => ({}),
+			...base,
+			asUser
+		};
+		ctx.registerToolProvider(name, provider);
+	}
+	for (const [name, tools] of Object.entries(fakes)) registerProvider(name, tools);
+	async function attach(plugin) {
+		if (!cacheReady()) await CacheManager.getInstance({ storage: new InMemoryStorage({}) });
+		plugin.attachContext({ context: ctx });
+		ctx.registerPlugin(plugin.name, plugin);
+		if (isToolProvider(plugin) && !providers.has(plugin.name)) ctx.registerToolProvider(plugin.name, plugin);
+		return plugin;
+	}
+	return {
+		ctx,
+		telemetry,
+		toolCalls,
+		routes,
+		providers,
+		registerProvider,
+		attach
+	};
+}
+function cacheReady() {
+	try {
+		CacheManager.getInstanceSync();
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { createTestPluginContext };
+//# sourceMappingURL=test-plugin-context.js.map

package/dist/testing/test-plugin-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-plugin-context.js","names":[],"sources":["../../src/testing/test-plugin-context.ts"],"sourcesContent":["import type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  BasePlugin,\n  IAppRequest,\n  ToolProvider,\n} from \"shared\";\n\nimport { CacheManager } from \"../cache\";\nimport { InMemoryStorage } from \"../cache/storage\";\nimport { isToolProvider, PluginContext } from \"../core/plugin-context\";\nimport { AuthenticationError } from \"../errors\";\nimport type { Plugin } from \"../plugin\";\nimport type { ITelemetry } from \"../telemetry\";\nimport { createMockTelemetry } from \"./fixtures\";\n\n/**\n * A concrete (non-function) fake tool response — returned as-is. Covers the\n * JSON-serializable shapes a tool call yields (rows, objects, primitives,\n * nullish). A bare `unknown` is intentionally not used here: unioned with the\n * function form below it would collapse to `unknown` and strip contextual\n * types from the callback's parameters.\n */\ntype FakeToolValue =\n  | Record<string, unknown>\n  | unknown[]\n  | string\n  | number\n  | boolean\n  | null;\n\n/**\n * A canned tool response. Either a static {@link FakeToolValue} returned\n * as-is, or a function of the call arguments (and the abort signal\n * `PluginContext.executeTool` composes) so a fake can assert on inputs or\n * simulate slow/aborting work. Returning a promise is supported (the return\n * type is intentionally `unknown`, which also covers `Promise<...>`).\n */\nexport type FakeToolResponse =\n  | FakeToolValue\n  | ((args: unknown, signal?: AbortSignal) => unknown);\n\n/**\n * Fake connector responses, keyed by plugin name and then tool name:\n *\n * ```ts\n * createTestPluginContext({ analytics: { query: fixtureRows } });\n * ```\n *\n * Each top-level key registers a fake {@link ToolProvider} under that plugin\n * name; each inner key becomes a tool that returns the mapped response.\n */\nexport type FakeProviders = Record<string, Record<string, FakeToolResponse>>;\n\n/** A single dispatch observed by a fake provider. */\nexport interface RecordedToolCall {\n  /** Registered plugin name (the key in {@link FakeProviders}). */\n  plugin: string;\n  /** Tool name passed to `executeAgentTool`. */\n  tool: string;\n  /** Arguments the tool received. */\n  args: unknown;\n  /** The abort signal `executeTool` composed (timeout ∘ caller). */\n  signal?: AbortSignal;\n  /**\n   * Whether the dispatch was resolved through the on-behalf-of (`asUser`)\n   * path. `PluginContext.executeTool` always calls `provider.asUser(req)`, so\n   * for a tool reached through `executeTool` this is `true` — and, because the\n   * fake `asUser` enforces the same token precondition as the real\n   * {@link Plugin.asUser}, a request with no `x-forwarded-access-token` makes\n   * that call **throw** rather than record `asUser: true`. The meaningful\n   * assertions are therefore: a well-formed request records `asUser: true`\n   * with {@link userId} set, and a token-less request rejects.\n   *\n   * The fake replicates the token precondition only, not the real dev-mode\n   * OTel `isDevOboFallback()` marker — assert OBO here, not via that flag.\n   */\n  asUser: boolean;\n  /**\n   * The user the on-behalf-of scope resolved to (from `x-forwarded-user`), or\n   * `undefined` for a service-principal call (`asUser: false`). Lets a test\n   * assert the tool ran as the expected end user, not just that OBO was used.\n   */\n  userId?: string;\n}\n\n/** A single route registered through the context's `addRoute`/`addMiddleware`. */\nexport interface RecordedRoute {\n  method: string;\n  path: string;\n  /**\n   * The raw handlers as passed to `addRoute` — before `PluginContext` wraps\n   * them with `forwardAsyncErrors`. Recorded here so aliasing assertions\n   * (\"both routes mount the same handler\") can compare the original\n   * references, which the wrapped express-level handlers no longer share.\n   */\n  handlers: express.RequestHandler[];\n}\n\n/** A fake tool provider registered on a mock context. */\nexport interface FakeProvider {\n  /** Every `asUser(req)` the context resolved for this provider. */\n  asUserRequests: express.Request[];\n  /** Definitions returned from `getAgentTools()`. */\n  tools: AgentToolDefinition[];\n}\n\n/**\n * The result of {@link createTestPluginContext}: the real `PluginContext` plus the\n * seams a test needs to drive and inspect it.\n */\nexport interface TestPluginContext {\n  /** The real {@link PluginContext}, constructed with mock telemetry. */\n  ctx: PluginContext;\n  /**\n   * The mock telemetry provider injected into the {@link PluginContext}.\n   * Captures the spans the *context* opens (notably `executeTool`) — not the\n   * plugin's own spans: `attachContext` rebuilds the plugin's `this.telemetry`\n   * from the real `TelemetryManager`, so plugin-internal spans do not land here.\n   */\n  telemetry: ITelemetry;\n  /**\n   * Tool dispatches observed across all fake providers, in call order. Live —\n   * read it after the action under test runs.\n   */\n  toolCalls: RecordedToolCall[];\n  /**\n   * Routes registered through the context, in registration order. Live —\n   * populated when the plugin calls `addRoute`/`addMiddleware`.\n   */\n  routes: RecordedRoute[];\n  /** Fake providers by plugin name, for direct assertions. */\n  providers: Map<string, FakeProvider>;\n  /**\n   * Register (or replace) a fake tool provider after construction.\n   * Same shape as one {@link FakeProviders} entry.\n   */\n  registerProvider(name: string, tools: Record<string, FakeToolResponse>): void;\n  /**\n   * Attach this context to a plugin the production way: seed an in-memory\n   * cache (if AppKit hasn't already), then call `plugin.attachContext`, which\n   * also rebuilds the plugin's telemetry and flips `isReady` to `true`. Await\n   * it before exercising handlers that read `this.context`, `this.cache`, or\n   * gate on `isReady`. Returns the same plugin for chaining.\n   */\n  attach<P extends Plugin>(plugin: P): Promise<P>;\n}\n\n/**\n * Build a real {@link PluginContext} with faked edges for testing — no live\n * workspace, no OpenTelemetry pipeline, no network.\n *\n * The context is the *real* class, so route buffering, the tool registry,\n * timeout composition, and the on-behalf-of (`asUser`) path all run for real.\n * Only three edges are faked, matching the seams the class actually has:\n *\n * - **Telemetry** is a mock provider injected into the context (the one\n *   injectable production seam); it records the context's own spans, not the\n *   plugin's.\n * - **Tool providers** are fakes registered through the existing public\n *   `registerToolProvider`; their `asUser`/`executeAgentTool` are recorded.\n * - **Routes** are captured by wrapping the public `addRoute`/`addMiddleware`.\n *\n * Nothing about `PluginContext` is reimplemented.\n *\n * @param fakes - Canned tool responses keyed by plugin then tool name.\n *\n * @example\n * ```ts\n * const mock = createTestPluginContext({ analytics: { query: fixtureRows } });\n * await mock.attach(agentsPlugin);\n * // ...exercise a handler that dispatches analytics.query...\n * expect(mock.toolCalls[0]).toMatchObject({ plugin: \"analytics\", asUser: true });\n * ```\n */\nexport function createTestPluginContext(\n  fakes: FakeProviders = {},\n): TestPluginContext {\n  const telemetry = createMockTelemetry();\n  const ctx = new PluginContext({ telemetry });\n\n  const toolCalls: RecordedToolCall[] = [];\n  const routes: RecordedRoute[] = [];\n  const providers = new Map<string, FakeProvider>();\n\n  // Wrap the public route API so raw (pre-wrap) handlers are inspectable while\n  // the real buffering/flush path stays intact.\n  const realAddRoute = ctx.addRoute.bind(ctx);\n  ctx.addRoute = (\n    method: string,\n    path: string,\n    ...handlers: express.RequestHandler[]\n  ): void => {\n    routes.push({ method, path, handlers });\n    realAddRoute(method, path, ...handlers);\n  };\n  const realAddMiddleware = ctx.addMiddleware.bind(ctx);\n  ctx.addMiddleware = (\n    path: string,\n    ...handlers: express.RequestHandler[]\n  ): void => {\n    routes.push({ method: \"use\", path, handlers });\n    realAddMiddleware(path, ...handlers);\n  };\n\n  function registerProvider(\n    name: string,\n    tools: Record<string, FakeToolResponse>,\n  ): void {\n    const record: FakeProvider = {\n      asUserRequests: [],\n      tools: Object.keys(tools).map((toolName) => ({\n        name: toolName,\n        description: `Fake tool ${name}.${toolName}`,\n        parameters: { type: \"object\" },\n      })),\n    };\n    providers.set(name, record);\n\n    const resolve = async (\n      toolName: string,\n      args: unknown,\n      signal: AbortSignal | undefined,\n      asUser: boolean,\n      userId: string | undefined,\n    ): Promise<unknown> => {\n      toolCalls.push({\n        plugin: name,\n        tool: toolName,\n        args,\n        signal,\n        asUser,\n        userId,\n      });\n      // `Object.hasOwn`, not `tools[toolName] === undefined`: a tool named\n      // \"constructor\"/\"toString\"/etc. would otherwise resolve to an inherited\n      // Object.prototype method and be invoked instead of reported missing.\n      if (!Object.hasOwn(tools, toolName)) {\n        throw new Error(\n          `createTestPluginContext: plugin \"${name}\" has no fake tool \"${toolName}\". ` +\n            `Available: ${Object.keys(tools).join(\", \") || \"(none)\"}`,\n        );\n      }\n      const response = tools[toolName];\n      return typeof response === \"function\"\n        ? await (response as (a: unknown, s?: AbortSignal) => unknown)(\n            args,\n            signal,\n          )\n        : response;\n    };\n\n    const base: ToolProvider = {\n      getAgentTools: () => record.tools,\n      executeAgentTool: (toolName, args, signal) =>\n        resolve(toolName, args, signal, false, undefined),\n    };\n\n    // Mirror the real `Plugin.asUser` token precondition (plugin.ts) so the\n    // recorded `asUser` flag reflects genuine user-scope resolution rather than\n    // being unconditionally true: a request with no `x-forwarded-access-token`\n    // throws `missingToken` (production behavior), except in development where\n    // the real code skips impersonation. This is edge-faking of asUser's\n    // *contract*, not a reimplementation of `runInUserContext`/`ServiceContext`.\n    //\n    // Deliberately NOT reproduced: the real dev-mode path sets an OTel\n    // `DEV_OBO_FALLBACK_KEY` marker (read by `isDevOboFallback()`). That key is\n    // module-private telemetry plumbing; assert OBO via the recorded\n    // `asUser`/`userId` fields, not `isDevOboFallback()`.\n    const asUser = (req: IAppRequest): ToolProvider => {\n      record.asUserRequests.push(req as express.Request);\n      const token = (req as express.Request)\n        .header?.(\"x-forwarded-access-token\")\n        ?.trim();\n      const userId = (req as express.Request)\n        .header?.(\"x-forwarded-user\")\n        ?.trim();\n      const isDev = process.env.NODE_ENV === \"development\";\n\n      if (!token && !isDev) {\n        throw AuthenticationError.missingToken(\"user token\");\n      }\n      if (token && !userId && !isDev) {\n        throw AuthenticationError.missingUserId();\n      }\n\n      return {\n        ...base,\n        executeAgentTool: (toolName, args, signal) =>\n          resolve(toolName, args, signal, true, userId),\n      };\n    };\n\n    // `registerToolProvider` expects the full ToolProviderPlugin shape\n    // (BasePlugin & ToolProvider & { asUser }). executeTool only ever calls\n    // `asUser` and `executeAgentTool`; the remaining BasePlugin surface is\n    // never touched for a registered provider, so a focused fake plus a cast\n    // is sufficient and avoids reimplementing a plugin.\n    const provider = {\n      name,\n      setup: async () => {},\n      injectRoutes: () => {},\n      getEndpoints: () => ({}),\n      ...base,\n      asUser,\n    } as unknown as BasePlugin &\n      ToolProvider & {\n        asUser: (req: IAppRequest) => ToolProvider;\n      };\n\n    ctx.registerToolProvider(name, provider);\n  }\n\n  for (const [name, tools] of Object.entries(fakes)) {\n    registerProvider(name, tools);\n  }\n\n  async function attach<P extends Plugin>(plugin: P): Promise<P> {\n    // Seed a real in-memory cache if AppKit hasn't initialized one. Idempotent:\n    // getInstance returns any existing singleton (e.g. one a suite already set\n    // up) and ignores the storage argument in that case.\n    if (!cacheReady()) {\n      await CacheManager.getInstance({ storage: new InMemoryStorage({}) });\n    }\n    plugin.attachContext({ context: ctx });\n\n    // Mirror what AppKit core does after attachContext (core/appkit.ts): put\n    // the plugin in the registry so `getPlugins()`/`getPluginNames()`/\n    // `hasPlugin()` and any sibling-plugin lookup behave as in production. Only\n    // register it as a tool provider when it actually is one AND its name does\n    // not collide with an injected fake — the fakes are the authored test\n    // doubles and must not be overwritten by the plugin under test.\n    ctx.registerPlugin(plugin.name, plugin as unknown as BasePlugin);\n    if (isToolProvider(plugin) && !providers.has(plugin.name)) {\n      ctx.registerToolProvider(\n        plugin.name,\n        plugin as unknown as Parameters<typeof ctx.registerToolProvider>[1],\n      );\n    }\n    return plugin;\n  }\n\n  return {\n    ctx,\n    telemetry,\n    toolCalls,\n    routes,\n    providers,\n    registerProvider,\n    attach,\n  };\n}\n\nfunction cacheReady(): boolean {\n  try {\n    CacheManager.getInstanceSync();\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}

package/dist/type-generator/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\nimport type { MetricSchema } from \"./mv-registry/types\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n * @property retry - when true the entry never satisfies a cache hit, so the\n *   query is re-described on the next pass; fresh successful describes\n *   persist `retry: false`\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * One cached metric-view DESCRIBE outcome.\n *\n * `hash` is md5 over `\"<source>|<lane>\"` — the two config inputs that\n * determine a DESCRIBE — so editing either invalidates the entry. `schema`\n * is the full {@link MetricSchema} persisted verbatim (it is JSON-safe by\n * design), letting a warm pass regenerate the metric artifact without a\n * single warehouse call.\n */\nexport interface MetricCacheEntry {\n  hash: string;\n  schema: MetricSchema;\n  retry: boolean;\n}\n\n/**\n * Structural gate for reviving a cached metric entry at partition time.\n *\n * The cache file lives in `node_modules/.databricks` and is plain JSON —\n * hand-edits, truncation, or a stale writer can leave entries whose shape no\n * longer matches {@link MetricCacheEntry}. A malformed entry must read as a\n * cache MISS (re-describe) rather than crash the pass or render revived\n * garbage into the artifacts.\n */\nexport function isRevivableMetricCacheEntry(entry: unknown): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n  const e = entry as Record<string, unknown>;\n  if (typeof e.hash !== \"string\" || typeof e.retry !== \"boolean\") {\n    return false;\n  }\n  const schema = e.schema;\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return false;\n  }\n  const s = schema as Record<string, unknown>;\n  const isColumnArray = (value: unknown): boolean =>\n    Array.isArray(value) &&\n    value.every(\n      (col) =>\n        typeof col === \"object\" &&\n        col !== null &&\n        typeof (col as Record<string, unknown>).name === \"string\" &&\n        typeof (col as Record<string, unknown>).type === \"string\",\n    );\n  return (\n    typeof s.key === \"string\" &&\n    typeof s.source === \"string\" &&\n    (s.lane === \"sp\" || s.lane === \"obo\") &&\n    (s.degraded === undefined || typeof s.degraded === \"boolean\") &&\n    isColumnArray(s.measures) &&\n    isColumnArray(s.dimensions)\n  );\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n * @property metrics - cached metric-view schemas keyed by metric key.\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n  metrics?: Record<string, MetricCacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Change detector stored on {@link MetricCacheEntry.hash}: md5 over\n * `\"<source>|<lane>\"` — the two config inputs that determine a DESCRIBE —\n * so editing either invalidates the entry.\n */\nexport function metricCacheHash(source: string, lane: string): string {\n  return hashSQL(`${source}|${lane}`);\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,uBAAuB;;;;;;;;;;AAwCnD,SAAgB,4BAA4B,OAAyB;AACnE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,UAAU,UACnD,QAAO;CAET,MAAM,SAAS,EAAE;AACjB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAET,MAAM,IAAI;CACV,MAAM,iBAAiB,UACrB,MAAM,QAAQ,MAAM,IACpB,MAAM,OACH,QACC,OAAO,QAAQ,YACf,QAAQ,QACR,OAAQ,IAAgC,SAAS,YACjD,OAAQ,IAAgC,SAAS,SACpD;AACH,QACE,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,WAAW,aACnB,EAAE,SAAS,QAAQ,EAAE,SAAS,WAC9B,EAAE,aAAa,UAAa,OAAO,EAAE,aAAa,cACnD,cAAc,EAAE,SAAS,IACzB,cAAc,EAAE,WAAW;;AAgB/B,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,SAAgB,gBAAgB,QAAgB,MAAsB;AACpE,QAAO,QAAQ,GAAG,OAAO,GAAG,OAAO;;;;;;;AAQrC,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nimport { createLogger } from \"../logging/logger\";\nimport type { MetricSchema } from \"./mv-registry/types\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n * @property retry - when true the entry never satisfies a cache hit, so the\n *   query is re-described on the next pass; fresh successful describes\n *   persist `retry: false`\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * One cached metric-view DESCRIBE outcome.\n *\n * `hash` is md5 over `\"<source>|<lane>\"` — the two config inputs that\n * determine a DESCRIBE — so editing either invalidates the entry. `schema`\n * is the full {@link MetricSchema} persisted verbatim (it is JSON-safe by\n * design), letting a warm pass regenerate the metric artifact without a\n * single warehouse call.\n */\nexport interface MetricCacheEntry {\n  hash: string;\n  schema: MetricSchema;\n  retry: boolean;\n}\n\n/**\n * Structural gate for reviving a cached metric entry at partition time.\n *\n * The cache file lives in `node_modules/.databricks` and is plain JSON —\n * hand-edits, truncation, or a stale writer can leave entries whose shape no\n * longer matches {@link MetricCacheEntry}. A malformed entry must read as a\n * cache MISS (re-describe) rather than crash the pass or render revived\n * garbage into the artifacts.\n */\nexport function isRevivableMetricCacheEntry(entry: unknown): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n  const e = entry as Record<string, unknown>;\n  if (typeof e.hash !== \"string\" || typeof e.retry !== \"boolean\") {\n    return false;\n  }\n  const schema = e.schema;\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return false;\n  }\n  const s = schema as Record<string, unknown>;\n  const isColumnArray = (value: unknown): boolean =>\n    Array.isArray(value) &&\n    value.every(\n      (col) =>\n        typeof col === \"object\" &&\n        col !== null &&\n        typeof (col as Record<string, unknown>).name === \"string\" &&\n        typeof (col as Record<string, unknown>).type === \"string\",\n    );\n  return (\n    typeof s.key === \"string\" &&\n    typeof s.source === \"string\" &&\n    (s.lane === \"sp\" || s.lane === \"obo\") &&\n    (s.degraded === undefined || typeof s.degraded === \"boolean\") &&\n    isColumnArray(s.measures) &&\n    isColumnArray(s.dimensions)\n  );\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n * @property metrics - cached metric-view schemas keyed by metric key.\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n  metrics?: Record<string, MetricCacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Change detector stored on {@link MetricCacheEntry.hash}: md5 over\n * `\"<source>|<lane>\"` — the two config inputs that determine a DESCRIBE —\n * so editing either invalidates the entry.\n */\nexport function metricCacheHash(source: string, lane: string): string {\n  return hashSQL(`${source}|${lane}`);\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAOA,MAAM,SAAS,aAAa,uBAAuB;;;;;;;;;;AAwCnD,SAAgB,4BAA4B,OAAyB;AACnE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,UAAU,UACnD,QAAO;CAET,MAAM,SAAS,EAAE;AACjB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAET,MAAM,IAAI;CACV,MAAM,iBAAiB,UACrB,MAAM,QAAQ,MAAM,IACpB,MAAM,OACH,QACC,OAAO,QAAQ,YACf,QAAQ,QACR,OAAQ,IAAgC,SAAS,YACjD,OAAQ,IAAgC,SAAS,SACpD;AACH,QACE,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,WAAW,aACnB,EAAE,SAAS,QAAQ,EAAE,SAAS,WAC9B,EAAE,aAAa,UAAa,OAAO,EAAE,aAAa,cACnD,cAAc,EAAE,SAAS,IACzB,cAAc,EAAE,WAAW;;AAgB/B,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,SAAgB,gBAAgB,QAAgB,MAAsB;AACpE,QAAO,QAAQ,GAAG,OAAO,GAAG,OAAO;;;;;;;AAQrC,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}