@frontmcp/sdk 0.12.2 → 1.0.0-beta.2

package/esm-loader/app-helpers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @file app-helpers.ts
+ * @description Unified API for declaring external apps in @FrontMcp({ apps: [...] }).
+ *
+ * Provides `app.esm()` for loading @App classes from npm packages and
+ * `app.remote()` for connecting to external MCP servers.
+ *
+ * @example
+ * ```ts
+ * import { FrontMcp, app } from '@frontmcp/sdk';
+ *
+ * @FrontMcp({
+ *   info: { name: 'Gateway', version: '1.0.0' },
+ *   apps: [
+ *     LocalApp,
+ *     app.esm('@acme/tools@^1.0.0', { namespace: 'acme' }),
+ *     app.remote('https://api.example.com/mcp', { namespace: 'api' }),
+ *   ],
+ * })
+ * export default class Server {}
+ * ```
+ */
+import type { RemoteAppMetadata } from '../common/metadata/app.metadata';
+import type { EsmAppOptions, RemoteUrlAppOptions } from '../common/metadata/app.metadata';
+export type { EsmAppOptions, RemoteUrlAppOptions } from '../common/metadata/app.metadata';
+export type { PackageLoader } from '../common/metadata/app.metadata';
+export type { AppFilterConfig, PrimitiveFilterMap } from '../common/metadata/app-filter.metadata';
+/**
+ * Unified namespace for declaring external apps.
+ *
+ * @example
+ * ```ts
+ * // Load @App class from npm
+ * app.esm('@acme/tools@^1.0.0', { namespace: 'acme' })
+ *
+ * // Connect to external MCP server
+ * app.remote('https://api.example.com/mcp', { namespace: 'api' })
+ * ```
+ */
+export declare const app: {
+    /**
+     * Declare an npm package to load at runtime.
+     * The package should export an `@App`-decorated class as its default export.
+     *
+     * @param specifier - npm package specifier (e.g., '@acme/tools@^1.0.0')
+     * @param options - Optional per-app overrides
+     * @returns A `RemoteAppMetadata` ready for use in `@FrontMcp({ apps: [...] })`
+     */
+    readonly esm: (specifier: string, options?: EsmAppOptions) => RemoteAppMetadata;
+    /**
+     * Connect to an external MCP server via HTTP.
+     * The remote server's tools, resources, and prompts are proxied through your gateway.
+     *
+     * @param url - MCP server endpoint URL (e.g., 'https://api.example.com/mcp')
+     * @param options - Optional per-app overrides
+     * @returns A `RemoteAppMetadata` ready for use in `@FrontMcp({ apps: [...] })`
+     */
+    readonly remote: (url: string, options?: RemoteUrlAppOptions) => RemoteAppMetadata;
+};
+//# sourceMappingURL=app-helpers.d.ts.map

package/esm-loader/app-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-helpers.d.ts","sourceRoot":"","sources":["../../src/esm-loader/app-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAE1F,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC1F,YAAY,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAMlG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG;IACd;;;;;;;OAOG;8BACY,MAAM,YAAY,aAAa,KAAG,iBAAiB;IAmClE;;;;;;;OAOG;2BACS,MAAM,YAAY,mBAAmB,KAAG,iBAAiB;CAwB7D,CAAC"}

