@frontmcp/sdk 0.4.0 → 0.5.0

package/src/transport/transport.registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.registry.js","sourceRoot":"","sources":["../../../src/transport/transport.registry.ts"],"names":[],"mappings":"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","sourcesContent":["// server/transport/transport.registry.ts\nimport {createHash} from 'crypto';\nimport {\n  TransportBus,\n  Transporter,\n  TransportKey,\n  TransportRegistryBucket,\n  TransportTokenBucket,\n  TransportType,\n  TransportTypeBucket,\n} from './transport.types';\nimport {RemoteTransporter} from './transport.remote';\nimport {LocalTransporter} from './transport.local';\nimport {ServerResponse} from '../common';\nimport {Scope} from '../scope';\nimport HandleStreamableHttpFlow from './flows/handle.streamable-http.flow';\nimport HandleSseFlow from './flows/handle.sse.flow';\n\nexport class TransportService {\n  readonly ready: Promise<void>;\n  private readonly byType: TransportRegistryBucket = new Map();\n  private readonly distributed: boolean;\n  private readonly bus?: TransportBus;\n  private readonly scope: Scope;\n\n  constructor(scope: Scope) {\n    this.scope = scope;\n    this.distributed = false; // get from scope metadata\n    this.bus = undefined; // get from scope metadata\n    if (this.distributed && !this.bus) {\n      throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');\n    }\n\n    this.ready = this.initialize();\n\n  }\n\n\n  private async initialize() {\n    await this.scope.registryFlows(\n      HandleStreamableHttpFlow,\n      HandleSseFlow,\n    );\n  }\n\n  async destroy() {\n    /* empty */\n  }\n\n  async getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) return local;\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        return new RemoteTransporter(key, this.bus);\n      }\n    }\n\n    return undefined;\n  }\n\n  async createTransporter(\n    type: TransportType,\n    token: string,\n    sessionId: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, sessionId);\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      key.sessionId = sessionId;\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  async destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) {\n      await local.destroy(reason);\n      return;\n    }\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        await this.bus.destroyRemote(key, reason);\n        return;\n      }\n    }\n\n    throw new Error('Invalid session: cannot destroy non-existent transporter.');\n  }\n\n  /* --------------------------------- internals -------------------------------- */\n\n  private sha256(value: string): string {\n    return createHash('sha256').update(value, 'utf8').digest('hex');\n  }\n\n  private keyOf(type: TransportType, token: string, sessionId: string, sessionIdSse?: string): TransportKey {\n    return {\n      type,\n      token,\n      tokenHash: this.sha256(token),\n      sessionId,\n      sessionIdSse,\n    };\n  }\n\n  private ensureTypeBucket(type: TransportType): TransportTypeBucket {\n    let bucket = this.byType.get(type);\n    if (!bucket) {\n      bucket = new Map<string, TransportTokenBucket>();\n      this.byType.set(type, bucket);\n    }\n    return bucket;\n  }\n\n  private ensureTokenBucket(typeBucket: TransportTypeBucket, tokenHash: string): TransportTokenBucket {\n    let bucket = typeBucket.get(tokenHash);\n    if (!bucket) {\n      bucket = new Map<string, Transporter>();\n      typeBucket.set(tokenHash, bucket);\n    }\n    return bucket;\n  }\n\n\n  private lookupLocal(key: TransportKey): Transporter | undefined {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return undefined;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return undefined;\n    return tokenBucket.get(key.sessionId);\n  }\n\n  private insertLocal(key: TransportKey, t: Transporter): void {\n    const typeBucket = this.ensureTypeBucket(key.type);\n    const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);\n    tokenBucket.set(key.sessionId, t);\n  }\n\n  private evictLocal(key: TransportKey): void {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return;\n    tokenBucket.delete(key.sessionId);\n    if (tokenBucket.size === 0) typeBucket.delete(key.tokenHash);\n    if (typeBucket.size === 0) this.byType.delete(key.type);\n  }\n}\n"]}
+{"version":3,"file":"transport.registry.js","sourceRoot":"","sources":["../../../src/transport/transport.registry.ts"],"names":[],"mappings":"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","sourcesContent":["// server/transport/transport.registry.ts\nimport { createHash } from 'crypto';\nimport {\n  TransportBus,\n  Transporter,\n  TransportKey,\n  TransportRegistryBucket,\n  TransportTokenBucket,\n  TransportType,\n  TransportTypeBucket,\n} from './transport.types';\nimport { RemoteTransporter } from './transport.remote';\nimport { LocalTransporter } from './transport.local';\nimport { ServerResponse } from '../common';\nimport { Scope } from '../scope';\nimport HandleStreamableHttpFlow from './flows/handle.streamable-http.flow';\nimport HandleSseFlow from './flows/handle.sse.flow';\nimport HandleStatelessHttpFlow from './flows/handle.stateless-http.flow';\n\nexport class TransportService {\n  readonly ready: Promise<void>;\n  private readonly byType: TransportRegistryBucket = new Map();\n  private readonly distributed: boolean;\n  private readonly bus?: TransportBus;\n  private readonly scope: Scope;\n\n  /**\n   * Session history cache for tracking if sessions were ever created.\n   * Used to differentiate between \"session never initialized\" (HTTP 400) and\n   * \"session expired/terminated\" (HTTP 404) per MCP Spec 2025-11-25.\n   *\n   * Key: \"type:tokenHash:sessionId\", Value: creation timestamp\n   */\n  private readonly sessionHistory: Map<string, number> = new Map();\n  private readonly MAX_SESSION_HISTORY = 10000;\n\n  constructor(scope: Scope) {\n    this.scope = scope;\n    this.distributed = false; // get from scope metadata\n    this.bus = undefined; // get from scope metadata\n    if (this.distributed && !this.bus) {\n      throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');\n    }\n\n    this.ready = this.initialize();\n  }\n\n  private async initialize() {\n    await this.scope.registryFlows(HandleStreamableHttpFlow, HandleSseFlow, HandleStatelessHttpFlow);\n  }\n\n  async destroy() {\n    /* empty */\n  }\n\n  async getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) return local;\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        return new RemoteTransporter(key, this.bus);\n      }\n    }\n\n    return undefined;\n  }\n\n  async createTransporter(\n    type: TransportType,\n    token: string,\n    sessionId: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, sessionId);\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      key.sessionId = sessionId;\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  async destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) {\n      await local.destroy(reason);\n      return;\n    }\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        await this.bus.destroyRemote(key, reason);\n        return;\n      }\n    }\n\n    throw new Error('Invalid session: cannot destroy non-existent transporter.');\n  }\n\n  /**\n   * Get or create a shared singleton transport for anonymous stateless requests.\n   * All anonymous requests share the same transport instance.\n   */\n  async getOrCreateAnonymousStatelessTransport(type: TransportType, res: ServerResponse): Promise<Transporter> {\n    const key = this.keyOf(type, '__anonymous__', '__stateless__');\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    // Create shared transport for all anonymous requests\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  /**\n   * Get or create a singleton transport for authenticated stateless requests.\n   * Each unique token gets its own singleton transport.\n   */\n  async getOrCreateAuthenticatedStatelessTransport(\n    type: TransportType,\n    token: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, '__stateless__');\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    // Create singleton transport for this token\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  /**\n   * Check if a session was ever created (even if it's been terminated/evicted).\n   * Used to differentiate between \"session never initialized\" (HTTP 400) and\n   * \"session expired/terminated\" (HTTP 404) per MCP Spec 2025-11-25.\n   *\n   * @param type - Transport type (e.g., 'streamable-http', 'sse')\n   * @param token - The authorization token\n   * @param sessionId - The session ID to check\n   * @returns true if session was ever created, false otherwise\n   */\n  wasSessionCreated(type: TransportType, token: string, sessionId: string): boolean {\n    const tokenHash = this.sha256(token);\n    const historyKey = `${type}:${tokenHash}:${sessionId}`;\n    return this.sessionHistory.has(historyKey);\n  }\n\n  /* --------------------------------- internals -------------------------------- */\n\n  private sha256(value: string): string {\n    return createHash('sha256').update(value, 'utf8').digest('hex');\n  }\n\n  private keyOf(type: TransportType, token: string, sessionId: string, sessionIdSse?: string): TransportKey {\n    return {\n      type,\n      token,\n      tokenHash: this.sha256(token),\n      sessionId,\n      sessionIdSse,\n    };\n  }\n\n  private ensureTypeBucket(type: TransportType): TransportTypeBucket {\n    let bucket = this.byType.get(type);\n    if (!bucket) {\n      bucket = new Map<string, TransportTokenBucket>();\n      this.byType.set(type, bucket);\n    }\n    return bucket;\n  }\n\n  private ensureTokenBucket(typeBucket: TransportTypeBucket, tokenHash: string): TransportTokenBucket {\n    let bucket = typeBucket.get(tokenHash);\n    if (!bucket) {\n      bucket = new Map<string, Transporter>();\n      typeBucket.set(tokenHash, bucket);\n    }\n    return bucket;\n  }\n\n  private lookupLocal(key: TransportKey): Transporter | undefined {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return undefined;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return undefined;\n    return tokenBucket.get(key.sessionId);\n  }\n\n  private insertLocal(key: TransportKey, t: Transporter): void {\n    const typeBucket = this.ensureTypeBucket(key.type);\n    const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);\n    tokenBucket.set(key.sessionId, t);\n\n    // Record session creation in history for HTTP 404 detection\n    const historyKey = `${key.type}:${key.tokenHash}:${key.sessionId}`;\n    this.sessionHistory.set(historyKey, Date.now());\n\n    // Evict oldest entries if cache exceeds max size (LRU-like eviction)\n    if (this.sessionHistory.size > this.MAX_SESSION_HISTORY) {\n      const entries = [...this.sessionHistory.entries()].sort((a, b) => a[1] - b[1]);\n      // Remove oldest 10% of entries\n      const toEvict = Math.ceil(this.MAX_SESSION_HISTORY * 0.1);\n      for (let i = 0; i < toEvict && i < entries.length; i++) {\n        this.sessionHistory.delete(entries[i][0]);\n      }\n    }\n  }\n\n  private evictLocal(key: TransportKey): void {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return;\n    tokenBucket.delete(key.sessionId);\n    if (tokenBucket.size === 0) typeBucket.delete(key.tokenHash);\n    if (typeBucket.size === 0) this.byType.delete(key.type);\n  }\n}\n"]}

