@resourcexjs/core 2.5.4 → 2.5.6

package/dist/index.d.ts

@@ -177,4 +177,730 @@ declare function parse(locator: string): RXL;
 * @returns RXA archive object
 */
 declare function wrap(buffer: Buffer): RXA;
-export { wrap, resource, parse, manifest, locate, format, extract, define, archive, ResourceXError, RXR, RXM, RXL, RXD, RXA, ManifestError, LocatorError, DefinitionError, ContentError };
+/**
+* Isolator type for resolver execution.
+* Matches SandboX isolator types directly.
+* Configured at Registry level, not per-type.
+*
+* - "none": No isolation, fastest (~10ms), for development
+* - "srt": OS-level isolation (~50ms), secure local dev
+* - "cloudflare": Container isolation (~100ms), local Docker or edge
+* - "e2b": MicroVM isolation (~150ms), production (planned)
+*/
+type IsolatorType = "none" | "srt" | "cloudflare" | "e2b";
+/**
+* ResolveContext - Pure data context passed to resolver in sandbox.
+*
+* This is a serializable data structure that replaces RXR for sandbox execution.
+* The executor pre-processes RXR (extracts files) before passing to resolver.
+*/
+interface ResolveContext {
+	/**
+	* Resource manifest metadata.
+	*/
+	manifest: {
+		domain: string
+		path?: string
+		name: string
+		type: string
+		version: string
+	};
+	/**
+	* Extracted files from archive.
+	* Key is file path, value is file content as Uint8Array.
+	*/
+	files: Record<string, Uint8Array>;
+}
+/**
+* BundledType - Pre-bundled resource type ready for execution.
+* Contains bundled code string instead of closure.
+*
+* Note: Sandbox isolation is configured at Registry level via createRegistry({ sandbox: ... })
+*/
+interface BundledType {
+	/**
+	* Type name (e.g., "text", "json", "prompt").
+	*/
+	name: string;
+	/**
+	* Alternative names for this type.
+	*/
+	aliases?: string[];
+	/**
+	* Human-readable description.
+	*/
+	description: string;
+	/**
+	* JSON Schema for resolver arguments.
+	*/
+	schema?: JSONSchema;
+	/**
+	* Bundled resolver code (executable in sandbox).
+	*/
+	code: string;
+}
+/**
+* JSON Schema property definition.
+*/
+interface JSONSchemaProperty {
+	type: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+	description?: string;
+	default?: unknown;
+	enum?: unknown[];
+	items?: JSONSchemaProperty;
+	properties?: Record<string, JSONSchemaProperty>;
+	required?: string[];
+}
+/**
+* JSON Schema definition for resolver arguments.
+* Used by UI to render parameter forms.
+*/
+interface JSONSchema extends JSONSchemaProperty {
+	$schema?: string;
+	title?: string;
+}
+/**
+* ResolvedResource - Structured result object returned by resolver.
+* Contains execute function, original resource, and optional schema for UI rendering.
+*/
+interface ResolvedResource<
+	TArgs = void,
+	TResult = unknown
+> {
+	/**
+	* Original resource object (RXR from @resourcexjs/core).
+	*/
+	resource: unknown;
+	/**
+	* Execute function to get the resource content.
+	* - For static resources (text/json/binary): call with no arguments
+	* - For dynamic resources (tool): call with arguments
+	*/
+	execute: (args?: TArgs) => TResult | Promise<TResult>;
+	/**
+	* JSON Schema for the arguments (undefined if no arguments needed).
+	* UI uses this to render parameter forms.
+	*/
+	schema: TArgs extends void ? undefined : JSONSchema;
+}
+/**
+* ResourceResolver - Transforms resource into a structured result object.
+* The execute function is lazy-loaded: content is only read when called.
+*/
+interface ResourceResolver<
+	TArgs = void,
+	TResult = unknown
+> {
+	/**
+	* JSON Schema for arguments (required if TArgs is not void).
+	* This constraint ensures type safety at definition time.
+	*/
+	schema: TArgs extends void ? undefined : JSONSchema;
+	/**
+	* Resolve resource into a structured result object.
+	* @param rxr - RXR object from @resourcexjs/core
+	*/
+	resolve(rxr: unknown): Promise<ResolvedResource<TArgs, TResult>>;
+}
+/**
+* ResourceType - Defines how a resource type is handled.
+*/
+interface ResourceType<
+	TArgs = void,
+	TResult = unknown
+> {
+	/**
+	* Type name (e.g., "text", "json", "binary").
+	*/
+	name: string;
+	/**
+	* Alternative names for this type (e.g., ["txt", "plaintext"]).
+	*/
+	aliases?: string[];
+	/**
+	* Human-readable description.
+	*/
+	description: string;
+	/**
+	* Resolver to transform RXR into structured result object.
+	*/
+	resolver: ResourceResolver<TArgs, TResult>;
+}
+/**
+* Bundle a resource type from a source file.
+*
+* @param sourcePath - Path to the .type.ts file
+* @param basePath - Base path for resolving relative paths (defaults to cwd)
+* @returns BundledType ready for registry
+*
+* @example
+* ```typescript
+* const promptType = await bundleResourceType("./prompt.type.ts");
+* ```
+*/
+declare function bundleResourceType(sourcePath: string, basePath?: string): Promise<BundledType>;
+/**
+* Resource type related error.
+*/
+declare class ResourceTypeError extends ResourceXError {
+	constructor(message: string);
+}
+/**
+* TypeHandlerChain - Manages resource type registration.
+*
+* Responsibilities:
+* - Register types (name + aliases)
+* - Look up types by name
+*
+* Execution is delegated to ResolverExecutor (in registry package).
+*
+* Built-in types (text, json, binary) are registered by default.
+*/
+declare class TypeHandlerChain {
+	private handlers;
+	private constructor();
+	/**
+	* Create a new TypeHandlerChain instance.
+	* Built-in types (text, json, binary) are included by default.
+	*/
+	static create(): TypeHandlerChain;
+	/**
+	* Internal registration (no duplicate check).
+	*/
+	private registerInternal;
+	/**
+	* Register a type.
+	* @throws ResourceTypeError if type is already registered
+	*/
+	register(type: BundledType): void;
+	/**
+	* Check if a type is supported.
+	*/
+	canHandle(typeName: string): boolean;
+	/**
+	* Get handler for a type.
+	* @throws ResourceTypeError if type is not supported
+	*/
+	getHandler(typeName: string): BundledType;
+	/**
+	* Get handler for a type, or undefined if not found.
+	*/
+	getHandlerOrUndefined(typeName: string): BundledType | undefined;
+	/**
+	* Get all supported type names (including aliases).
+	*/
+	getSupportedTypes(): string[];
+	/**
+	* Clear all registered types (for testing).
+	*/
+	clear(): void;
+}
+/**
+* Plain text content
+*/
+declare const textType: BundledType;
+/**
+* JSON content
+*/
+declare const jsonType: BundledType;
+/**
+* Binary content
+*/
+declare const binaryType: BundledType;
+/**
+* All built-in types as an array.
+*/
+declare const builtinTypes: BundledType[];
+/**
+* ResourceLoader - Strategy interface for loading resources from different sources.
+*/
+interface ResourceLoader {
+	/**
+	* Check if this loader can handle the given source.
+	*
+	* @param source - Source path or identifier
+	* @returns true if this loader can handle the source
+	*/
+	canLoad(source: string): boolean | Promise<boolean>;
+	/**
+	* Load a resource from the given source.
+	*
+	* @param source - Source path or identifier
+	* @returns Complete RXR object
+	* @throws ResourceXError if loading fails
+	*/
+	load(source: string): Promise<RXR>;
+}
+/**
+* Default ResourceLoader implementation for loading resources from folders.
+*
+* Expected folder structure:
+* ```
+* folder/
+* ├── resource.json    # Resource metadata (required)
+* └── ...              # Any other files/directories (content)
+* ```
+*
+* resource.json format:
+* ```json
+* {
+*   "name": "resource-name",      // required
+*   "type": "text",               // required
+*   "version": "1.0.0",           // required
+*   "domain": "localhost",        // optional, defaults to "localhost"
+*   "path": "optional/path"       // optional
+* }
+* ```
+*
+* All files in the folder (except resource.json) will be packaged into the RXA.
+*/
+declare class FolderLoader implements ResourceLoader {
+	canLoad(source: string): Promise<boolean>;
+	load(folderPath: string): Promise<RXR>;
+	/**
+	* Recursively read all files in a folder, returning a map of relative paths to buffers.
+	*/
+	private readFolderFiles;
+}
+/**
+* Configuration options for loadResource.
+*/
+interface LoadResourceConfig {
+	/**
+	* Custom loader to use. If not provided, defaults to FolderLoader.
+	*/
+	loader?: ResourceLoader;
+}
+/**
+* Load a resource from a given source using a ResourceLoader.
+*
+* By default, uses FolderLoader which expects:
+* ```
+* folder/
+* ├── resource.json    # Resource metadata
+* └── content          # Resource content
+* ```
+*
+* You can provide a custom loader via config.loader to support other formats
+* (e.g., zip, tar.gz, URLs).
+*
+* @param source - Source path or identifier
+* @param config - Optional configuration
+* @returns Complete RXR object ready for registry.link()
+* @throws ResourceXError if the source cannot be loaded
+*
+* @example
+* ```typescript
+* // Load from folder (default)
+* const rxr = await loadResource("./my-resource");
+* await registry.link(rxr);
+*
+* // Load with custom loader
+* const rxr = await loadResource("resource.zip", {
+*   loader: new ZipLoader()
+* });
+* ```
+*/
+declare function loadResource(source: string, config?: LoadResourceConfig): Promise<RXR>;
+/**
+* Search options for querying resources.
+*/
+interface SearchOptions {
+	/**
+	* Search query string (matches against name, domain, path).
+	*/
+	query?: string;
+	/**
+	* Maximum number of results to return.
+	*/
+	limit?: number;
+	/**
+	* Number of results to skip (for pagination).
+	*/
+	offset?: number;
+}
+/**
+* Registry interface - business layer for RXR operations.
+*
+* This interface defines CRUD operations on RXR objects.
+* Different implementations (HostedRegistry, MirrorRegistry, LinkedRegistry)
+* provide different semantics on top of the same Storage layer.
+*/
+interface Registry {
+	/**
+	* Get resource by locator.
+	* @throws RegistryError if not found
+	*/
+	get(rxl: RXL): Promise<RXR>;
+	/**
+	* Store resource.
+	*/
+	put(rxr: RXR): Promise<void>;
+	/**
+	* Check if resource exists.
+	*/
+	has(rxl: RXL): Promise<boolean>;
+	/**
+	* Delete resource.
+	*/
+	remove(rxl: RXL): Promise<void>;
+	/**
+	* List resources matching options.
+	*/
+	list(options?: SearchOptions): Promise<RXL[]>;
+}
+/**
+* RXAStore - Content-Addressable Storage for Resource Archives
+*
+* SPI interface for storing file content by digest (hash).
+* Platform implementations provide concrete storage backends
+* (FileSystem, S3, R2, Memory, etc.)
+*/
+interface RXAStore {
+	/**
+	* Get content by digest.
+	* @throws if not found
+	*/
+	get(digest: string): Promise<Buffer>;
+	/**
+	* Store content, returns digest.
+	* If content with same digest exists, skips write (deduplication).
+	*/
+	put(data: Buffer): Promise<string>;
+	/**
+	* Check if digest exists.
+	*/
+	has(digest: string): Promise<boolean>;
+	/**
+	* Delete content by digest (for GC).
+	*/
+	delete(digest: string): Promise<void>;
+	/**
+	* List all digests (for GC).
+	*/
+	list(): Promise<string[]>;
+}
+/**
+* RXMStore - Manifest Storage
+*
+* SPI interface for storing resource manifests.
+* Platform implementations provide concrete storage backends
+* (SQLite, PostgreSQL, FileSystem, Memory, etc.)
+*/
+/**
+* Stored manifest with file digest mappings.
+*/
+interface StoredRXM {
+	readonly registry?: string;
+	readonly path?: string;
+	readonly name: string;
+	readonly type: string;
+	readonly tag: string;
+	readonly files: Record<string, string>;
+	readonly createdAt?: Date;
+	readonly updatedAt?: Date;
+}
+/**
+* Search options for RXMStore.
+*/
+interface RXMSearchOptions {
+	/**
+	* Filter by registry.
+	* - undefined: all
+	* - null: local only (no registry)
+	* - string: specific registry
+	*/
+	registry?: string | null;
+	/**
+	* Search query (matches name).
+	*/
+	query?: string;
+	/**
+	* Maximum results.
+	*/
+	limit?: number;
+	/**
+	* Skip results (pagination).
+	*/
+	offset?: number;
+}
+interface RXMStore {
+	/**
+	* Get manifest.
+	* @returns null if not found
+	*/
+	get(name: string, tag: string, registry?: string): Promise<StoredRXM | null>;
+	/**
+	* Store manifest.
+	*/
+	put(manifest: StoredRXM): Promise<void>;
+	/**
+	* Check if manifest exists.
+	*/
+	has(name: string, tag: string, registry?: string): Promise<boolean>;
+	/**
+	* Delete manifest.
+	*/
+	delete(name: string, tag: string, registry?: string): Promise<void>;
+	/**
+	* List all tags for a resource.
+	*/
+	listTags(name: string, registry?: string): Promise<string[]>;
+	/**
+	* List all resource names.
+	*/
+	listNames(registry?: string, query?: string): Promise<string[]>;
+	/**
+	* Search manifests.
+	*/
+	search(options?: RXMSearchOptions): Promise<StoredRXM[]>;
+	/**
+	* Delete all manifests from a registry (clear cache).
+	*/
+	deleteByRegistry(registry: string): Promise<void>;
+}
+declare class CASRegistry implements Registry {
+	private readonly rxaStore;
+	private readonly rxmStore;
+	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
+	get(rxl: RXL): Promise<RXR>;
+	put(rxr: RXR): Promise<void>;
+	has(rxl: RXL): Promise<boolean>;
+	remove(rxl: RXL): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL[]>;
+	/**
+	* Clear cached resources (resources with registry).
+	* @param registry - If provided, only clear resources from this registry
+	*/
+	clearCache(registry?: string): Promise<void>;
+	/**
+	* Run garbage collection to remove orphaned blobs.
+	*/
+	gc(): Promise<number>;
+	/**
+	* Check if a digest exists in the blob store.
+	* Useful for "instant upload" - skip uploading if server already has it.
+	*/
+	hasBlob(digest: string): Promise<boolean>;
+	/**
+	* Get blob by digest.
+	*/
+	getBlob(digest: string): Promise<Buffer>;
+	/**
+	* Put blob directly (for pull optimization).
+	*/
+	putBlob(data: Buffer): Promise<string>;
+}
+/**
+* LinkedRegistry - Registry for development symlinks.
+*
+* Creates symlinks to development directories so changes are reflected immediately.
+* Unlike HostedRegistry/MirrorRegistry, it doesn't use Storage layer directly.
+* Instead, it manages symlinks in a base directory.
+*
+* Storage structure:
+*   {basePath}/{registry}/{path}/{name}/{tag} → /path/to/dev/folder
+*/
+declare class LinkedRegistry implements Registry {
+	private readonly basePath;
+	constructor(basePath: string);
+	/**
+	* Build symlink path for a resource.
+	*/
+	private buildLinkPath;
+	/**
+	* Check if a path is a symlink.
+	*/
+	private isSymlink;
+	get(rxl: RXL): Promise<RXR>;
+	/**
+	* Put is not typically used for LinkedRegistry.
+	* Use link() instead to create symlinks.
+	*/
+	put(_rxr: RXR): Promise<void>;
+	has(rxl: RXL): Promise<boolean>;
+	remove(rxl: RXL): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL[]>;
+	/**
+	* Link a development directory.
+	* Creates a symlink so changes are reflected immediately.
+	*
+	* @param devPath - Path to development directory (must contain resource.json)
+	* @returns The RXL of the linked resource
+	*/
+	link(devPath: string): Promise<RXL>;
+	/**
+	* Unlink a development directory.
+	* Alias for remove().
+	*/
+	unlink(rxl: RXL): Promise<void>;
+	/**
+	* Recursively scan for symlinks.
+	*/
+	private scanSymlinks;
+	/**
+	* Parse relative path to RXL.
+	* Path format: {registry}/{path}/{name}/{tag}
+	*/
+	private parsePathToRXL;
+}
+/**
+* Compute SHA-256 digest of data.
+* Returns string in format "sha256:{hex}"
+*/
+declare function computeDigest(data: Buffer): string;
+/**
+* Validate digest format.
+*/
+declare function isValidDigest(digest: string): boolean;
+declare class MemoryRXAStore implements RXAStore {
+	private readonly blobs;
+	get(digest: string): Promise<Buffer>;
+	put(data: Buffer): Promise<string>;
+	has(digest: string): Promise<boolean>;
+	delete(digest: string): Promise<void>;
+	list(): Promise<string[]>;
+	/**
+	* Clear all blobs (for testing).
+	*/
+	clear(): void;
+}
+declare class MemoryRXMStore implements RXMStore {
+	private readonly manifests;
+	/**
+	* Build key for manifest lookup.
+	*/
+	private buildKey;
+	get(name: string, tag: string, registry?: string): Promise<StoredRXM | null>;
+	put(manifest: StoredRXM): Promise<void>;
+	has(name: string, tag: string, registry?: string): Promise<boolean>;
+	delete(name: string, tag: string, registry?: string): Promise<void>;
+	listTags(name: string, registry?: string): Promise<string[]>;
+	listNames(registry?: string, query?: string): Promise<string[]>;
+	search(options?: RXMSearchOptions): Promise<StoredRXM[]>;
+	deleteByRegistry(registry: string): Promise<void>;
+	/**
+	* Clear all manifests (for testing).
+	*/
+	clear(): void;
+}
+/**
+* Well-known discovery response format.
+*/
+interface WellKnownResponse {
+	version?: string;
+	registries: string[];
+}
+/**
+* Result from discoverRegistry().
+*/
+interface DiscoveryResult {
+	domain: string;
+	registries: string[];
+}
+/**
+* Discover registry for a domain using well-known.
+* @param domain - The domain to discover (e.g., "deepractice.ai")
+* @returns Discovery result with domain and authorized registries
+*/
+declare function discoverRegistry(domain: string): Promise<DiscoveryResult>;
+/**
+* Registry-specific error.
+*/
+declare class RegistryError extends ResourceXError {
+	constructor(message: string, options?: ErrorOptions);
+}
+/**
+* Base class for Registry middleware.
+* Delegates all operations to the inner registry.
+* Override specific methods to add custom behavior.
+*/
+declare abstract class RegistryMiddleware implements Registry {
+	protected readonly inner: Registry;
+	constructor(inner: Registry);
+	get(rxl: RXL): Promise<RXR>;
+	put(rxr: RXR): Promise<void>;
+	has(rxl: RXL): Promise<boolean>;
+	remove(rxl: RXL): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL[]>;
+}
+/**
+* Registry validation middleware.
+* Ensures all resources from this registry match the trusted registry.
+*/
+declare class RegistryValidation extends RegistryMiddleware {
+	private readonly trustedRegistry;
+	constructor(inner: Registry, trustedRegistry: string);
+	/**
+	* Validate that manifest registry matches trusted registry.
+	*/
+	private validateRegistry;
+	/**
+	* Get resource and validate registry.
+	*/
+	get(rxl: RXL): Promise<RXR>;
+}
+/**
+* Factory function to create registry validation middleware.
+*
+* @example
+* const registry = withRegistryValidation(hostedRegistry, "deepractice.ai");
+*/
+declare function withRegistryValidation(registry: Registry, trustedRegistry: string): Registry;
+declare const DomainValidation: typeof RegistryValidation;
+declare const withDomainValidation: typeof withRegistryValidation;
+/**
+* Provider configuration passed to createStores/createLoader.
+*/
+interface ProviderConfig {
+	/**
+	* Base path for storage (filesystem) or connection info.
+	*/
+	path?: string;
+	/**
+	* Platform-specific configuration.
+	*/
+	[key: string]: unknown;
+}
+/**
+* Stores created by the provider.
+*/
+interface ProviderStores {
+	rxaStore: RXAStore;
+	rxmStore: RXMStore;
+}
+/**
+* Resource loader interface for loading from directories/archives.
+*/
+interface ResourceLoader2 {
+	/**
+	* Check if this loader can handle the given source.
+	*/
+	canLoad(source: string): boolean | Promise<boolean>;
+	/**
+	* Load resource from source.
+	*/
+	load(source: string): Promise<unknown>;
+}
+/**
+* ResourceX Provider - Platform implementation interface.
+*
+* Platforms implement this interface to provide storage and loading
+* capabilities for their environment.
+*/
+interface ResourceXProvider {
+	/**
+	* Platform identifier.
+	*/
+	readonly platform: string;
+	/**
+	* Create storage instances for the platform.
+	*/
+	createStores(config: ProviderConfig): ProviderStores;
+	/**
+	* Create resource loader (optional).
+	* Not all platforms support loading from filesystem.
+	*/
+	createLoader?(config: ProviderConfig): ResourceLoader2;
+}
+export { wrap, withDomainValidation, textType, resource, parse, manifest, locate, loadResource, jsonType, isValidDigest, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, StoredRXM, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResolvedResource, ResolveContext, RegistryMiddleware, RegistryError, Registry, RXR, RXMStore, RXMSearchOptions, RXM, RXL, RXD, RXAStore, RXA, ProviderStores, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, FolderLoader, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };