@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/src/client/command.ts

@@ -0,0 +1,54 @@
+import type { z } from "zod";
+
+/**
+ * Base class for all Dimensions API commands.
+ *
+ * Commands are self-contained units with:
+ * - Input schema (Zod) for validation
+ * - Typed input and output
+ * - Execution handled by DimensionsClient.send()
+ */
+export abstract class Command<TInput, TOutput> {
+  /**
+   * Zod schema for input validation.
+   * Must be defined on subclass.
+   */
+  static readonly inputSchema: z.ZodType<unknown>;
+
+  /**
+   * Validated input parameters.
+   */
+  abstract readonly input: TInput;
+
+  /**
+   * Resolves the DSL query for this command.
+   * Override in subclasses that use DSL queries.
+   */
+  resolveQuery?(): string;
+
+  /**
+   * Resolves the API endpoint for this command.
+   * Default is DSL endpoint; override for special endpoints.
+   */
+  resolveEndpoint(): string {
+    return "/api/dsl/v2";
+  }
+
+  /**
+   * Transforms raw API response to typed output.
+   * Override in subclasses.
+   */
+  transformResponse?(response: unknown): TOutput;
+}
+
+/**
+ * Type helper to extract input type from a Command class.
+ */
+export type CommandInput<T extends Command<unknown, unknown>> =
+  T extends Command<infer I, unknown> ? I : never;
+
+/**
+ * Type helper to extract output type from a Command class.
+ */
+export type CommandOutput<T extends Command<unknown, unknown>> =
+  T extends Command<unknown, infer O> ? O : never;

package/src/client/config/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Configuration schemas and loaders.
+ * @module core/config
+ */
+
+export { loadConfig, loadConfigFile } from "./loader.js";
+export type { DslConfig } from "./schemas.js";
+export { DslConfigSchema, RawConfigFileSchema } from "./schemas.js";
+export type { ConfigLoaderOptions, ConfigResult, RawConfigFile } from "./types.js";
+export type { DimensionsConfigFile, LoadDimensionsConfigOptions } from "./unified-loader.js";
+export {
+  DimensionsConfigFileSchema,
+  loadDimensionsConfig,
+  loadServiceConfig,
+} from "./unified-loader.js";

package/src/client/config/loader.ts

@@ -0,0 +1,155 @@
+/**
+ * Configuration file loader with environment variable support.
+ * @module core/config/loader
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { z } from "zod";
+import { ValidationError } from "../errors.js";
+import { RawConfigFileSchema } from "./schemas.js";
+import type { ConfigLoaderOptions, ConfigResult, RawConfigFile } from "./types.js";
+
+const CONFIG_FILE_NAME = ".dimensions.config.json";
+
+/**
+ * Environment variable mapping for each service.
+ */
+const ENV_VAR_MAP: Record<string, Record<string, string>> = {
+  dsl: {
+    apiKey: "DIMENSIONS_DSL_API_KEY",
+    baseUrl: "DIMENSIONS_DSL_BASE_URL",
+  },
+};
+
+/**
+ * Loads and parses a JSON config file.
+ * @param filePath - Path to the config file
+ * @returns Parsed config object, or undefined if file not found
+ * @throws Error if file exists but cannot be parsed
+ */
+export async function loadConfigFile(filePath: string): Promise<RawConfigFile | undefined> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    return RawConfigFileSchema.parse(parsed);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Loads config from environment variables for a service.
+ * @param service - Service name
+ * @returns Config object from env vars, or undefined if not set
+ */
+function loadFromEnv(service: string): Record<string, string> | undefined {
+  const mapping = ENV_VAR_MAP[service];
+  if (!mapping) {
+    return undefined;
+  }
+
+  const config: Record<string, string> = {};
+  let hasAnyValue = false;
+
+  for (const [key, envVar] of Object.entries(mapping)) {
+    const value = process.env[envVar];
+    if (value) {
+      config[key] = value;
+      hasAnyValue = true;
+    }
+  }
+
+  return hasAnyValue ? config : undefined;
+}
+
+/**
+ * Loads configuration with priority:
+ * 1. Explicit configPath
+ * 2. Environment variables (DIMENSIONS_{SERVICE}_{KEY})
+ * 3. .dimensions.config.json in cwd
+ * 4. .dimensions.config.json in home directory
+ *
+ * @param options - Loader options (service is required to extract config from file)
+ * @param schema - Zod schema for validation
+ * @returns Config result with source, or undefined if not found or service not specified
+ * @throws ValidationError if config fails schema validation
+ */
+export async function loadConfig<T>(
+  options: ConfigLoaderOptions,
+  schema: z.ZodSchema<T>,
+): Promise<ConfigResult<T> | undefined> {
+  const { configPath, service, cwd = process.cwd(), homedir = os.homedir() } = options;
+
+  if (configPath) {
+    const rawConfig = await loadConfigFile(configPath);
+    if (rawConfig && service) {
+      const serviceConfig = rawConfig[service as keyof RawConfigFile];
+      if (serviceConfig) {
+        return validateAndReturn(serviceConfig, schema, "explicit");
+      }
+    }
+    return undefined;
+  }
+
+  if (service) {
+    const envConfig = loadFromEnv(service);
+    if (envConfig) {
+      const result = schema.safeParse(envConfig);
+      if (result.success) {
+        return { config: result.data, source: "env" };
+      }
+    }
+  }
+
+  const cwdConfigPath = path.join(cwd, CONFIG_FILE_NAME);
+  const cwdConfig = await loadConfigFile(cwdConfigPath);
+  if (cwdConfig && service) {
+    const serviceConfig = cwdConfig[service as keyof RawConfigFile];
+    if (serviceConfig) {
+      return validateAndReturn(serviceConfig, schema, "cwd");
+    }
+  }
+
+  const homeConfigPath = path.join(homedir, CONFIG_FILE_NAME);
+  const homeConfig = await loadConfigFile(homeConfigPath);
+  if (homeConfig && service) {
+    const serviceConfig = homeConfig[service as keyof RawConfigFile];
+    if (serviceConfig) {
+      return validateAndReturn(serviceConfig, schema, "home");
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Validates config against schema and returns result.
+ * @param config - Raw config object
+ * @param schema - Zod schema
+ * @param source - Config source
+ * @returns Validated config result
+ * @throws ValidationError if validation fails
+ */
+function validateAndReturn<T>(
+  config: unknown,
+  schema: z.ZodSchema<T>,
+  source: ConfigResult<T>["source"],
+): ConfigResult<T> {
+  const result = schema.safeParse(config);
+  if (!result.success) {
+    throw new ValidationError(
+      `Configuration validation failed (source: ${source}): ${result.error.message}`,
+      { issues: result.error.issues, source },
+    );
+  }
+  return { config: result.data, source };
+}

package/src/client/config/node.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js-only configuration file loaders.
+ *
+ * These utilities read `.dimensions.config.json` from disk and merge with
+ * environment variables. They depend on `node:fs/promises` and must not be
+ * imported in browser/edge contexts.
+ *
+ * @example
+ * ```typescript
+ * import { loadDimensionsConfig, loadServiceConfig } from "./node.js";
+ * ```
+ *
+ * @module core/config/node
+ */
+
+export { loadConfig, loadConfigFile } from "./loader.js";
+export type { DimensionsConfigFile } from "./unified-loader.js";
+export {
+  DimensionsConfigFileSchema,
+  loadDimensionsConfig,
+  loadServiceConfig,
+} from "./unified-loader.js";

package/src/client/config/schemas.ts

@@ -0,0 +1,28 @@
+/**
+ * Zod schemas for config validation.
+ * @module core/config/schemas
+ */
+
+import { z } from "zod";
+
+/**
+ * Schema for DSL service configuration.
+ */
+export const DslConfigSchema = z.object({
+  apiKey: z.string().min(1, "API key is required"),
+  baseUrl: z.string().url().optional().default("https://app.dimensions.ai"),
+});
+
+/**
+ * Schema for the raw config file structure.
+ */
+export const RawConfigFileSchema = z.object({
+  dsl: z
+    .object({
+      apiKey: z.string().optional(),
+      baseUrl: z.string().optional(),
+    })
+    .optional(),
+});
+
+export type DslConfig = z.infer<typeof DslConfigSchema>;

package/src/client/config/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Configuration loader types.
+ * @module core/config/types
+ */
+
+/**
+ * Options for loading configuration.
+ */
+export interface ConfigLoaderOptions {
+  /** Explicit path to config file */
+  configPath?: string;
+  /** Service to load config for (e.g., 'dsl') */
+  service?: string;
+  /** @internal Override cwd for tests; defaults to `process.cwd()`. */
+  cwd?: string;
+  /** @internal Override home directory for tests; defaults to `os.homedir()`. */
+  homedir?: string;
+}
+
+/**
+ * Result of loading configuration.
+ */
+export interface ConfigResult<T> {
+  /** Loaded configuration */
+  readonly config: T;
+  /** Source of the configuration */
+  readonly source: "explicit" | "env" | "cwd" | "home";
+}
+
+/**
+ * Raw config file structure with nested service configs.
+ */
+export interface RawConfigFile {
+  /** DSL service configuration */
+  readonly dsl?: {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+  };
+}

package/src/client/config/unified-loader.ts

@@ -0,0 +1,118 @@
+/**
+ * Unified configuration loader for Dimensions DSL settings.
+ * Reads `.dimensions.config.json` with cwd → home fallback and env var override.
+ * @module core/config/unified-loader
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { z } from "zod";
+
+const CONFIG_FILE_NAME = ".dimensions.config.json";
+
+/**
+ * Schema for the Dimensions config file.
+ */
+export const DimensionsConfigFileSchema = z.object({
+  dsl: z
+    .object({
+      apiKey: z.string().optional(),
+      baseUrl: z.string().optional(),
+    })
+    .optional(),
+});
+
+/** Full config file type */
+export type DimensionsConfigFile = z.infer<typeof DimensionsConfigFileSchema>;
+
+/**
+ * Options for `loadDimensionsConfig`. All fields are optional overrides
+ * intended for tests; production callers should omit `options` entirely.
+ */
+export interface LoadDimensionsConfigOptions {
+  /** @internal Override cwd for tests; defaults to `process.cwd()`. */
+  cwd?: string;
+  /** @internal Override home directory for tests; defaults to `os.homedir()`. */
+  homedir?: string;
+}
+
+/**
+ * Loads and parses the Dimensions config file, checking cwd then home directory.
+ * @param options - Optional cwd/homedir overrides (test-only)
+ * @returns Parsed config file, or undefined if no file found
+ */
+export async function loadDimensionsConfig(
+  options: LoadDimensionsConfigOptions = {},
+): Promise<DimensionsConfigFile | undefined> {
+  const { cwd = process.cwd(), homedir = os.homedir() } = options;
+
+  const cwdPath = path.join(cwd, CONFIG_FILE_NAME);
+  const cwdConfig = await readConfigFile(cwdPath);
+  if (cwdConfig) {
+    return cwdConfig;
+  }
+
+  const homePath = path.join(homedir, CONFIG_FILE_NAME);
+  const homeConfig = await readConfigFile(homePath);
+  if (homeConfig) {
+    return homeConfig;
+  }
+
+  return undefined;
+}
+
+/**
+ * Loads a specific service section from the config file with env var fallback.
+ * @param section - Config file section key (e.g., "dsl")
+ * @param envVars - Mapping from config field names to environment variable names
+ * @returns Merged service config, or undefined if nothing found
+ */
+export async function loadServiceConfig<K extends keyof DimensionsConfigFile>(
+  section: K,
+  envVars?: Record<string, string>,
+  options: LoadDimensionsConfigOptions = {},
+): Promise<DimensionsConfigFile[K] | undefined> {
+  const fileConfig = await loadDimensionsConfig(options);
+  const sectionConfig = fileConfig?.[section] as Record<string, unknown> | undefined;
+
+  let merged: Record<string, unknown> | undefined = sectionConfig
+    ? { ...sectionConfig }
+    : undefined;
+
+  if (envVars) {
+    for (const [field, envVar] of Object.entries(envVars)) {
+      const value = process.env[envVar];
+      if (value) {
+        if (!merged) {
+          merged = {};
+        }
+        merged[field] = value;
+      }
+    }
+  }
+
+  return merged as DimensionsConfigFile[K] | undefined;
+}
+
+/**
+ * Reads and parses a config file at the given path.
+ * @param filePath - Absolute path to the config file
+ * @returns Parsed config, or undefined if file not found or invalid
+ */
+async function readConfigFile(filePath: string): Promise<DimensionsConfigFile | undefined> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(content);
+    return DimensionsConfigFileSchema.parse(parsed);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    return undefined;
+  }
+}

package/src/client/config.ts

@@ -0,0 +1,69 @@
+/**
+ * Configuration schema and types for DimensionsClient.
+ * @module config
+ */
+
+import { z } from "zod";
+import { InternalDslEnvSchema } from "./deployment-config.js";
+
+const InternalClientConfigSchema = z.object({
+  service: InternalDslEnvSchema,
+  userEmail: z.string().min(1),
+  clientIp: z.string().optional(),
+});
+
+/**
+ * Zod schema for DimensionsClient configuration.
+ * Validates and provides defaults for all configuration options.
+ */
+export const DimensionsClientConfigSchema = z
+  .object({
+    /** Dimensions API key (required for public backend) */
+    apiKey: z.string().min(1).optional(),
+    /** DSL backend: public JWT API or internal dsl-service */
+    backend: z.enum(["public", "internal"]).default("public"),
+    /** Internal dsl-service settings (required when backend is internal) */
+    internal: InternalClientConfigSchema.optional(),
+    /** Base URL for Dimensions API (public backend only) */
+    baseUrl: z.string().url().default("https://app.dimensions.ai"),
+    /** Request timeout in milliseconds */
+    timeout: z.number().positive().default(30000),
+    /** Maximum number of retry attempts */
+    maxRetries: z.number().nonnegative().default(3),
+    /** Delay between retries in milliseconds */
+    retryDelay: z.number().positive().default(1000),
+    /** Maximum requests per minute (public backend client-side limiter) */
+    rateLimitPerMinute: z.number().positive().default(30),
+    /** Validate DSL queries before sending. Default: true */
+    validateQueries: z.boolean().default(false),
+  })
+  .superRefine((value, ctx) => {
+    if (value.backend === "public") {
+      if (!value.apiKey) {
+        ctx.addIssue({
+          code: "custom",
+          message: "apiKey is required for public backend",
+          path: ["apiKey"],
+        });
+      }
+      return;
+    }
+
+    if (!value.internal) {
+      ctx.addIssue({
+        code: "custom",
+        message: "internal config is required for internal backend",
+        path: ["internal"],
+      });
+    }
+  });
+
+/**
+ * Configuration options for DimensionsClient.
+ */
+export type DimensionsClientConfig = z.input<typeof DimensionsClientConfigSchema>;
+
+/**
+ * Validated configuration with defaults applied.
+ */
+export type ResolvedDimensionsClientConfig = z.output<typeof DimensionsClientConfigSchema>;

package/src/client/deployment-config.ts

@@ -0,0 +1,98 @@
+/**
+ * Deployment mode and hosted backend configuration from environment.
+ * @module client/deployment-config
+ */
+
+import { z } from "zod";
+
+export type DeploymentMode = "local" | "hosted";
+
+export const InternalDslEnvSchema = z.object({
+  serviceUrl: z.string().url(),
+  username: z.string().min(1),
+  password: z.string().min(1),
+  dslSchema: z.string().min(1),
+  host: z.string().min(1),
+  variant: z.string().min(1),
+});
+
+export type InternalDslEnvConfig = z.infer<typeof InternalDslEnvSchema>;
+
+export interface HostedEnvConfig {
+  readonly deploymentMode: "hosted";
+  readonly radarAuthUrl: string;
+  readonly internal: InternalDslEnvConfig;
+  readonly httpPort: number;
+}
+
+export interface LocalEnvConfig {
+  readonly deploymentMode: "local";
+}
+
+export type AppDeploymentConfig = HostedEnvConfig | LocalEnvConfig;
+
+function readDeploymentMode(): DeploymentMode {
+  const raw = process.env.DEPLOYMENT_MODE?.trim().toLowerCase();
+  return raw === "hosted" ? "hosted" : "local";
+}
+
+function readIntEnv(raw: string | undefined, fallback: number, min: number): number {
+  if (raw == null || raw.trim() === "") return fallback;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) && value >= min ? value : fallback;
+}
+
+/**
+ * User identity for hosted schema warmup (`describe schema` at startup).
+ * dsl-service requires X-DIMENSIONS-USER before any MCP client has authenticated.
+ */
+export function hostedBootstrapUser(host: string): string {
+  return `mcp@${host}`;
+}
+
+/**
+ * Loads deployment configuration from environment variables.
+ * @throws {Error} When hosted mode is enabled but required vars are missing
+ */
+export function loadDeploymentConfig(): AppDeploymentConfig {
+  if (readDeploymentMode() !== "hosted") {
+    return { deploymentMode: "local" };
+  }
+
+  const serviceUrl = process.env.DSL_SERVICE_URL;
+  const username = process.env.DSL_SERVICE_USERNAME;
+  const password = process.env.DSL_SERVICE_PASSWORD;
+  const dslSchema = process.env.DSL_SCHEMA;
+  const host = process.env.DSL_HOST;
+  const variant = process.env.DSL_VARIANT;
+  const radarAuthUrl = process.env.RADAR_AUTH_URL;
+
+  const missing: string[] = [];
+  if (!serviceUrl) missing.push("DSL_SERVICE_URL");
+  if (!username) missing.push("DSL_SERVICE_USERNAME");
+  if (!password) missing.push("DSL_SERVICE_PASSWORD");
+  if (!dslSchema) missing.push("DSL_SCHEMA");
+  if (!host) missing.push("DSL_HOST");
+  if (!variant) missing.push("DSL_VARIANT");
+  if (!radarAuthUrl) missing.push("RADAR_AUTH_URL");
+
+  if (missing.length > 0) {
+    throw new Error(`Hosted deployment requires: ${missing.join(", ")}`);
+  }
+
+  const internal = InternalDslEnvSchema.parse({
+    serviceUrl,
+    username,
+    password,
+    dslSchema,
+    host,
+    variant,
+  });
+
+  return {
+    deploymentMode: "hosted",
+    radarAuthUrl: radarAuthUrl!.replace(/\/$/, ""),
+    internal,
+    httpPort: readIntEnv(process.env.MCP_HTTP_PORT, 8080, 1),
+  };
+}