package/src/transport/transport.types.d.ts

@@ -1,9 +1,9 @@
 import { AuthenticatedServerRequest } from '../server/server.types';
 import { ElicitResult } from '@modelcontextprotocol/sdk/types.js';
-import { ZodObject } from 'zod';
+import { ZodType } from 'zod';
 import { Infer } from '../utils/types.utils';
 import { ServerResponse } from '../common';
-export type TransportType = 'sse' | 'streamable-http' | 'http';
+export type TransportType = 'sse' | 'streamable-http' | 'http' | 'stateless-http';
 export interface TransportKey {
     type: TransportType;
     token: string;
@@ -48,7 +48,7 @@ export interface TransportRegistryOptions {
 export type TransportTokenBucket = Map<string, Transporter>;
 export type TransportTypeBucket = Map<string, TransportTokenBucket>;
 export type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>;
-export type TypedElicitResult<T extends ZodObject<any>> = {
+export type TypedElicitResult<T extends ZodType> = {
     action: ElicitResult['action'];
     content: Infer<T>;
 };

package/src/transport/transport.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.types.js","sourceRoot":"","sources":["../../../src/transport/transport.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthenticatedServerRequest } from '../server/server.types';\nimport { ElicitResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ZodObject } from 'zod';\nimport { Infer } from '../utils/types.utils';\nimport { ServerResponse } from '../common';\n\nexport type TransportType = 'sse' | 'streamable-http' | 'http';\n\nexport interface TransportKey {\n  type: TransportType;\n  token: string;\n  tokenHash: string;\n  sessionId: string;\n  sessionIdSse?: string;\n}\n\nexport interface RemoteLocation {\n  nodeId: string;\n  channel: string;\n}\n\nexport interface TransportBus {\n  nodeId(): string;\n\n  advertise(key: TransportKey): Promise<void>;\n\n  revoke(key: TransportKey): Promise<void>;\n\n  lookup(key: TransportKey): Promise<RemoteLocation | null>;\n\n  proxyRequest(\n    key: TransportKey,\n    payload: {\n      method?: string;\n      url?: string;\n      headers?: Record<string, string | string[] | undefined>;\n    },\n    io: {\n      onResponseStart(statusCode: number, headers: Record<string, string>): void;\n      onResponseChunk(chunk: Uint8Array | string): void;\n      onResponseEnd(finalChunk?: Uint8Array | string): void;\n      onError?(err: Error | string): void;\n    },\n  ): Promise<void>;\n\n  destroyRemote(key: TransportKey, reason?: string): Promise<void>;\n}\n\n/* --------------------------------- API ---------------------------------- */\n\nexport interface Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  destroy(reason?: string): Promise<void>;\n\n  ping(timeoutMs?: number): Promise<boolean>;\n}\n\nexport interface TransportRegistryOptions {\n  distributed?: boolean;\n  bus?: TransportBus;\n}\n\nexport type TransportTokenBucket = Map<string, Transporter>; // sessionHash -> Transporter\nexport type TransportTypeBucket = Map<string, TransportTokenBucket>; // tokenHash   -> TokenBucket\nexport type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>; // tokenHash   -> TokenBucket\n\nexport type TypedElicitResult<T extends ZodObject<any>> = { action: ElicitResult['action']; content: Infer<T> };\n"]}
+{"version":3,"file":"transport.types.js","sourceRoot":"","sources":["../../../src/transport/transport.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthenticatedServerRequest } from '../server/server.types';\nimport { ElicitResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ZodType } from 'zod';\nimport { Infer } from '../utils/types.utils';\nimport { ServerResponse } from '../common';\n\nexport type TransportType = 'sse' | 'streamable-http' | 'http' | 'stateless-http';\n\nexport interface TransportKey {\n  type: TransportType;\n  token: string;\n  tokenHash: string;\n  sessionId: string;\n  sessionIdSse?: string;\n}\n\nexport interface RemoteLocation {\n  nodeId: string;\n  channel: string;\n}\n\nexport interface TransportBus {\n  nodeId(): string;\n\n  advertise(key: TransportKey): Promise<void>;\n\n  revoke(key: TransportKey): Promise<void>;\n\n  lookup(key: TransportKey): Promise<RemoteLocation | null>;\n\n  proxyRequest(\n    key: TransportKey,\n    payload: {\n      method?: string;\n      url?: string;\n      headers?: Record<string, string | string[] | undefined>;\n    },\n    io: {\n      onResponseStart(statusCode: number, headers: Record<string, string>): void;\n      onResponseChunk(chunk: Uint8Array | string): void;\n      onResponseEnd(finalChunk?: Uint8Array | string): void;\n      onError?(err: Error | string): void;\n    },\n  ): Promise<void>;\n\n  destroyRemote(key: TransportKey, reason?: string): Promise<void>;\n}\n\n/* --------------------------------- API ---------------------------------- */\n\nexport interface Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  destroy(reason?: string): Promise<void>;\n\n  ping(timeoutMs?: number): Promise<boolean>;\n}\n\nexport interface TransportRegistryOptions {\n  distributed?: boolean;\n  bus?: TransportBus;\n}\n\nexport type TransportTokenBucket = Map<string, Transporter>; // sessionHash -> Transporter\nexport type TransportTypeBucket = Map<string, TransportTokenBucket>; // tokenHash   -> TokenBucket\nexport type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>; // tokenHash   -> TokenBucket\n\nexport type TypedElicitResult<T extends ZodType> = { action: ElicitResult['action']; content: Infer<T> };\n"]}

package/src/utils/content.utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sanitize arbitrary JS values into JSON-safe objects suitable for:
+ *   - MCP `structuredContent`
+ *   - JSON.stringify without circular reference errors
+ *
+ * Rules:
+ *   - Drop functions and symbols.
+ *   - BigInt → string.
+ *   - Date → ISO string.
+ *   - Error → { name, message, stack }.
+ *   - Map → plain object.
+ *   - Set → array.
+ *   - Protect against circular references via WeakSet.
+ */
+export declare function sanitizeToJson(value: unknown): unknown;
+/**
+ * Convert a value to MCP structuredContent format.
+ * Returns Record<string, unknown> or undefined (matching MCP's structuredContent type).
+ * Primitives and arrays are wrapped in { value: ... }.
+ */
+export declare function toStructuredContent(value: unknown): Record<string, unknown> | undefined;
+/** MCP-compatible text resource content */
+export type TextContent = {
+    uri: string;
+    mimeType?: string;
+    text: string;
+};
+/** MCP-compatible blob resource content */
+export type BlobContent = {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+};
+/** MCP-compatible resource content (text or blob) */
+export type ResourceContent = TextContent | BlobContent;
+/**
+ * Build a resource content item for MCP ReadResourceResult format.
+ * Handles both text and binary (blob) content.
+ *
+ * @param uri - The resource URI
+ * @param content - The content to serialize (string, Buffer, object, etc.)
+ * @param mimeType - Optional MIME type override
+ */
+export declare function buildResourceContent(uri: string, content: unknown, mimeType?: string): ResourceContent;
+/**
+ * Infer MIME type from file extension or content.
+ */
+export declare function inferMimeType(uri: string, content?: unknown): string;

package/src/utils/content.utils.js

@@ -0,0 +1,194 @@
+"use strict";
+// file: libs/sdk/src/utils/content.utils.ts
+// Content building and sanitization utilities for MCP responses
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeToJson = sanitizeToJson;
+exports.toStructuredContent = toStructuredContent;
+exports.buildResourceContent = buildResourceContent;
+exports.inferMimeType = inferMimeType;
+/**
+ * Sanitize arbitrary JS values into JSON-safe objects suitable for:
+ *   - MCP `structuredContent`
+ *   - JSON.stringify without circular reference errors
+ *
+ * Rules:
+ *   - Drop functions and symbols.
+ *   - BigInt → string.
+ *   - Date → ISO string.
+ *   - Error → { name, message, stack }.
+ *   - Map → plain object.
+ *   - Set → array.
+ *   - Protect against circular references via WeakSet.
+ */
+function sanitizeToJson(value) {
+    const seen = new WeakSet();
+    function sanitize(val) {
+        if (typeof val === 'function' || typeof val === 'symbol') {
+            return undefined;
+        }
+        if (typeof val === 'bigint') {
+            return val.toString();
+        }
+        if (val instanceof Date) {
+            return val.toISOString();
+        }
+        if (val instanceof Error) {
+            return {
+                name: val.name,
+                message: val.message,
+                stack: val.stack,
+            };
+        }
+        if (val instanceof Map) {
+            const obj = {};
+            for (const [k, v] of val.entries()) {
+                obj[String(k)] = sanitize(v);
+            }
+            return obj;
+        }
+        if (val instanceof Set) {
+            return Array.from(val).map(sanitize);
+        }
+        if (Array.isArray(val)) {
+            if (seen.has(val)) {
+                return undefined;
+            }
+            seen.add(val);
+            return val.map(sanitize);
+        }
+        if (val && typeof val === 'object') {
+            if (seen.has(val)) {
+                // Drop circular references
+                return undefined;
+            }
+            seen.add(val);
+            const sanitized = {};
+            for (const [key, value] of Object.entries(val)) {
+                const clean = sanitize(value);
+                if (clean !== undefined) {
+                    sanitized[key] = clean;
+                }
+            }
+            return sanitized;
+        }
+        // Primitives pass through
+        return val;
+    }
+    return sanitize(value);
+}
+/**
+ * Convert a value to MCP structuredContent format.
+ * Returns Record<string, unknown> or undefined (matching MCP's structuredContent type).
+ * Primitives and arrays are wrapped in { value: ... }.
+ */
+function toStructuredContent(value) {
+    const result = sanitizeToJson(value);
+    if (result === undefined || result === null)
+        return undefined;
+    if (typeof result === 'object' && !Array.isArray(result)) {
+        return result;
+    }
+    // Wrap primitives and arrays in an object
+    return { value: result };
+}
+/**
+ * Build a resource content item for MCP ReadResourceResult format.
+ * Handles both text and binary (blob) content.
+ *
+ * @param uri - The resource URI
+ * @param content - The content to serialize (string, Buffer, object, etc.)
+ * @param mimeType - Optional MIME type override
+ */
+function buildResourceContent(uri, content, mimeType) {
+    // If content is already in the expected format
+    if (content && typeof content === 'object') {
+        const obj = content;
+        if ('blob' in obj && typeof obj['blob'] === 'string') {
+            return {
+                uri,
+                mimeType: obj['mimeType'] || mimeType,
+                blob: obj['blob'],
+            };
+        }
+        if ('text' in obj && typeof obj['text'] === 'string') {
+            return {
+                uri,
+                mimeType: obj['mimeType'] || mimeType,
+                text: obj['text'],
+            };
+        }
+    }
+    // Binary content (Buffer, Uint8Array)
+    if (Buffer.isBuffer(content) || content instanceof Uint8Array) {
+        const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+        return {
+            uri,
+            mimeType: mimeType || 'application/octet-stream',
+            blob: buffer.toString('base64'),
+        };
+    }
+    // String content
+    if (typeof content === 'string') {
+        return {
+            uri,
+            mimeType: mimeType || 'text/plain',
+            text: content,
+        };
+    }
+    // JSON-serializable content
+    try {
+        return {
+            uri,
+            mimeType: mimeType || 'application/json',
+            text: JSON.stringify(content),
+        };
+    }
+    catch {
+        return {
+            uri,
+            mimeType: mimeType || 'text/plain',
+            text: String(content),
+        };
+    }
+}
+/**
+ * Infer MIME type from file extension or content.
+ */
+function inferMimeType(uri, content) {
+    // Try to infer from URI extension
+    const ext = uri.split('.').pop()?.toLowerCase();
+    const mimeTypes = {
+        json: 'application/json',
+        xml: 'application/xml',
+        html: 'text/html',
+        htm: 'text/html',
+        css: 'text/css',
+        js: 'application/javascript',
+        ts: 'application/typescript',
+        txt: 'text/plain',
+        md: 'text/markdown',
+        yaml: 'application/yaml',
+        yml: 'application/yaml',
+        csv: 'text/csv',
+        png: 'image/png',
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        gif: 'image/gif',
+        svg: 'image/svg+xml',
+        pdf: 'application/pdf',
+    };
+    if (ext && mimeTypes[ext]) {
+        return mimeTypes[ext];
+    }
+    // Try to infer from content
+    if (typeof content === 'string') {
+        if (content.trim().startsWith('{') || content.trim().startsWith('[')) {
+            return 'application/json';
+        }
+        if (content.trim().startsWith('<')) {
+            return content.includes('<!DOCTYPE html') || content.includes('<html') ? 'text/html' : 'application/xml';
+        }
+    }
+    return 'text/plain';
+}
+//# sourceMappingURL=content.utils.js.map

package/src/utils/content.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.utils.js","sourceRoot":"","sources":["../../../src/utils/content.utils.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,gEAAgE;;AAgBhE,wCAkEC;AAOD,kDAQC;AA2BD,oDAqDC;AAKD,sCAuCC;AA3ND;;;;;;;;;;;;;GAaG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IAEnC,SAAS,QAAQ,CAAC,GAAY;QAC5B,IAAI,OAAO,GAAG,KAAK,UAAU,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;QACxB,CAAC;QAED,IAAI,GAAG,YAAY,IAAI,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;QAED,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;YACvB,MAAM,GAAG,GAA4B,EAAE,CAAC;YACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;gBACnC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;YACvB,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;QAED,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,2BAA2B;gBAC3B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAEd,MAAM,SAAS,GAA4B,EAAE,CAAC;YAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACzB,CAAC;YACH,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,0BAA0B;QAC1B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,KAAc;IAChD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC9D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,OAAO,MAAiC,CAAC;IAC3C,CAAC;IACD,0CAA0C;IAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAmBD;;;;;;;GAOG;AACH,SAAgB,oBAAoB,CAAC,GAAW,EAAE,OAAgB,EAAE,QAAiB;IACnF,+CAA+C;IAC/C,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,OAAkC,CAAC;QAC/C,IAAI,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO;gBACL,GAAG;gBACH,QAAQ,EAAG,GAAG,CAAC,UAAU,CAAY,IAAI,QAAQ;gBACjD,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;aAClB,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO;gBACL,GAAG;gBACH,QAAQ,EAAG,GAAG,CAAC,UAAU,CAAY,IAAI,QAAQ;gBACjD,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;aAClB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,YAAY,UAAU,EAAE,CAAC;QAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzE,OAAO;YACL,GAAG;YACH,QAAQ,EAAE,QAAQ,IAAI,0BAA0B;YAChD,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,iBAAiB;IACjB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO;YACL,GAAG;YACH,QAAQ,EAAE,QAAQ,IAAI,YAAY;YAClC,IAAI,EAAE,OAAO;SACd,CAAC;IACJ,CAAC;IAED,4BAA4B;IAC5B,IAAI,CAAC;QACH,OAAO;YACL,GAAG;YACH,QAAQ,EAAE,QAAQ,IAAI,kBAAkB;YACxC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SAC9B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,GAAG;YACH,QAAQ,EAAE,QAAQ,IAAI,YAAY;YAClC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC;SACtB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,GAAW,EAAE,OAAiB;IAC1D,kCAAkC;IAClC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,CAAC;IAChD,MAAM,SAAS,GAA2B;QACxC,IAAI,EAAE,kBAAkB;QACxB,GAAG,EAAE,iBAAiB;QACtB,IAAI,EAAE,WAAW;QACjB,GAAG,EAAE,WAAW;QAChB,GAAG,EAAE,UAAU;QACf,EAAE,EAAE,wBAAwB;QAC5B,EAAE,EAAE,wBAAwB;QAC5B,GAAG,EAAE,YAAY;QACjB,EAAE,EAAE,eAAe;QACnB,IAAI,EAAE,kBAAkB;QACxB,GAAG,EAAE,kBAAkB;QACvB,GAAG,EAAE,UAAU;QACf,GAAG,EAAE,WAAW;QAChB,GAAG,EAAE,YAAY;QACjB,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,WAAW;QAChB,GAAG,EAAE,eAAe;QACpB,GAAG,EAAE,iBAAiB;KACvB,CAAC;IAEF,IAAI,GAAG,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,4BAA4B;IAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrE,OAAO,kBAAkB,CAAC;QAC5B,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAC3G,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["// file: libs/sdk/src/utils/content.utils.ts\n// Content building and sanitization utilities for MCP responses\n\n/**\n * Sanitize arbitrary JS values into JSON-safe objects suitable for:\n *   - MCP `structuredContent`\n *   - JSON.stringify without circular reference errors\n *\n * Rules:\n *   - Drop functions and symbols.\n *   - BigInt → string.\n *   - Date → ISO string.\n *   - Error → { name, message, stack }.\n *   - Map → plain object.\n *   - Set → array.\n *   - Protect against circular references via WeakSet.\n */\nexport function sanitizeToJson(value: unknown): unknown {\n  const seen = new WeakSet<object>();\n\n  function sanitize(val: unknown): unknown {\n    if (typeof val === 'function' || typeof val === 'symbol') {\n      return undefined;\n    }\n\n    if (typeof val === 'bigint') {\n      return val.toString();\n    }\n\n    if (val instanceof Date) {\n      return val.toISOString();\n    }\n\n    if (val instanceof Error) {\n      return {\n        name: val.name,\n        message: val.message,\n        stack: val.stack,\n      };\n    }\n\n    if (val instanceof Map) {\n      const obj: Record<string, unknown> = {};\n      for (const [k, v] of val.entries()) {\n        obj[String(k)] = sanitize(v);\n      }\n      return obj;\n    }\n\n    if (val instanceof Set) {\n      return Array.from(val).map(sanitize);\n    }\n\n    if (Array.isArray(val)) {\n      if (seen.has(val)) {\n        return undefined;\n      }\n      seen.add(val);\n      return val.map(sanitize);\n    }\n\n    if (val && typeof val === 'object') {\n      if (seen.has(val)) {\n        // Drop circular references\n        return undefined;\n      }\n      seen.add(val);\n\n      const sanitized: Record<string, unknown> = {};\n      for (const [key, value] of Object.entries(val)) {\n        const clean = sanitize(value);\n        if (clean !== undefined) {\n          sanitized[key] = clean;\n        }\n      }\n      return sanitized;\n    }\n\n    // Primitives pass through\n    return val;\n  }\n\n  return sanitize(value);\n}\n\n/**\n * Convert a value to MCP structuredContent format.\n * Returns Record<string, unknown> or undefined (matching MCP's structuredContent type).\n * Primitives and arrays are wrapped in { value: ... }.\n */\nexport function toStructuredContent(value: unknown): Record<string, unknown> | undefined {\n  const result = sanitizeToJson(value);\n  if (result === undefined || result === null) return undefined;\n  if (typeof result === 'object' && !Array.isArray(result)) {\n    return result as Record<string, unknown>;\n  }\n  // Wrap primitives and arrays in an object\n  return { value: result };\n}\n\n/** MCP-compatible text resource content */\nexport type TextContent = {\n  uri: string;\n  mimeType?: string;\n  text: string;\n};\n\n/** MCP-compatible blob resource content */\nexport type BlobContent = {\n  uri: string;\n  mimeType?: string;\n  blob: string;\n};\n\n/** MCP-compatible resource content (text or blob) */\nexport type ResourceContent = TextContent | BlobContent;\n\n/**\n * Build a resource content item for MCP ReadResourceResult format.\n * Handles both text and binary (blob) content.\n *\n * @param uri - The resource URI\n * @param content - The content to serialize (string, Buffer, object, etc.)\n * @param mimeType - Optional MIME type override\n */\nexport function buildResourceContent(uri: string, content: unknown, mimeType?: string): ResourceContent {\n  // If content is already in the expected format\n  if (content && typeof content === 'object') {\n    const obj = content as Record<string, unknown>;\n    if ('blob' in obj && typeof obj['blob'] === 'string') {\n      return {\n        uri,\n        mimeType: (obj['mimeType'] as string) || mimeType,\n        blob: obj['blob'],\n      };\n    }\n    if ('text' in obj && typeof obj['text'] === 'string') {\n      return {\n        uri,\n        mimeType: (obj['mimeType'] as string) || mimeType,\n        text: obj['text'],\n      };\n    }\n  }\n\n  // Binary content (Buffer, Uint8Array)\n  if (Buffer.isBuffer(content) || content instanceof Uint8Array) {\n    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);\n    return {\n      uri,\n      mimeType: mimeType || 'application/octet-stream',\n      blob: buffer.toString('base64'),\n    };\n  }\n\n  // String content\n  if (typeof content === 'string') {\n    return {\n      uri,\n      mimeType: mimeType || 'text/plain',\n      text: content,\n    };\n  }\n\n  // JSON-serializable content\n  try {\n    return {\n      uri,\n      mimeType: mimeType || 'application/json',\n      text: JSON.stringify(content),\n    };\n  } catch {\n    return {\n      uri,\n      mimeType: mimeType || 'text/plain',\n      text: String(content),\n    };\n  }\n}\n\n/**\n * Infer MIME type from file extension or content.\n */\nexport function inferMimeType(uri: string, content?: unknown): string {\n  // Try to infer from URI extension\n  const ext = uri.split('.').pop()?.toLowerCase();\n  const mimeTypes: Record<string, string> = {\n    json: 'application/json',\n    xml: 'application/xml',\n    html: 'text/html',\n    htm: 'text/html',\n    css: 'text/css',\n    js: 'application/javascript',\n    ts: 'application/typescript',\n    txt: 'text/plain',\n    md: 'text/markdown',\n    yaml: 'application/yaml',\n    yml: 'application/yaml',\n    csv: 'text/csv',\n    png: 'image/png',\n    jpg: 'image/jpeg',\n    jpeg: 'image/jpeg',\n    gif: 'image/gif',\n    svg: 'image/svg+xml',\n    pdf: 'application/pdf',\n  };\n\n  if (ext && mimeTypes[ext]) {\n    return mimeTypes[ext];\n  }\n\n  // Try to infer from content\n  if (typeof content === 'string') {\n    if (content.trim().startsWith('{') || content.trim().startsWith('[')) {\n      return 'application/json';\n    }\n    if (content.trim().startsWith('<')) {\n      return content.includes('<!DOCTYPE html') || content.includes('<html') ? 'text/html' : 'application/xml';\n    }\n  }\n\n  return 'text/plain';\n}\n"]}