package/esm-loader/esm-auth.types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file esm-auth.types.ts
+ * @description Authentication configuration for private npm registries and esm.sh CDN.
+ */
+import { z } from 'zod';
+/**
+ * Authentication configuration for accessing private npm registries.
+ * Used both for version resolution (npm registry API) and ESM bundle fetching.
+ */
+export interface EsmRegistryAuth {
+    /**
+     * Custom registry URL (e.g., 'https://npm.pkg.github.com').
+     * If not provided, defaults to 'https://registry.npmjs.org'.
+     */
+    registryUrl?: string;
+    /**
+     * Bearer token for authentication.
+     * Mutually exclusive with `tokenEnvVar`.
+     */
+    token?: string;
+    /**
+     * Environment variable name containing the bearer token.
+     * Resolved at runtime for security (avoids storing tokens in config).
+     * Mutually exclusive with `token`.
+     */
+    tokenEnvVar?: string;
+}
+/**
+ * Zod schema for EsmRegistryAuth validation.
+ */
+export declare const esmRegistryAuthSchema: z.ZodObject<{
+    registryUrl: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    tokenEnvVar: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Default npm registry URL.
+ */
+export declare const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+/**
+ * Resolve the bearer token from an EsmRegistryAuth configuration.
+ * Handles both direct tokens and environment variable references.
+ *
+ * @param auth - Registry auth configuration (optional)
+ * @returns The resolved token, or undefined if no auth configured
+ * @throws Error if tokenEnvVar is specified but the environment variable is not set
+ */
+export declare function resolveRegistryToken(auth?: EsmRegistryAuth): string | undefined;
+/**
+ * Get the registry URL from auth configuration, falling back to default.
+ */
+export declare function getRegistryUrl(auth?: EsmRegistryAuth): string;
+//# sourceMappingURL=esm-auth.types.d.ts.map

package/esm-loader/esm-auth.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-auth.types.d.ts","sourceRoot":"","sources":["../../src/esm-loader/esm-auth.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;iBAQ9B,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAkB/E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAE7D"}

package/esm-loader/esm-cache.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file esm-cache.ts
+ * @description Cache manager for downloaded ESM bundles.
+ *
+ * Supports two modes:
+ * - **Node.js**: File-based cache with `.mjs`/`.cjs` bundles and metadata JSON
+ * - **Browser**: In-memory cache (no file system access)
+ *
+ * The mode is auto-detected. In-memory cache is always used as a fast first-level cache,
+ * with disk persistence as a second level in Node.js environments.
+ */
+/**
+ * Metadata stored alongside each cached ESM bundle.
+ */
+export interface EsmCacheEntry {
+    /** Full package URL used to fetch */
+    packageUrl: string;
+    /** Full package name (e.g., '@acme/mcp-tools') */
+    packageName: string;
+    /** Concrete resolved version */
+    resolvedVersion: string;
+    /** Timestamp when cached */
+    cachedAt: number;
+    /** Path to the cached bundle file (.mjs for ESM, .cjs for bridged CJS; empty in browser) */
+    bundlePath: string;
+    /** HTTP ETag for conditional requests */
+    etag?: string;
+    /** In-memory bundle content (used in browser mode and as fast cache in Node.js) */
+    bundleContent?: string;
+}
+/**
+ * Options for the ESM cache manager.
+ */
+export interface EsmCacheOptions {
+    /**
+     * Root cache directory for disk persistence. Environment-aware default:
+     * - **Browser**: empty string (disk cache disabled, in-memory only)
+     * - **Node.js server** (project has `node_modules/`): `{cwd}/node_modules/.cache/frontmcp-esm/`
+     * - **CLI binary** (no `node_modules/`): `~/.frontmcp/esm-cache/`
+     */
+    cacheDir?: string;
+    /** Maximum age of cached entries in milliseconds. Defaults to 24 hours. */
+    maxAgeMs?: number;
+}
+/**
+ * Cache manager for ESM bundles.
+ *
+ * **Node.js mode**: File-based disk cache with in-memory first-level cache.
+ * ```
+ * {cacheDir}/{hash}/
+ *   bundle.mjs|cjs  - Native ESM or bridged CJS bundle code
+ *   meta.json        - Cache metadata (version, timestamp, etag)
+ * ```
+ *
+ * **Browser mode**: In-memory Map only (no file system).
+ */
+export declare class EsmCacheManager {
+    private readonly cacheDir;
+    private readonly maxAgeMs;
+    private readonly memoryStore;
+    constructor(options?: EsmCacheOptions);
+    /**
+     * Get a cached ESM bundle entry if it exists and is not expired.
+     */
+    get(packageName: string, version: string): Promise<EsmCacheEntry | undefined>;
+    /**
+     * Store an ESM bundle in the cache.
+     */
+    put(packageName: string, version: string, bundleContent: string, packageUrl: string, etag?: string): Promise<EsmCacheEntry>;
+    /**
+     * Invalidate all cached versions for a package.
+     */
+    invalidate(packageName: string): Promise<void>;
+    /**
+     * Remove expired cache entries.
+     */
+    cleanup(maxAgeMs?: number): Promise<number>;
+    /**
+     * Read the cached bundle content from a cache entry.
+     */
+    readBundle(entry: EsmCacheEntry): Promise<string>;
+    /**
+     * Get the cache directory for a specific package+version combination.
+     */
+    private getEntryDir;
+}
+//# sourceMappingURL=esm-cache.d.ts.map

package/esm-loader/esm-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-cache.d.ts","sourceRoot":"","sources":["../../src/esm-loader/esm-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0DH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+CD;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;gBAEpD,OAAO,CAAC,EAAE,eAAe;IAKrC;;OAEG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IA+CnF;;OAEG;IACG,GAAG,CACP,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC;IAoDzB;;OAEG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCpD;;OAEG;IACG,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkDjD;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAYvD;;OAEG;IACH,OAAO,CAAC,WAAW;CAKpB"}

package/esm-loader/esm-manifest.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file esm-manifest.ts
+ * @description Package manifest interface and normalizer for ESM-loaded packages.
+ * Defines the contract that npm packages must follow to be loadable by FrontMCP.
+ */
+import { z } from 'zod';
+/**
+ * The manifest that ESM packages export to declare their MCP primitives.
+ *
+ * Package authors export this as the default export of their package:
+ * ```typescript
+ * export default {
+ *   name: '@acme/mcp-tools',
+ *   version: '1.0.0',
+ *   tools: [SearchTool, CreateIssueTool],
+ *   skills: [{ name: 'triage', ... }],
+ * } satisfies FrontMcpPackageManifest;
+ * ```
+ */
+export interface FrontMcpPackageManifest {
+    /** Package name (should match npm package name) */
+    name: string;
+    /** Package version (should match npm package version) */
+    version: string;
+    /** Package description */
+    description?: string;
+    /** Tool classes or function-style tools */
+    tools?: unknown[];
+    /** Prompt classes or function-style prompts */
+    prompts?: unknown[];
+    /** Resource classes or function-style resources */
+    resources?: unknown[];
+    /** Skill definitions (can include embedded tools via the skill's tools array) */
+    skills?: unknown[];
+    /** Agent classes or function-style agents */
+    agents?: unknown[];
+    /** Job classes or function-style jobs */
+    jobs?: unknown[];
+    /** Workflow classes or function-style workflows */
+    workflows?: unknown[];
+    /** Shared providers for dependency injection */
+    providers?: unknown[];
+}
+/**
+ * Zod schema for basic manifest validation.
+ * We validate the shape loosely since the actual primitives are validated
+ * by their respective registries during registration.
+ */
+export declare const frontMcpPackageManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    prompts: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    jobs: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    workflows: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    providers: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Primitive type keys available in a manifest.
+ */
+export declare const MANIFEST_PRIMITIVE_KEYS: readonly ["tools", "prompts", "resources", "skills", "agents", "jobs", "workflows", "providers"];
+export type ManifestPrimitiveKey = (typeof MANIFEST_PRIMITIVE_KEYS)[number];
+/**
+ * Normalize the default export of an ESM module into a FrontMcpPackageManifest.
+ *
+ * Handles five formats:
+ * 1. A plain manifest object with tools/prompts/etc arrays
+ * 2. A class decorated with @FrontMcp (detected via reflect-metadata)
+ * 3. A module with named exports (tools, prompts, etc. arrays)
+ * 4. A single default export of a decorated primitive class (@Tool, @Resource, etc.)
+ * 5. Named exports of individual decorated classes (scanned and grouped by type)
+ *
+ * @param moduleExport - The raw module export (result of dynamic import())
+ * @returns Normalized FrontMcpPackageManifest
+ * @throws Error if the export cannot be normalized
+ */
+export declare function normalizeEsmExport(moduleExport: unknown): FrontMcpPackageManifest;
+//# sourceMappingURL=esm-manifest.d.ts.map

package/esm-loader/esm-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-manifest.d.ts","sourceRoot":"","sources":["../../src/esm-loader/esm-manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,gDAAgD;IAChD,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;iBAYxC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB,kGAS1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,OAAO,GAAG,uBAAuB,CAyDjF"}

package/esm-loader/esm-module-loader.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file esm-module-loader.ts
+ * @description Core engine for dynamically loading npm packages.
+ *
+ * Supports two runtime environments:
+ * - **Node.js**: fetch → cache to disk → import() from file:// URL
+ * - **Browser**: fetch → in-memory cache → evaluate via Function constructor
+ */
+import type { FrontMcpLogger } from '../common';
+import type { EsmRegistryAuth } from './esm-auth.types';
+import type { EsmCacheManager } from './esm-cache';
+import type { ParsedPackageSpecifier } from './package-specifier';
+import type { FrontMcpPackageManifest } from './esm-manifest';
+/**
+ * Result of loading an ESM package.
+ */
+export interface EsmLoadResult {
+    /** Normalized package manifest with primitives */
+    manifest: FrontMcpPackageManifest;
+    /** Concrete version that was loaded */
+    resolvedVersion: string;
+    /** Whether the bundle came from cache or network */
+    source: 'cache' | 'network';
+    /** Timestamp when the load completed */
+    loadedAt: number;
+    /** The raw module export (for direct access to classes/functions) */
+    rawModule: unknown;
+}
+/**
+ * Options for the ESM module loader.
+ */
+export interface EsmModuleLoaderOptions {
+    /** Cache manager for storing ESM bundles */
+    cache: EsmCacheManager;
+    /** Authentication for private registries */
+    registryAuth?: EsmRegistryAuth;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Logger instance */
+    logger?: FrontMcpLogger;
+    /** Custom ESM CDN base URL */
+    esmBaseUrl?: string;
+}
+/**
+ * Core ESM module loader.
+ *
+ * Loads npm packages dynamically at runtime:
+ * 1. Resolves semver range to concrete version via npm registry
+ * 2. Checks cache for the resolved version (in-memory + disk)
+ * 3. On cache miss, fetches the bundle from esm.sh (or custom CDN)
+ * 4. Caches the bundle (disk in Node.js, in-memory in browser)
+ * 5. Evaluates the module (import() in Node.js, Function constructor in browser)
+ * 6. Normalizes the module export into a FrontMcpPackageManifest
+ */
+export declare class EsmModuleLoader {
+    private readonly cache;
+    private readonly versionResolver;
+    private readonly timeout;
+    private readonly logger?;
+    private readonly esmBaseUrl?;
+    constructor(options: EsmModuleLoaderOptions);
+    /**
+     * Load an npm package and return its normalized manifest.
+     *
+     * @param specifier - Parsed package specifier
+     * @returns Load result with manifest and metadata
+     */
+    load(specifier: ParsedPackageSpecifier): Promise<EsmLoadResult>;
+    /**
+     * Resolve a package specifier's range to a concrete version.
+     */
+    resolveVersion(specifier: ParsedPackageSpecifier): Promise<string>;
+    /**
+     * Load a module from a cached bundle.
+     */
+    private loadFromCache;
+    /**
+     * Fetch ESM bundle from esm.sh, cache it, and load it.
+     */
+    private fetchAndCache;
+    /**
+     * Import a bundle from a local file path (Node.js only).
+     * Uses dynamic import with file:// URL for cross-platform compatibility.
+     */
+    private importFromPath;
+    /**
+     * Import a bundle from its source text.
+     * Detects ESM vs CJS and uses the appropriate evaluation strategy.
+     */
+    private importBundle;
+    /**
+     * Heuristic: content uses ESM export/import syntax at line boundaries.
+     */
+    private looksLikeEsm;
+    /**
+     * Import ESM content via Blob URL (browser) or temp file (Node.js).
+     */
+    private importEsmBundle;
+}
+//# sourceMappingURL=esm-module-loader.d.ts.map

package/esm-loader/esm-module-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-module-loader.d.ts","sourceRoot":"","sources":["../../src/esm-loader/esm-module-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAK9D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,uBAAuB,CAAC;IAClC,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,KAAK,EAAE,eAAe,CAAC;IACvB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,eAAe,CAAC;IAC/B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;gBAEzB,OAAO,EAAE,sBAAsB;IAW3C;;;;;OAKG;IACG,IAAI,CAAC,SAAS,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC;IAmBrE;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKxE;;OAEG;YACW,aAAa;IAsC3B;;OAEG;YACW,aAAa;IAyD3B;;;OAGG;YACW,cAAc;IAQ5B;;;OAGG;YACW,YAAY;IAW1B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;YACW,eAAe;CA2B9B"}

package/esm-loader/factories/esm-context-factories.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file esm-context-factories.ts
+ * @description Factory functions that create context classes for ESM-loaded primitives.
+ *
+ * Unlike remote-mcp context factories (which proxy to a remote MCP server),
+ * these factories create classes that execute code locally in-process.
+ * The ESM module's functions are closed over via closure.
+ */
+import { Type } from '@frontmcp/di';
+import { ToolContext, ToolInputType, ToolOutputType, ResourceContext, PromptContext } from '../../common';
+import type { CallToolResult, ReadResourceResult, GetPromptResult } from '@frontmcp/protocol';
+/**
+ * Handler type for ESM tool execution.
+ * This is the execute function exported by the ESM package.
+ */
+export type EsmToolExecuteHandler = (input: Record<string, unknown>) => Promise<CallToolResult>;
+/**
+ * Handler type for ESM resource reading.
+ */
+export type EsmResourceReadHandler = (uri: string, params: Record<string, string>) => Promise<ReadResourceResult>;
+/**
+ * Handler type for ESM prompt execution.
+ */
+export type EsmPromptExecuteHandler = (args: Record<string, string>) => Promise<GetPromptResult>;
+/**
+ * Creates an ESM tool context class that executes locally in-process.
+ *
+ * The returned class closes over the ESM module's execute function.
+ * When called, it runs the tool handler directly in the same Node.js process.
+ *
+ * @param executeFn - The tool's execute function from the ESM module
+ * @param toolName - The name of the tool (for debugging)
+ * @returns A ToolContext class that executes the ESM tool locally
+ */
+export declare function createEsmToolContextClass(executeFn: EsmToolExecuteHandler, toolName: string): Type<ToolContext<ToolInputType, ToolOutputType, unknown, CallToolResult>>;
+/**
+ * Creates an ESM resource context class that reads locally in-process.
+ *
+ * @param readFn - The resource's read function from the ESM module
+ * @param resourceName - The name of the resource (for debugging)
+ * @returns A ResourceContext class that reads the ESM resource locally
+ */
+export declare function createEsmResourceContextClass<Params extends Record<string, string> = Record<string, string>>(readFn: EsmResourceReadHandler, resourceName: string): Type<ResourceContext<Params, ReadResourceResult>>;
+/**
+ * Creates an ESM prompt context class that executes locally in-process.
+ *
+ * @param executeFn - The prompt's execute function from the ESM module
+ * @param promptName - The name of the prompt (for debugging)
+ * @returns A PromptContext class that executes the ESM prompt locally
+ */
+export declare function createEsmPromptContextClass(executeFn: EsmPromptExecuteHandler, promptName: string): Type<PromptContext>;
+//# sourceMappingURL=esm-context-factories.d.ts.map

package/esm-loader/factories/esm-context-factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-context-factories.d.ts","sourceRoot":"","sources":["../../../src/esm-loader/factories/esm-context-factories.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1G,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE9F;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAElH;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEjG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,qBAAqB,EAChC,QAAQ,EAAE,MAAM,GACf,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAW3E;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1G,MAAM,EAAE,sBAAsB,EAC9B,YAAY,EAAE,MAAM,GACnB,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAUnD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,uBAAuB,EAClC,UAAU,EAAE,MAAM,GACjB,IAAI,CAAC,aAAa,CAAC,CAUrB"}

package/esm-loader/factories/esm-instance-factories.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file esm-instance-factories.ts
+ * @description Factory functions that create standard instances for ESM-loaded primitives.
+ *
+ * Uses the esm-record-builders to create records, then instantiates standard
+ * ToolInstance, ResourceInstance, and PromptInstance. This allows ESM-loaded
+ * entities to use the same hook lifecycle and registry infrastructure as local entities.
+ */
+import type { EntryOwnerRef } from '../../common';
+import type ProviderRegistry from '../../provider/provider.registry';
+import { ToolInstance } from '../../tool/tool.instance';
+import { ResourceInstance } from '../../resource/resource.instance';
+import { PromptInstance } from '../../prompt/prompt.instance';
+import type { EsmToolDefinition, EsmResourceDefinition, EsmPromptDefinition } from './esm-record-builders';
+/**
+ * Create a standard ToolInstance for an ESM-loaded tool.
+ *
+ * The resulting ToolInstance executes the tool's code locally in-process
+ * and participates fully in the hook lifecycle.
+ *
+ * @param tool - ESM tool definition with execute function
+ * @param providers - The provider registry for DI and scope access
+ * @param owner - The entry owner reference (app owner)
+ * @param namespace - Optional namespace prefix for the tool name
+ * @returns A standard ToolInstance that executes the ESM tool locally
+ */
+export declare function createEsmToolInstance(tool: EsmToolDefinition, providers: ProviderRegistry, owner: EntryOwnerRef, namespace?: string): ToolInstance;
+/**
+ * Create a standard ResourceInstance for an ESM-loaded resource.
+ *
+ * @param resource - ESM resource definition with read function
+ * @param providers - The provider registry for DI and scope access
+ * @param owner - The entry owner reference (app owner)
+ * @param namespace - Optional namespace prefix
+ * @returns A standard ResourceInstance that reads the ESM resource locally
+ */
+export declare function createEsmResourceInstance(resource: EsmResourceDefinition, providers: ProviderRegistry, owner: EntryOwnerRef, namespace?: string): ResourceInstance;
+/**
+ * Create a standard PromptInstance for an ESM-loaded prompt.
+ *
+ * @param prompt - ESM prompt definition with execute function
+ * @param providers - The provider registry for DI and scope access
+ * @param owner - The entry owner reference (app owner)
+ * @param namespace - Optional namespace prefix
+ * @returns A standard PromptInstance that executes the ESM prompt locally
+ */
+export declare function createEsmPromptInstance(prompt: EsmPromptDefinition, providers: ProviderRegistry, owner: EntryOwnerRef, namespace?: string): PromptInstance;
+//# sourceMappingURL=esm-instance-factories.d.ts.map

package/esm-loader/factories/esm-instance-factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-instance-factories.d.ts","sourceRoot":"","sources":["../../../src/esm-loader/factories/esm-instance-factories.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,gBAAgB,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE3G;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,aAAa,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,YAAY,CAGd;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,aAAa,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAGlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,aAAa,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAGhB"}

package/esm-loader/factories/esm-record-builders.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file esm-record-builders.ts
+ * @description Functions that build standard records for ESM-loaded primitives.
+ *
+ * Unlike remote-mcp record-builders (which proxy to a remote server), these builders
+ * create records for tools/resources/prompts that execute locally in-process.
+ */
+import type { ToolClassTokenRecord, ResourceClassTokenRecord, PromptClassTokenRecord } from '../../common';
+import type { EsmToolExecuteHandler, EsmResourceReadHandler, EsmPromptExecuteHandler } from './esm-context-factories';
+/**
+ * Metadata for an ESM-loaded tool (simplified shape for tools loaded from packages).
+ */
+export interface EsmToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: unknown;
+    execute: EsmToolExecuteHandler;
+}
+/**
+ * Metadata for an ESM-loaded resource.
+ */
+export interface EsmResourceDefinition {
+    name: string;
+    description?: string;
+    uri: string;
+    mimeType?: string;
+    read: EsmResourceReadHandler;
+}
+/**
+ * Metadata for an ESM-loaded prompt.
+ */
+export interface EsmPromptDefinition {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    execute: EsmPromptExecuteHandler;
+}
+/**
+ * Build a ToolClassTokenRecord for an ESM-loaded tool.
+ *
+ * Detects whether the tool's `inputSchema` is a Zod raw shape or JSON Schema
+ * and routes accordingly:
+ * - Zod shape → stored in `inputSchema` (converted by `getInputJsonSchema()`)
+ * - JSON Schema → stored in `rawInputSchema` (used as-is)
+ *
+ * @param tool - ESM tool definition with execute function
+ * @param namespace - Optional namespace prefix for the tool name
+ * @returns Standard ToolClassTokenRecord for use with ToolInstance
+ */
+export declare function buildEsmToolRecord(tool: EsmToolDefinition, namespace?: string): ToolClassTokenRecord;
+/**
+ * Build a ResourceClassTokenRecord for an ESM-loaded resource.
+ *
+ * @param resource - ESM resource definition with read function
+ * @param namespace - Optional namespace prefix
+ * @returns Standard ResourceClassTokenRecord
+ */
+export declare function buildEsmResourceRecord(resource: EsmResourceDefinition, namespace?: string): ResourceClassTokenRecord;
+/**
+ * Build a PromptClassTokenRecord for an ESM-loaded prompt.
+ *
+ * @param prompt - ESM prompt definition with execute function
+ * @param namespace - Optional namespace prefix
+ * @returns Standard PromptClassTokenRecord
+ */
+export declare function buildEsmPromptRecord(prompt: EsmPromptDefinition, namespace?: string): PromptClassTokenRecord;
+//# sourceMappingURL=esm-record-builders.d.ts.map

package/esm-loader/factories/esm-record-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-record-builders.d.ts","sourceRoot":"","sources":["../../../src/esm-loader/factories/esm-record-builders.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAM3G,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEtH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,sBAAsB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC9E,OAAO,EAAE,uBAAuB,CAAC;CAClC;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAoCpG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,qBAAqB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAiBpH;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAqB5G"}

package/esm-loader/factories/index.d.ts

@@ -0,0 +1,4 @@
+export { createEsmToolContextClass, createEsmResourceContextClass, createEsmPromptContextClass, type EsmToolExecuteHandler, type EsmResourceReadHandler, type EsmPromptExecuteHandler, } from './esm-context-factories';
+export { buildEsmToolRecord, buildEsmResourceRecord, buildEsmPromptRecord, type EsmToolDefinition, type EsmResourceDefinition, type EsmPromptDefinition, } from './esm-record-builders';
+export { createEsmToolInstance, createEsmResourceInstance, createEsmPromptInstance } from './esm-instance-factories';
+//# sourceMappingURL=index.d.ts.map

package/esm-loader/factories/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/esm-loader/factories/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC7B,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/esm-loader/index.d.ts

@@ -0,0 +1,10 @@
+export { parsePackageSpecifier, isPackageSpecifier, buildEsmShUrl, ESM_SH_BASE_URL, type ParsedPackageSpecifier, } from './package-specifier';
+export { type EsmRegistryAuth, esmRegistryAuthSchema, resolveRegistryToken, getRegistryUrl, DEFAULT_NPM_REGISTRY, } from './esm-auth.types';
+export { satisfiesRange, maxSatisfying, isValidRange, isValidVersion, compareVersions, isNewerVersion, } from './semver.utils';
+export { EsmCacheManager, type EsmCacheEntry, type EsmCacheOptions } from './esm-cache';
+export { normalizeEsmExport, frontMcpPackageManifestSchema, MANIFEST_PRIMITIVE_KEYS, type FrontMcpPackageManifest, type ManifestPrimitiveKey, } from './esm-manifest';
+export { VersionResolver, type VersionResolutionResult, type VersionResolverOptions } from './version-resolver';
+export { EsmModuleLoader, type EsmLoadResult, type EsmModuleLoaderOptions } from './esm-module-loader';
+export { VersionPoller, type VersionPollerOptions, type VersionCheckResult } from './version-poller';
+export { createEsmToolContextClass, createEsmResourceContextClass, createEsmPromptContextClass, type EsmToolExecuteHandler, type EsmResourceReadHandler, type EsmPromptExecuteHandler, buildEsmToolRecord, buildEsmResourceRecord, buildEsmPromptRecord, type EsmToolDefinition, type EsmResourceDefinition, type EsmPromptDefinition, createEsmToolInstance, createEsmResourceInstance, createEsmPromptInstance, } from './factories';
+//# sourceMappingURL=index.d.ts.map

package/esm-loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/esm-loader/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EACL,KAAK,eAAe,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAKxF,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAE,eAAe,EAAE,KAAK,uBAAuB,EAAE,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKhH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAKvG,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAKrG,OAAO,EAEL,yBAAyB,EACzB,6BAA6B,EAC7B,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAE5B,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EAExB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,aAAa,CAAC"}