@resourcexjs/registry 2.2.0 → 2.4.0

package/dist/index.d.ts

@@ -1,84 +1,6 @@
+import { RXR as RXR3, RXL as RXL3 } from "@resourcexjs/core";
+import { BundledType, ResolvedResource, IsolatorType } from "@resourcexjs/type";
 import { RXR, RXL } from "@resourcexjs/core";
-import { ResourceType, ResolvedResource } from "@resourcexjs/type";
-/**
-* Local registry configuration.
-* Uses filesystem for storage.
-*/
-interface LocalRegistryConfig {
-	/**
-	* Local storage path. Defaults to ~/.resourcex
-	*/
-	path?: string;
-	/**
-	* Supported resource types.
-	* If not provided, defaults to built-in types (text, json, binary).
-	*/
-	types?: ResourceType[];
-}
-/**
-* Remote registry configuration.
-* Uses HTTP API for access.
-*/
-interface RemoteRegistryConfig {
-	/**
-	* Remote registry API endpoint.
-	* Example: "https://registry.deepractice.ai/v1"
-	*/
-	endpoint: string;
-}
-/**
-* Git registry configuration.
-* Uses git clone to fetch registry content.
-*/
-interface GitRegistryConfig {
-	type: "git";
-	/** Git repository URL (SSH format: git@github.com:owner/repo.git) */
-	url: string;
-	/** Git ref (branch, tag, or commit). Default: "main" */
-	ref?: string;
-	/** Base path in repo for resources. Default: ".resourcex" */
-	basePath?: string;
-	/**
-	* Trusted domain for this registry.
-	* If set, only resources with this domain in manifest are allowed.
-	* Required for security - prevents untrusted registries from claiming any domain.
-	*/
-	domain?: string;
-}
-/**
-* Well-known discovery response format.
-* Used by discoverRegistry() to find registry for a domain.
-*/
-interface WellKnownResponse {
-	version: string;
-	/**
-	* List of registry URLs (git or http).
-	* First one is primary, rest are fallbacks (for future use).
-	*/
-	registries: string[];
-}
-/**
-* Result from discoverRegistry().
-* Contains domain and its authorized registries.
-*/
-interface DiscoveryResult {
-	/** The domain that was discovered */
-	domain: string;
-	/** Authorized registry URLs for this domain */
-	registries: string[];
-}
-/**
-* Registry configuration - local, remote, or git.
-*/
-type RegistryConfig = LocalRegistryConfig | RemoteRegistryConfig | GitRegistryConfig;
-/**
-* Type guard to check if config is for remote registry.
-*/
-declare function isRemoteConfig(config?: RegistryConfig): config is RemoteRegistryConfig;
-/**
-* Type guard to check if config is for git registry.
-*/
-declare function isGitConfig(config?: RegistryConfig): config is GitRegistryConfig;
 /**
 * Search options for querying resources.
 */
@@ -97,291 +19,332 @@ interface SearchOptions {
 	offset?: number;
 }
 /**
-* Options for pulling resources from remote registry.
-*/
-interface PullOptions {
-	/**
-	* Pull from a specific registry instead of auto-discovering.
-	*/
-	from?: Registry;
-}
-/**
-* Target configuration for publishing resources.
-*/
-interface PublishTarget {
-	type: "http" | "git";
-	/** HTTP endpoint (for type: "http") */
-	endpoint?: string;
-	/** Git repository URL (for type: "git") */
-	url?: string;
-	/** Git ref - branch/tag (for type: "git"). Default: "main" */
-	ref?: string;
-}
-/**
-* Options for publishing resources to remote registry.
-*/
-interface PublishOptions {
-	/**
-	* Target registry configuration.
-	*/
-	to: PublishTarget;
-}
-/**
-* Registry interface for resource storage and retrieval.
+* Storage interface - pure storage abstraction.
+* Handles CRUD operations for resources.
+*
+* Different implementations:
+* - LocalStorage: filesystem, read-write
+* - GitStorage: git clone, read-only
+* - HttpStorage: HTTP API, typically read-only
 */
-interface Registry {
-	/**
-	* Add support for a custom resource type.
-	* @param type - The resource type to support
-	*/
-	supportType(type: ResourceType): void;
-	/**
-	* Link a development directory to local registry.
-	* Creates a symlink so changes are reflected immediately.
-	* @param path - Path to resource directory (must contain resource.json)
-	*/
-	link(path: string): Promise<void>;
-	/**
-	* Add resource to local registry.
-	* Copies resource content to local storage.
-	* @param source - Resource directory path or RXR object
-	*/
-	add(source: string | RXR): Promise<void>;
+interface Storage {
 	/**
-	* Pull resource from remote registry to local cache.
-	* Discovers remote registry via well-known and caches locally.
-	* @param locator - Resource locator (must include domain)
-	* @param options - Pull options
+	* Storage type identifier.
 	*/
-	pull(locator: string, options?: PullOptions): Promise<void>;
+	readonly type: string;
 	/**
-	* Publish resource to remote registry.
-	* @param source - Resource directory path or RXR object
-	* @param options - Publish target configuration (required)
-	*/
-	publish(source: string | RXR, options: PublishOptions): Promise<void>;
-	/**
-	* Get raw resource by locator string.
-	* Returns the RXR (locator + manifest + content) without resolving.
-	* Use this when you need access to raw resource content.
+	* Get resource by locator.
+	* @throws RegistryError if not found
 	*/
 	get(locator: string): Promise<RXR>;
 	/**
-	* Resolve resource by locator string.
-	* Returns a ResolvedResource with execute function and original resource.
-	* Checks local first, then fetches from remote if not found.
+	* Store a resource.
+	* @throws RegistryError if storage is read-only
 	*/
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource<TArgs, TResult>>;
+	put(rxr: RXR): Promise<void>;
 	/**
 	* Check if resource exists.
 	*/
 	exists(locator: string): Promise<boolean>;
 	/**
-	* Delete resource from local registry.
+	* Delete a resource.
+	* @throws RegistryError if storage is read-only
 	*/
 	delete(locator: string): Promise<void>;
 	/**
-	* Search for resources matching options.
-	* @param options - Search options (query, limit, offset)
-	* @returns Array of matching resource locators
+	* Search for resources.
 	*/
 	search(options?: SearchOptions): Promise<RXL[]>;
 }
-import { ResourceXError } from "@resourcexjs/core";
+import { RXR as RXR2, RXL as RXL2 } from "@resourcexjs/core";
 /**
-* Registry-specific error.
+* LocalStorage configuration.
 */
-declare class RegistryError extends ResourceXError {
-	constructor(message: string, options?: ErrorOptions);
+interface LocalStorageConfig {
+	/**
+	* Base path for storage. Defaults to ~/.resourcex
+	*/
+	path?: string;
 }
-import { RXR as RXR2, RXL as RXL2 } from "@resourcexjs/core";
-import { ResourceType as ResourceType2, ResolvedResource as ResolvedResource2 } from "@resourcexjs/type";
 /**
-* Local filesystem-based registry implementation.
+* Local filesystem storage implementation.
 * Uses ARP file transport for I/O operations.
+*
+* Storage structure:
+* - {basePath}/{domain}/{path}/{name}.{type}/{version}/
+*   - manifest.json
+*   - archive.tar.gz
+*
+* For localhost/no-domain resources:
+* - {basePath}/localhost/{name}.{type}/{version}/
 */
-declare class LocalRegistry implements Registry {
+declare class LocalStorage implements Storage {
+	readonly type = "local";
 	private readonly basePath;
-	private readonly typeHandler;
 	private readonly arp;
-	constructor(config?: LocalRegistryConfig);
-	supportType(type: ResourceType2): void;
+	constructor(config?: LocalStorageConfig);
 	/**
 	* Create ARP URL for a file path.
 	*/
 	private toArpUrl;
 	/**
 	* Build filesystem path for a resource.
-	*
-	* Storage structure:
-	* - local: {basePath}/local/{name}.{type}/{version}
-	* - cache: {basePath}/cache/{domain}/{path}/{name}.{type}/{version}
-	*
-	* @param locator - Resource locator
-	* @param area - Storage area ("local" or "cache")
+	* Path: {basePath}/{domain}/{path}/{name}.{type}/{version}
 	*/
 	private buildPath;
 	/**
-	* Determine if a locator refers to a local-only resource (no domain or localhost).
-	*/
-	private isLocalOnlyLocator;
-	/**
 	* Check if a resource exists at a specific path.
+	* Handles both regular storage (manifest.json) and symlinked dev directories (resource.json).
 	*/
 	private existsAt;
 	/**
-	* Find which area a resource exists in.
-	* Returns the area ("local" or "cache") or null if not found.
-	*/
-	private findArea;
-	/**
 	* Check if a path is a symlink.
 	*/
 	private isSymlink;
 	/**
 	* Load resource from a specific path.
-	* If path is a symlink, loads from the linked directory using FolderLoader.
+	* If path is a symlink, loads from the linked directory.
 	*/
 	private loadFrom;
-	link(path: string): Promise<void>;
-	add(source: string | RXR2): Promise<void>;
-	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_source: string | RXR2, _options: PublishOptions): Promise<void>;
 	get(locator: string): Promise<RXR2>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource2<TArgs, TResult>>;
+	put(rxr: RXR2): Promise<void>;
 	exists(locator: string): Promise<boolean>;
 	delete(locator: string): Promise<void>;
 	search(options?: SearchOptions): Promise<RXL2[]>;
 	/**
-	* Parse a local entry path to RXL.
-	* Entry format: {name}.{type}/{version}/manifest.json
+	* Link a development directory.
+	* Creates a symlink so changes are reflected immediately.
 	*/
-	private parseLocalEntry;
+	link(path: string): Promise<void>;
 	/**
-	* Parse a cache entry path to RXL.
+	* Parse entry path to RXL.
 	* Entry format: {domain}/{path}/{name}.{type}/{version}/manifest.json
 	*/
-	private parseCacheEntry;
+	private parseEntryToRXL;
+}
+/**
+* Registry configuration.
+*/
+interface RegistryConfig {
 	/**
-	* Parse name and type from a combined string like "name.type" or "name".
+	* Storage backend. Defaults to LocalStorage.
 	*/
-	private parseNameType;
+	storage?: Storage;
+	/**
+	* Mirror URL for remote fetch (client mode).
+	* If configured, tries mirror before well-known discovery.
+	*/
+	mirror?: string;
+	/**
+	* Additional custom resource types to support.
+	* Built-in types (text, json, binary) are always included by default.
+	*/
+	types?: BundledType[];
+	/**
+	* Isolator type for resolver execution (SandboX).
+	* - "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)
+	*/
+	isolator?: IsolatorType;
 }
-import { RXR as RXR3, RXL as RXL3 } from "@resourcexjs/core";
-import { ResourceType as ResourceType3, ResolvedResource as ResolvedResource3 } from "@resourcexjs/type";
 /**
-* Remote registry implementation.
-* Uses HTTP API for resource access.
+* Registry interface for resource management.
 */
-declare class RemoteRegistry implements Registry {
-	private readonly endpoint;
-	private readonly typeHandler;
-	constructor(config: RemoteRegistryConfig);
-	supportType(type: ResourceType3): void;
-	link(_path: string): Promise<void>;
-	add(_source: string | RXR3): Promise<void>;
-	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_source: string | RXR3, _options: PublishOptions): Promise<void>;
+interface Registry {
+	/**
+	* Add support for a custom resource type.
+	*/
+	supportType(type: BundledType): void;
+	/**
+	* Link a development directory.
+	* Creates a symlink so changes are reflected immediately.
+	* Only supported by LocalStorage.
+	*/
+	link(path: string): Promise<void>;
+	/**
+	* Add resource to storage.
+	* @param source - Resource directory path or RXR object
+	*/
+	add(source: string | RXR3): Promise<void>;
+	/**
+	* Get raw resource by locator.
+	*
+	* Flow:
+	* - localhost: Only queries local storage
+	* - Other domains: Local cache -> [Mirror] -> Source (well-known)
+	*/
 	get(locator: string): Promise<RXR3>;
+	/**
+	* Resolve resource by locator.
+	* Returns ResolvedResource with execute function.
+	*/
 	resolve<
 		TArgs = void,
 		TResult = unknown
-	>(locator: string): Promise<ResolvedResource3<TArgs, TResult>>;
+	>(locator: string): Promise<ResolvedResource<TArgs, TResult>>;
+	/**
+	* Check if resource exists.
+	*/
 	exists(locator: string): Promise<boolean>;
-	delete(_locator: string): Promise<void>;
+	/**
+	* Delete resource from storage.
+	*/
+	delete(locator: string): Promise<void>;
+	/**
+	* Search for resources.
+	*/
 	search(options?: SearchOptions): Promise<RXL3[]>;
 }
 /**
-* 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
+* Default Registry implementation.
+*
+* Combines Storage (for CRUD) with TypeHandlerChain (for type resolution).
+* Supports remote fetch for non-localhost domains.
 */
-declare function discoverRegistry(domain: string): Promise<DiscoveryResult>;
-import { RXR as RXR4, RXL as RXL4 } from "@resourcexjs/core";
-import { ResourceType as ResourceType4, ResolvedResource as ResolvedResource4 } from "@resourcexjs/type";
-declare class GitRegistry implements Registry {
-	private readonly url;
-	private readonly ref;
-	private readonly basePath;
-	private readonly cacheDir;
+declare class DefaultRegistry implements Registry {
+	private readonly storage;
+	private readonly mirror?;
 	private readonly typeHandler;
-	private readonly arp;
-	private readonly isLocal;
-	constructor(config: GitRegistryConfig);
+	private readonly executor;
+	private readonly discoveryCache;
+	constructor(config?: RegistryConfig);
+	supportType(type: BundledType): void;
+	link(path: string): Promise<void>;
+	add(source: string | RXR3): Promise<void>;
+	get(locator: string): Promise<RXR3>;
+	resolve<
+		TArgs = void,
+		TResult = unknown
+	>(locator: string): Promise<ResolvedResource<TArgs, TResult>>;
+	exists(locator: string): Promise<boolean>;
+	delete(locator: string): Promise<void>;
+	search(options?: SearchOptions): Promise<RXL3[]>;
 	/**
-	* Build cache directory name from git URL.
-	* git@github.com:Deepractice/Registry.git → github.com-Deepractice-Registry
+	* Fetch resource from remote.
+	* Flow: Mirror (if configured) -> Source (well-known)
 	*/
-	private buildCacheDir;
-	supportType(type: ResourceType4): void;
+	private fetchRemote;
 	/**
-	* Create ARP URL for a file path.
+	* Discover registry endpoint for a domain via well-known.
 	*/
-	private toArpUrl;
+	private discoverEndpoint;
 	/**
-	* Ensure the repository is cloned and up to date.
-	* For local paths, just verify the .git directory exists.
-	* For remote URLs, includes retry logic for transient network errors.
+	* Fetch resource from a specific endpoint via HTTP API.
 	*/
-	private ensureCloned;
+	private fetchFromEndpoint;
+}
+import { BundledType as BundledType2, IsolatorType as IsolatorType2 } from "@resourcexjs/type";
+/**
+* Client registry configuration.
+* Uses LocalStorage as cache, optionally fetches from remote via mirror or well-known.
+*/
+interface ClientRegistryConfig {
 	/**
-	* Get the default branch name (main or master).
+	* Local cache path. Defaults to ~/.resourcex
 	*/
-	private getDefaultBranch;
+	path?: string;
 	/**
-	* Build filesystem path for a resource in the cloned repo.
-	* Path structure: {cacheDir}/{basePath}/{domain}/{path}/{name}.{type}/{version}
+	* Mirror URL for remote fetch.
+	* If configured, tries mirror before well-known discovery.
 	*/
-	private buildResourcePath;
-	get(locator: string): Promise<RXR4>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource4<TArgs, TResult>>;
-	exists(locator: string): Promise<boolean>;
-	search(options?: SearchOptions): Promise<RXL4[]>;
-	private parseEntryToRXL;
-	link(_path: string): Promise<void>;
-	add(_source: string | RXR4): Promise<void>;
-	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_source: string | RXR4, _options: PublishOptions): Promise<void>;
-	delete(_locator: string): Promise<void>;
+	mirror?: string;
+	/**
+	* Additional custom resource types.
+	* Built-in types (text, json, binary) are always included.
+	*/
+	types?: BundledType2[];
+	/**
+	* Isolator type for resolver execution.
+	* Defaults to "none".
+	*/
+	isolator?: IsolatorType2;
+}
+/**
+* Server registry configuration.
+* Uses custom Storage implementation.
+*/
+interface ServerRegistryConfig {
+	/**
+	* Custom storage implementation.
+	* Example: new LocalStorage({ path: "..." })
+	*/
+	storage: Storage;
+	/**
+	* Additional custom resource types.
+	* Built-in types (text, json, binary) are always included.
+	*/
+	types?: BundledType2[];
+	/**
+	* Isolator type for resolver execution.
+	* Defaults to "none".
+	*/
+	isolator?: IsolatorType2;
 }
 /**
+* All supported registry configurations.
+*/
+type CreateRegistryConfig = ClientRegistryConfig | ServerRegistryConfig;
+/**
 * Create a registry instance.
 *
-* When a `domain` is provided in GitRegistryConfig, the registry is automatically
-* wrapped with DomainValidation middleware for security.
+* Built-in types (text, json, binary) are always included by default.
 *
-* @param config - Registry configuration
-*   - No config or LocalRegistryConfig: Creates LocalRegistry (filesystem-based)
-*   - RemoteRegistryConfig: Creates RemoteRegistry (HTTP-based)
-*   - GitRegistryConfig: Creates GitRegistry (git clone-based)
+* Two modes:
+* 1. Client mode (default): Uses LocalStorage as cache, fetches from remote when cache miss
+* 2. Server mode: Uses custom Storage implementation
 *
 * @example
-* // Local registry (default)
+* // Simple usage - builtin types included
 * const registry = createRegistry();
-* const registry2 = createRegistry({ path: "./custom-path" });
 *
-* // Remote registry
-* const registry3 = createRegistry({ endpoint: "https://registry.deepractice.ai/v1" });
+* @example
+* // With custom types
+* const registry = createRegistry({ types: [myPromptType] });
 *
-* // Git registry (requires domain for remote URLs)
-* const registry4 = createRegistry({
-*   type: "git",
-*   url: "git@github.com:Deepractice/Registry.git",
-*   domain: "deepractice.ai",  // Auto-wrapped with DomainValidation
+* @example
+* // With isolator (SandboX)
+* const registry = createRegistry({
+*   isolator: "srt",  // or "none", "cloudflare", "e2b"
+* });
+*
+* @example
+* // Server mode - custom storage
+* const registry = createRegistry({
+*   storage: new LocalStorage({ path: "./data" }),
 * });
 */
-declare function createRegistry(config?: RegistryConfig): Registry;
-import { RXR as RXR5, RXL as RXL5 } from "@resourcexjs/core";
-import { ResourceType as ResourceType5, ResolvedResource as ResolvedResource5 } from "@resourcexjs/type";
+declare function createRegistry(config?: CreateRegistryConfig): Registry;
+/**
+* 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>;
+import { ResourceXError } from "@resourcexjs/core";
+/**
+* Registry-specific error.
+*/
+declare class RegistryError extends ResourceXError {
+	constructor(message: string, options?: ErrorOptions);
+}
+import { RXR as RXR4, RXL as RXL4 } from "@resourcexjs/core";
+import { BundledType as BundledType3, ResolvedResource as ResolvedResource2 } from "@resourcexjs/type";
 /**
 * Base class for Registry middleware.
 * Delegates all operations to the inner registry.
@@ -390,22 +353,20 @@ import { ResourceType as ResourceType5, ResolvedResource as ResolvedResource5 }
 declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
-	supportType(type: ResourceType5): void;
+	supportType(type: BundledType3): void;
 	link(path: string): Promise<void>;
-	add(source: string | RXR5): Promise<void>;
-	pull(locator: string, options?: PullOptions): Promise<void>;
-	publish(source: string | RXR5, options: PublishOptions): Promise<void>;
-	get(locator: string): Promise<RXR5>;
+	add(source: string | RXR4): Promise<void>;
+	get(locator: string): Promise<RXR4>;
 	resolve<
 		TArgs = void,
 		TResult = unknown
-	>(locator: string): Promise<ResolvedResource5<TArgs, TResult>>;
+	>(locator: string): Promise<ResolvedResource2<TArgs, TResult>>;
 	exists(locator: string): Promise<boolean>;
 	delete(locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL5[]>;
+	search(options?: SearchOptions): Promise<RXL4[]>;
 }
-import { RXR as RXR6 } from "@resourcexjs/core";
-import { ResolvedResource as ResolvedResource6 } from "@resourcexjs/type";
+import { RXR as RXR5 } from "@resourcexjs/core";
+import { ResolvedResource as ResolvedResource3 } from "@resourcexjs/type";
 /**
 * Domain validation middleware.
 * Ensures all resources from this registry match the trusted domain.
@@ -420,14 +381,14 @@ declare class DomainValidation extends RegistryMiddleware {
 	/**
 	* Get resource and validate domain.
 	*/
-	get(locator: string): Promise<RXR6>;
+	get(locator: string): Promise<RXR5>;
 	/**
 	* Resolve resource and validate domain.
 	*/
 	resolve<
 		TArgs = void,
 		TResult = unknown
-	>(locator: string): Promise<ResolvedResource6<TArgs, TResult>>;
+	>(locator: string): Promise<ResolvedResource3<TArgs, TResult>>;
 }
 /**
 * Factory function to create domain validation middleware.
@@ -436,4 +397,4 @@ declare class DomainValidation extends RegistryMiddleware {
 * const registry = withDomainValidation(gitRegistry, "deepractice.ai");
 */
 declare function withDomainValidation(registry: Registry, trustedDomain: string): Registry;
-export { withDomainValidation, isRemoteConfig, isGitConfig, discoverRegistry, createRegistry, WellKnownResponse, SearchOptions, RemoteRegistryConfig, RemoteRegistry, RegistryMiddleware, RegistryError, RegistryConfig, Registry, PullOptions, PublishTarget, PublishOptions, LocalRegistryConfig, LocalRegistry, GitRegistryConfig, GitRegistry, DomainValidation, DiscoveryResult };
+export { withDomainValidation, discoverRegistry, createRegistry, WellKnownResponse, Storage, ServerRegistryConfig, SearchOptions, RegistryMiddleware, RegistryError, RegistryConfig, Registry, LocalStorageConfig, LocalStorage, DomainValidation, DiscoveryResult, DefaultRegistry, CreateRegistryConfig, ClientRegistryConfig };