package/src/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { NameCase, splitWords, toCase, sepFor, normalizeSegment, normalizeProviderId, normalizeOwnerPath, shortHash, ensureMaxLen, } from './naming.utils';
+export { ownerKeyOf, qualifiedNameOf, parseQualifiedName, lineageDepth, lineagesEqual, isAncestorLineage, } from './lineage.utils';
+export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate } from './uri-validation.utils';
+export { parseUriTemplate, matchUriTemplate, expandUriTemplate } from './uri-template.utils';
+export { tokenName, isClass, isPromise, depsOfClass, depsOfFunc } from './token.utils';
+export { sanitizeToJson, toStructuredContent, TextContent, BlobContent, ResourceContent, buildResourceContent, inferMimeType, } from './content.utils';
+export { idFromString } from './string.utils';
+export { getMetadata, setMetadata, hasAsyncWith } from './metadata.utils';

package/src/utils/index.js

@@ -0,0 +1,55 @@
+"use strict";
+// file: libs/sdk/src/utils/index.ts
+// Centralized exports for SDK utilities
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAsyncWith = exports.setMetadata = exports.getMetadata = exports.idFromString = exports.inferMimeType = exports.buildResourceContent = exports.toStructuredContent = exports.sanitizeToJson = exports.depsOfFunc = exports.depsOfClass = exports.isPromise = exports.isClass = exports.tokenName = exports.expandUriTemplate = exports.matchUriTemplate = exports.parseUriTemplate = exports.isValidMcpUriTemplate = exports.extractUriScheme = exports.isValidMcpUri = exports.isAncestorLineage = exports.lineagesEqual = exports.lineageDepth = exports.parseQualifiedName = exports.qualifiedNameOf = exports.ownerKeyOf = exports.ensureMaxLen = exports.shortHash = exports.normalizeOwnerPath = exports.normalizeProviderId = exports.normalizeSegment = exports.sepFor = exports.toCase = exports.splitWords = void 0;
+// Naming and case conversion utilities
+var naming_utils_1 = require("./naming.utils");
+Object.defineProperty(exports, "splitWords", { enumerable: true, get: function () { return naming_utils_1.splitWords; } });
+Object.defineProperty(exports, "toCase", { enumerable: true, get: function () { return naming_utils_1.toCase; } });
+Object.defineProperty(exports, "sepFor", { enumerable: true, get: function () { return naming_utils_1.sepFor; } });
+Object.defineProperty(exports, "normalizeSegment", { enumerable: true, get: function () { return naming_utils_1.normalizeSegment; } });
+Object.defineProperty(exports, "normalizeProviderId", { enumerable: true, get: function () { return naming_utils_1.normalizeProviderId; } });
+Object.defineProperty(exports, "normalizeOwnerPath", { enumerable: true, get: function () { return naming_utils_1.normalizeOwnerPath; } });
+Object.defineProperty(exports, "shortHash", { enumerable: true, get: function () { return naming_utils_1.shortHash; } });
+Object.defineProperty(exports, "ensureMaxLen", { enumerable: true, get: function () { return naming_utils_1.ensureMaxLen; } });
+// Owner lineage and qualified name utilities
+var lineage_utils_1 = require("./lineage.utils");
+Object.defineProperty(exports, "ownerKeyOf", { enumerable: true, get: function () { return lineage_utils_1.ownerKeyOf; } });
+Object.defineProperty(exports, "qualifiedNameOf", { enumerable: true, get: function () { return lineage_utils_1.qualifiedNameOf; } });
+Object.defineProperty(exports, "parseQualifiedName", { enumerable: true, get: function () { return lineage_utils_1.parseQualifiedName; } });
+Object.defineProperty(exports, "lineageDepth", { enumerable: true, get: function () { return lineage_utils_1.lineageDepth; } });
+Object.defineProperty(exports, "lineagesEqual", { enumerable: true, get: function () { return lineage_utils_1.lineagesEqual; } });
+Object.defineProperty(exports, "isAncestorLineage", { enumerable: true, get: function () { return lineage_utils_1.isAncestorLineage; } });
+// URI validation utilities (RFC 3986)
+var uri_validation_utils_1 = require("./uri-validation.utils");
+Object.defineProperty(exports, "isValidMcpUri", { enumerable: true, get: function () { return uri_validation_utils_1.isValidMcpUri; } });
+Object.defineProperty(exports, "extractUriScheme", { enumerable: true, get: function () { return uri_validation_utils_1.extractUriScheme; } });
+Object.defineProperty(exports, "isValidMcpUriTemplate", { enumerable: true, get: function () { return uri_validation_utils_1.isValidMcpUriTemplate; } });
+// URI template parsing and matching utilities
+var uri_template_utils_1 = require("./uri-template.utils");
+Object.defineProperty(exports, "parseUriTemplate", { enumerable: true, get: function () { return uri_template_utils_1.parseUriTemplate; } });
+Object.defineProperty(exports, "matchUriTemplate", { enumerable: true, get: function () { return uri_template_utils_1.matchUriTemplate; } });
+Object.defineProperty(exports, "expandUriTemplate", { enumerable: true, get: function () { return uri_template_utils_1.expandUriTemplate; } });
+// Token utilities
+var token_utils_1 = require("./token.utils");
+Object.defineProperty(exports, "tokenName", { enumerable: true, get: function () { return token_utils_1.tokenName; } });
+Object.defineProperty(exports, "isClass", { enumerable: true, get: function () { return token_utils_1.isClass; } });
+Object.defineProperty(exports, "isPromise", { enumerable: true, get: function () { return token_utils_1.isPromise; } });
+Object.defineProperty(exports, "depsOfClass", { enumerable: true, get: function () { return token_utils_1.depsOfClass; } });
+Object.defineProperty(exports, "depsOfFunc", { enumerable: true, get: function () { return token_utils_1.depsOfFunc; } });
+// Content utilities
+var content_utils_1 = require("./content.utils");
+Object.defineProperty(exports, "sanitizeToJson", { enumerable: true, get: function () { return content_utils_1.sanitizeToJson; } });
+Object.defineProperty(exports, "toStructuredContent", { enumerable: true, get: function () { return content_utils_1.toStructuredContent; } });
+Object.defineProperty(exports, "buildResourceContent", { enumerable: true, get: function () { return content_utils_1.buildResourceContent; } });
+Object.defineProperty(exports, "inferMimeType", { enumerable: true, get: function () { return content_utils_1.inferMimeType; } });
+// String utilities
+var string_utils_1 = require("./string.utils");
+Object.defineProperty(exports, "idFromString", { enumerable: true, get: function () { return string_utils_1.idFromString; } });
+// Metadata utilities
+var metadata_utils_1 = require("./metadata.utils");
+Object.defineProperty(exports, "getMetadata", { enumerable: true, get: function () { return metadata_utils_1.getMetadata; } });
+Object.defineProperty(exports, "setMetadata", { enumerable: true, get: function () { return metadata_utils_1.setMetadata; } });
+Object.defineProperty(exports, "hasAsyncWith", { enumerable: true, get: function () { return metadata_utils_1.hasAsyncWith; } });
+//# sourceMappingURL=index.js.map

package/src/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;AACpC,wCAAwC;;;AAExC,uCAAuC;AACvC,+CAUwB;AARtB,0GAAA,UAAU,OAAA;AACV,sGAAA,MAAM,OAAA;AACN,sGAAA,MAAM,OAAA;AACN,gHAAA,gBAAgB,OAAA;AAChB,mHAAA,mBAAmB,OAAA;AACnB,kHAAA,kBAAkB,OAAA;AAClB,yGAAA,SAAS,OAAA;AACT,4GAAA,YAAY,OAAA;AAGd,6CAA6C;AAC7C,iDAOyB;AANvB,2GAAA,UAAU,OAAA;AACV,gHAAA,eAAe,OAAA;AACf,mHAAA,kBAAkB,OAAA;AAClB,6GAAA,YAAY,OAAA;AACZ,8GAAA,aAAa,OAAA;AACb,kHAAA,iBAAiB,OAAA;AAGnB,sCAAsC;AACtC,+DAAgG;AAAvF,qHAAA,aAAa,OAAA;AAAE,wHAAA,gBAAgB,OAAA;AAAE,6HAAA,qBAAqB,OAAA;AAE/D,8CAA8C;AAC9C,2DAA6F;AAApF,sHAAA,gBAAgB,OAAA;AAAE,sHAAA,gBAAgB,OAAA;AAAE,uHAAA,iBAAiB,OAAA;AAE9D,kBAAkB;AAClB,6CAAuF;AAA9E,wGAAA,SAAS,OAAA;AAAE,sGAAA,OAAO,OAAA;AAAE,wGAAA,SAAS,OAAA;AAAE,0GAAA,WAAW,OAAA;AAAE,yGAAA,UAAU,OAAA;AAE/D,oBAAoB;AACpB,iDAQyB;AAPvB,+GAAA,cAAc,OAAA;AACd,oHAAA,mBAAmB,OAAA;AAInB,qHAAA,oBAAoB,OAAA;AACpB,8GAAA,aAAa,OAAA;AAGf,mBAAmB;AACnB,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AAErB,qBAAqB;AACrB,mDAA0E;AAAjE,6GAAA,WAAW,OAAA;AAAE,6GAAA,WAAW,OAAA;AAAE,8GAAA,YAAY,OAAA","sourcesContent":["// file: libs/sdk/src/utils/index.ts\n// Centralized exports for SDK utilities\n\n// Naming and case conversion utilities\nexport {\n  NameCase,\n  splitWords,\n  toCase,\n  sepFor,\n  normalizeSegment,\n  normalizeProviderId,\n  normalizeOwnerPath,\n  shortHash,\n  ensureMaxLen,\n} from './naming.utils';\n\n// Owner lineage and qualified name utilities\nexport {\n  ownerKeyOf,\n  qualifiedNameOf,\n  parseQualifiedName,\n  lineageDepth,\n  lineagesEqual,\n  isAncestorLineage,\n} from './lineage.utils';\n\n// URI validation utilities (RFC 3986)\nexport { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate } from './uri-validation.utils';\n\n// URI template parsing and matching utilities\nexport { parseUriTemplate, matchUriTemplate, expandUriTemplate } from './uri-template.utils';\n\n// Token utilities\nexport { tokenName, isClass, isPromise, depsOfClass, depsOfFunc } from './token.utils';\n\n// Content utilities\nexport {\n  sanitizeToJson,\n  toStructuredContent,\n  TextContent,\n  BlobContent,\n  ResourceContent,\n  buildResourceContent,\n  inferMimeType,\n} from './content.utils';\n\n// String utilities\nexport { idFromString } from './string.utils';\n\n// Metadata utilities\nexport { getMetadata, setMetadata, hasAsyncWith } from './metadata.utils';\n"]}

package/src/utils/lineage.utils.d.ts

@@ -0,0 +1,40 @@
+import { EntryLineage } from '../common';
+/**
+ * Convert an entry lineage to a string key.
+ *
+ * @example
+ * ownerKeyOf([{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }])
+ * => "app:Portal/plugin:Auth"
+ */
+export declare function ownerKeyOf(lineage: EntryLineage): string;
+/**
+ * Create a fully qualified name from lineage and name.
+ *
+ * @example
+ * qualifiedNameOf([{ kind: 'app', id: 'Portal' }], 'myTool')
+ * => "app:Portal:myTool"
+ */
+export declare function qualifiedNameOf(lineage: EntryLineage, name: string): string;
+/**
+ * Parse a qualified name back into lineage and name.
+ *
+ * @example
+ * parseQualifiedName("app:Portal/plugin:Auth:myTool")
+ * => { lineage: [{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }], name: 'myTool' }
+ */
+export declare function parseQualifiedName(qualifiedName: string): {
+    lineage: EntryLineage;
+    name: string;
+} | null;
+/**
+ * Get the depth of a lineage (number of owners).
+ */
+export declare function lineageDepth(lineage: EntryLineage): number;
+/**
+ * Check if two lineages are equal.
+ */
+export declare function lineagesEqual(a: EntryLineage, b: EntryLineage): boolean;
+/**
+ * Check if lineage `a` is an ancestor of lineage `b`.
+ */
+export declare function isAncestorLineage(ancestor: EntryLineage, descendant: EntryLineage): boolean;

package/src/utils/lineage.utils.js

@@ -0,0 +1,82 @@
+"use strict";
+// file: libs/sdk/src/utils/lineage.utils.ts
+// Owner lineage and qualified name utilities
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownerKeyOf = ownerKeyOf;
+exports.qualifiedNameOf = qualifiedNameOf;
+exports.parseQualifiedName = parseQualifiedName;
+exports.lineageDepth = lineageDepth;
+exports.lineagesEqual = lineagesEqual;
+exports.isAncestorLineage = isAncestorLineage;
+/**
+ * Convert an entry lineage to a string key.
+ *
+ * @example
+ * ownerKeyOf([{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }])
+ * => "app:Portal/plugin:Auth"
+ */
+function ownerKeyOf(lineage) {
+    return lineage.map((o) => `${o.kind}:${o.id}`).join('/');
+}
+/**
+ * Create a fully qualified name from lineage and name.
+ *
+ * @example
+ * qualifiedNameOf([{ kind: 'app', id: 'Portal' }], 'myTool')
+ * => "app:Portal:myTool"
+ */
+function qualifiedNameOf(lineage, name) {
+    return `${ownerKeyOf(lineage)}:${name}`;
+}
+/**
+ * Parse a qualified name back into lineage and name.
+ *
+ * @example
+ * parseQualifiedName("app:Portal/plugin:Auth:myTool")
+ * => { lineage: [{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }], name: 'myTool' }
+ */
+function parseQualifiedName(qualifiedName) {
+    const lastColon = qualifiedName.lastIndexOf(':');
+    if (lastColon === -1)
+        return null;
+    const ownerKey = qualifiedName.slice(0, lastColon);
+    const name = qualifiedName.slice(lastColon + 1);
+    const lineage = [];
+    const parts = ownerKey.split('/');
+    for (const part of parts) {
+        const colonIdx = part.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const kind = part.slice(0, colonIdx);
+        if (kind !== 'scope' && kind !== 'app' && kind !== 'plugin')
+            continue;
+        const id = part.slice(colonIdx + 1);
+        // `ref` is required by EntryOwnerRef but cannot be resolved from string parsing.
+        // Callers must resolve the ref from context if needed.
+        lineage.push({ kind, id, ref: undefined });
+    }
+    return { lineage, name };
+}
+/**
+ * Get the depth of a lineage (number of owners).
+ */
+function lineageDepth(lineage) {
+    return lineage.length;
+}
+/**
+ * Check if two lineages are equal.
+ */
+function lineagesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((owner, i) => owner.kind === b[i].kind && owner.id === b[i].id);
+}
+/**
+ * Check if lineage `a` is an ancestor of lineage `b`.
+ */
+function isAncestorLineage(ancestor, descendant) {
+    if (ancestor.length >= descendant.length)
+        return false;
+    return ancestor.every((owner, i) => owner.kind === descendant[i].kind && owner.id === descendant[i].id);
+}
+//# sourceMappingURL=lineage.utils.js.map

package/src/utils/lineage.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.utils.js","sourceRoot":"","sources":["../../../src/utils/lineage.utils.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,6CAA6C;;AAW7C,gCAEC;AASD,0CAEC;AASD,gDAsBC;AAKD,oCAEC;AAKD,sCAGC;AAKD,8CAGC;AA1ED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,OAAqB;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,OAAqB,EAAE,IAAY;IACjE,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,aAAqB;IACtD,MAAM,SAAS,GAAG,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjD,IAAI,SAAS,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAEhD,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,SAAS;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,QAAQ;YAAE,SAAS;QACtE,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;QACpC,iFAAiF;QACjF,uDAAuD;QACvD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,SAAgB,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,OAAqB;IAChD,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,CAAe,EAAE,CAAe;IAC5D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,QAAsB,EAAE,UAAwB;IAChF,IAAI,QAAQ,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACvD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC1G,CAAC","sourcesContent":["// file: libs/sdk/src/utils/lineage.utils.ts\n// Owner lineage and qualified name utilities\n\nimport { EntryLineage } from '../common';\n\n/**\n * Convert an entry lineage to a string key.\n *\n * @example\n * ownerKeyOf([{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }])\n * => \"app:Portal/plugin:Auth\"\n */\nexport function ownerKeyOf(lineage: EntryLineage): string {\n  return lineage.map((o) => `${o.kind}:${o.id}`).join('/');\n}\n\n/**\n * Create a fully qualified name from lineage and name.\n *\n * @example\n * qualifiedNameOf([{ kind: 'app', id: 'Portal' }], 'myTool')\n * => \"app:Portal:myTool\"\n */\nexport function qualifiedNameOf(lineage: EntryLineage, name: string): string {\n  return `${ownerKeyOf(lineage)}:${name}`;\n}\n\n/**\n * Parse a qualified name back into lineage and name.\n *\n * @example\n * parseQualifiedName(\"app:Portal/plugin:Auth:myTool\")\n * => { lineage: [{ kind: 'app', id: 'Portal' }, { kind: 'plugin', id: 'Auth' }], name: 'myTool' }\n */\nexport function parseQualifiedName(qualifiedName: string): { lineage: EntryLineage; name: string } | null {\n  const lastColon = qualifiedName.lastIndexOf(':');\n  if (lastColon === -1) return null;\n\n  const ownerKey = qualifiedName.slice(0, lastColon);\n  const name = qualifiedName.slice(lastColon + 1);\n\n  const lineage: EntryLineage = [];\n  const parts = ownerKey.split('/');\n\n  for (const part of parts) {\n    const colonIdx = part.indexOf(':');\n    if (colonIdx === -1) continue;\n    const kind = part.slice(0, colonIdx);\n    if (kind !== 'scope' && kind !== 'app' && kind !== 'plugin') continue;\n    const id = part.slice(colonIdx + 1);\n    // `ref` is required by EntryOwnerRef but cannot be resolved from string parsing.\n    // Callers must resolve the ref from context if needed.\n    lineage.push({ kind, id, ref: undefined as any });\n  }\n\n  return { lineage, name };\n}\n\n/**\n * Get the depth of a lineage (number of owners).\n */\nexport function lineageDepth(lineage: EntryLineage): number {\n  return lineage.length;\n}\n\n/**\n * Check if two lineages are equal.\n */\nexport function lineagesEqual(a: EntryLineage, b: EntryLineage): boolean {\n  if (a.length !== b.length) return false;\n  return a.every((owner, i) => owner.kind === b[i].kind && owner.id === b[i].id);\n}\n\n/**\n * Check if lineage `a` is an ancestor of lineage `b`.\n */\nexport function isAncestorLineage(ancestor: EntryLineage, descendant: EntryLineage): boolean {\n  if (ancestor.length >= descendant.length) return false;\n  return ancestor.every((owner, i) => owner.kind === descendant[i].kind && owner.id === descendant[i].id);\n}\n"]}

package/src/utils/naming.utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Supported naming conventions for MCP identifiers
+ */
+export type NameCase = 'snake' | 'kebab' | 'dot' | 'camel';
+/**
+ * Split a string into words, handling camelCase, PascalCase, and delimiters.
+ *
+ * @example
+ * splitWords("myFunctionName") => ["my", "Function", "Name"]
+ * splitWords("my_function_name") => ["my", "function", "name"]
+ */
+export declare function splitWords(input: string): string[];
+/**
+ * Convert words to a specific naming case.
+ *
+ * @example
+ * toCase(["my", "function"], "snake") => "my_function"
+ * toCase(["my", "function"], "camel") => "myFunction"
+ */
+export declare function toCase(words: string[], kind: NameCase): string;
+/**
+ * Get the separator character for a naming case.
+ */
+export declare function sepFor(kind: NameCase): string;
+/**
+ * Normalize a single segment (name part) to MCP-safe characters.
+ */
+export declare function normalizeSegment(raw: string, kind: NameCase): string;
+/**
+ * Normalize a provider ID to MCP-safe characters.
+ */
+export declare function normalizeProviderId(raw: string | undefined, kind: NameCase): string | undefined;
+/**
+ * Normalize an owner path (app:id/plugin:id) to the specified naming case.
+ */
+export declare function normalizeOwnerPath(ownerKey: string, kind: NameCase): string;
+/**
+ * Generate a short hash (6 hex chars) from a string.
+ * Uses djb2 algorithm for fast, reasonable distribution.
+ */
+export declare function shortHash(s: string): string;
+/**
+ * Ensure a name fits within a maximum length, using hash truncation if needed.
+ * Preserves meaningful suffix while adding a hash for uniqueness.
+ */
+export declare function ensureMaxLen(name: string, max: number): string;