@resourcexjs/registry 1.7.0 → 2.1.0

package/README.md

@@ -10,36 +10,47 @@ bun add @resourcexjs/registry
 
 ## Overview
 
-The `@resourcexjs/registry` package provides a Maven-style registry for storing and resolving resources locally.
+The `@resourcexjs/registry` package provides a Maven-style registry for storing and resolving resources (local or remote).
 
 ### Key Concepts
 
 - **Registry**: Interface for resource storage and retrieval
-- **ARPRegistry**: Implementation using ARP (Agent Resource Protocol) for I/O
-- **Local-first**: Resources cached locally at `~/.resourcex`
-- **Maven-style**: Organized by `domain/path/name.type@version`
+- **LocalRegistry**: Filesystem-based implementation for local storage
+- **RemoteRegistry**: HTTP API-based implementation for remote access
+- **Well-known discovery**: Auto-discover registry endpoint via `/.well-known/resourcex`
+- **Maven-style**: Organized by `domain/path/name.type/version`
 
 ## Usage
 
 ### Create Registry
 
 ```typescript
-import { createRegistry } from "@resourcexjs/registry";
+import { createRegistry, discoverRegistry } from "@resourcexjs/registry";
 
-// Default configuration (~/.resourcex)
+// Local registry (default)
 const registry = createRegistry();
 
-// Custom path
-const registry = createRegistry({
+// Local registry with custom path
+const registry2 = createRegistry({
   path: "./my-registry",
 });
 
-// With extension types
+// Local registry with extension types
 import { promptType } from "@my-org/types";
 
-const registry = createRegistry({
+const registry3 = createRegistry({
+  path: "~/.resourcex",
   types: [promptType],
 });
+
+// Remote registry
+const registry4 = createRegistry({
+  endpoint: "https://registry.deepractice.ai/v1",
+});
+
+// Remote registry with well-known discovery
+const endpoint = await discoverRegistry("deepractice.ai");
+const registry5 = createRegistry({ endpoint });
 ```
 
 ### Link Resource
@@ -201,30 +212,59 @@ const all = await registry.search();
 
 ## Storage Structure
 
-Resources are stored in Maven-style structure:
+Resources are stored in two separate areas:
+
+- **local/** - Development resources (organized by name.type/version)
+- **cache/** - Remote cached resources (organized by domain/path/name.type/version)
 
 ```
 ~/.resourcex/
-└── {domain}/
-    └── {path}/
-        └── {name}.{type}@{version}/
-            ├── manifest.json    # RXM metadata
-            └── content          # Serialized content
+├── local/                              # Development area
+│   └── {name}.{type}/
+│       └── {version}/
+│           ├── manifest.json
+│           └── content.tar.gz
+│
+└── cache/                              # Remote cache area
+    └── {domain}/
+        └── {path}/
+            └── {name}.{type}/
+                └── {version}/
+                    ├── manifest.json
+                    └── content.tar.gz
 ```
 
 ### Example
 
-For resource `deepractice.ai/prompts/assistant.prompt@1.0.0`:
+For a local development resource `my-prompt.text@1.0.0`:
+
+```
+~/.resourcex/
+└── local/
+    └── my-prompt.text/
+        └── 1.0.0/
+            ├── manifest.json    # domain can be "deepractice.ai" or "localhost"
+            └── content.tar.gz
+```
+
+For a cached remote resource `deepractice.ai/prompts/assistant.text@1.0.0`:
 
 ```
 ~/.resourcex/
-└── deepractice.ai/
-    └── prompts/
-        └── assistant.prompt@1.0.0/
-            ├── manifest.json
-            └── content
+└── cache/
+    └── deepractice.ai/
+        └── prompts/
+            └── assistant.text/
+                └── 1.0.0/
+                    ├── manifest.json
+                    └── content.tar.gz
 ```
 
+### Resolution Order
+
+1. **local/** is checked first (development resources)
+2. **cache/** is checked second (remote cached resources)
+
 **manifest.json:**
 
 ```json
@@ -237,7 +277,7 @@ For resource `deepractice.ai/prompts/assistant.prompt@1.0.0`:
 }
 ```
 
-**content:** (serialized by type's serializer)
+**content.tar.gz:** Archive containing resource files (managed by TypeHandlerChain)
 
 ## Extension Types
 
@@ -373,31 +413,47 @@ await registry.link(agentResource);
 
 ## Resolution Strategy
 
-1. **Check local registry** (`~/.resourcex` or custom path)
-2. **If not found**: (TODO) Fetch from remote registry based on domain
-3. **Cache locally** after fetching
-4. **Return** resource
+### LocalRegistry
+
+1. **Check local filesystem** (`~/.resourcex` or custom path)
+2. **If not found**: Throw RegistryError
+3. **Return** RXR
+
+### RemoteRegistry
+
+1. **Fetch from HTTP API** (`GET /resource` + `GET /content`)
+2. **Return** RXR (no local caching)
+
+### Future: Hybrid Strategy (TODO)
 
-Currently only local resolution is implemented. Remote fetching is planned.
+1. Check local cache first
+2. If not found, fetch from remote based on domain
+3. Cache locally
+4. Return RXR
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────┐
-│          Registry Interface         │
-└──────────────┬──────────────────────┘
-               │
-        ┌──────▼──────┐
-        │ARPRegistry  │
-        │(implements) │
-        └──────┬──────┘
-               │
-     ┌─────────┴─────────┐
-     │                   │
-┌────▼────┐      ┌──────▼──────┐
-│   ARP   │      │TypeHandler  │
-│(I/O)    │      │Chain        │
-└─────────┘      └─────────────┘
+┌─────────────────────────────────────────┐
+│         Registry Interface              │
+└────────────┬────────────────────────────┘
+             │
+    ┌────────┴────────┐
+    │                 │
+┌───▼──────────┐  ┌──▼──────────────┐
+│LocalRegistry │  │RemoteRegistry   │
+│(filesystem)  │  │(HTTP API)       │
+└───┬──────────┘  └──┬──────────────┘
+    │                │
+┌───▼───────┐    ┌──▼──────┐
+│ Node.js   │    │ fetch   │
+│ fs module │    │         │
+└───────────┘    └─────────┘
+     │                │
+┌────▼────────────────▼─────┐
+│   TypeHandlerChain        │
+│  (serialization logic)    │
+└───────────────────────────┘
 ```
 
 ## Type Safety

package/dist/index.d.ts

@@ -27,14 +27,59 @@ interface RemoteRegistryConfig {
 	endpoint: string;
 }
 /**
-* Registry configuration - either local or remote.
+* Git registry configuration.
+* Uses git clone to fetch registry content.
 */
-type RegistryConfig = LocalRegistryConfig | RemoteRegistryConfig;
+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.
 */
 interface SearchOptions {
@@ -52,6 +97,36 @@ 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.
 */
 interface Registry {
@@ -61,9 +136,19 @@ interface Registry {
 	*/
 	supportType(type: ResourceType): void;
 	/**
-	* Publish resource to remote registry (based on domain).
+	* 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
+	*/
+	pull(locator: string, options?: PullOptions): Promise<void>;
+	/**
+	* Publish resource to remote registry.
+	* Resource must exist in local first.
+	* @param resource - Resource to publish
+	* @param options - Publish target configuration
 	*/
-	publish(resource: RXR): Promise<void>;
+	publish(resource: RXR, options: PublishOptions): Promise<void>;
 	/**
 	* Link resource to local registry (for development/caching).
 	*/
@@ -103,25 +188,54 @@ import { ResourceXError } from "@resourcexjs/core";
 * Registry-specific error.
 */
 declare class RegistryError extends ResourceXError {
-	constructor(message: string);
+	constructor(message: string, options?: ErrorOptions);
 }
 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.
-* Uses Node.js fs module directly for storage operations.
+* Uses ARP file transport for I/O operations.
 */
 declare class LocalRegistry implements Registry {
 	private readonly basePath;
 	private readonly typeHandler;
+	private readonly arp;
 	constructor(config?: LocalRegistryConfig);
 	supportType(type: ResourceType2): void;
 	/**
+	* Create ARP URL for a file path.
+	*/
+	private toArpUrl;
+	/**
 	* Build filesystem path for a resource.
-	* Path structure: {basePath}/{domain}/{path}/{name}.{type}/{version}
+	*
+	* 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")
 	*/
 	private buildPath;
-	publish(_resource: RXR2): Promise<void>;
+	/**
+	* 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.
+	*/
+	private existsAt;
+	/**
+	* Find which area a resource exists in.
+	* Returns the area ("local" or "cache") or null if not found.
+	*/
+	private findArea;
+	/**
+	* Load resource from a specific path.
+	*/
+	private loadFrom;
+	pull(_locator: string, _options?: PullOptions): Promise<void>;
+	publish(_resource: RXR2, _options: PublishOptions): Promise<void>;
 	link(resource: RXR2): Promise<void>;
 	get(locator: string): Promise<RXR2>;
 	resolve<
@@ -132,14 +246,19 @@ declare class LocalRegistry implements Registry {
 	delete(locator: string): Promise<void>;
 	search(options?: SearchOptions): Promise<RXL2[]>;
 	/**
-	* Recursively list all files in a directory.
+	* Parse a local entry path to RXL.
+	* Entry format: {name}.{type}/{version}/manifest.json
 	*/
-	private listRecursive;
+	private parseLocalEntry;
 	/**
-	* Parse a file entry path to RXL.
+	* Parse a cache entry path to RXL.
 	* Entry format: {domain}/{path}/{name}.{type}/{version}/manifest.json
 	*/
-	private parseEntryToRXL;
+	private parseCacheEntry;
+	/**
+	* Parse name and type from a combined string like "name.type" or "name".
+	*/
+	private parseNameType;
 }
 import { RXR as RXR3, RXL as RXL3 } from "@resourcexjs/core";
 import { ResourceType as ResourceType3, ResolvedResource as ResolvedResource3 } from "@resourcexjs/type";
@@ -152,7 +271,8 @@ declare class RemoteRegistry implements Registry {
 	private readonly typeHandler;
 	constructor(config: RemoteRegistryConfig);
 	supportType(type: ResourceType3): void;
-	publish(_resource: RXR3): Promise<void>;
+	pull(_locator: string, _options?: PullOptions): Promise<void>;
+	publish(_resource: RXR3, _options: PublishOptions): Promise<void>;
 	link(_resource: RXR3): Promise<void>;
 	get(locator: string): Promise<RXR3>;
 	resolve<
@@ -164,17 +284,75 @@ declare class RemoteRegistry implements Registry {
 	search(options?: SearchOptions): Promise<RXL3[]>;
 }
 /**
-* Discover registry endpoint for a domain using well-known.
+* Discover registry for a domain using well-known.
 * @param domain - The domain to discover (e.g., "deepractice.ai")
-* @returns The registry endpoint URL
+* @returns Discovery result with domain and authorized registries
 */
-declare function discoverRegistry(domain: string): Promise<string>;
+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";
+/**
+* Git-based registry implementation.
+* Clones a git repository and reads resources from it.
+*/
+declare class GitRegistry implements Registry {
+	private readonly url;
+	private readonly ref;
+	private readonly basePath;
+	private readonly cacheDir;
+	private readonly typeHandler;
+	private readonly arp;
+	constructor(config: GitRegistryConfig);
+	/**
+	* Build cache directory name from git URL.
+	* git@github.com:Deepractice/Registry.git → github.com-Deepractice-Registry
+	*/
+	private buildCacheDir;
+	supportType(type: ResourceType4): void;
+	/**
+	* Create ARP URL for a file path.
+	*/
+	private toArpUrl;
+	/**
+	* Ensure the repository is cloned and up to date.
+	*/
+	private ensureCloned;
+	/**
+	* Get the default branch name (main or master).
+	*/
+	private getDefaultBranch;
+	/**
+	* Execute git command in the cache directory.
+	*/
+	private gitExec;
+	/**
+	* Build filesystem path for a resource in the cloned repo.
+	* Path structure: {cacheDir}/{basePath}/{domain}/{path}/{name}.{type}/{version}
+	*/
+	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;
+	pull(_locator: string, _options?: PullOptions): Promise<void>;
+	publish(_resource: RXR4, _options: PublishOptions): Promise<void>;
+	link(_resource: RXR4): Promise<void>;
+	delete(_locator: string): Promise<void>;
+}
 /**
 * Create a registry instance.
 *
+* When a `domain` is provided in GitRegistryConfig, the registry is automatically
+* wrapped with DomainValidation middleware for security.
+*
 * @param config - Registry configuration
 *   - No config or LocalRegistryConfig: Creates LocalRegistry (filesystem-based)
 *   - RemoteRegistryConfig: Creates RemoteRegistry (HTTP-based)
+*   - GitRegistryConfig: Creates GitRegistry (git clone-based)
 *
 * @example
 * // Local registry (default)
@@ -183,6 +361,68 @@ declare function discoverRegistry(domain: string): Promise<string>;
 *
 * // Remote registry
 * const registry3 = createRegistry({ endpoint: "https://registry.deepractice.ai/v1" });
+*
+* // 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
+* });
 */
 declare function createRegistry(config?: RegistryConfig): Registry;
-export { isRemoteConfig, discoverRegistry, createRegistry, SearchOptions, RemoteRegistryConfig, RemoteRegistry, RegistryError, RegistryConfig, Registry, LocalRegistryConfig, LocalRegistry };
+import { RXR as RXR5, RXL as RXL5 } from "@resourcexjs/core";
+import { ResourceType as ResourceType5, ResolvedResource as ResolvedResource5 } from "@resourcexjs/type";
+/**
+* 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);
+	supportType(type: ResourceType5): void;
+	pull(locator: string, options?: PullOptions): Promise<void>;
+	publish(resource: RXR5, options: PublishOptions): Promise<void>;
+	link(resource: RXR5): Promise<void>;
+	get(locator: string): Promise<RXR5>;
+	resolve<
+		TArgs = void,
+		TResult = unknown
+	>(locator: string): Promise<ResolvedResource5<TArgs, TResult>>;
+	exists(locator: string): Promise<boolean>;
+	delete(locator: string): Promise<void>;
+	search(options?: SearchOptions): Promise<RXL5[]>;
+}
+import { RXR as RXR6 } from "@resourcexjs/core";
+import { ResolvedResource as ResolvedResource6 } from "@resourcexjs/type";
+/**
+* Domain validation middleware.
+* Ensures all resources from this registry match the trusted domain.
+*/
+declare class DomainValidation extends RegistryMiddleware {
+	private readonly trustedDomain;
+	constructor(inner: Registry, trustedDomain: string);
+	/**
+	* Validate that manifest domain matches trusted domain.
+	*/
+	private validateDomain;
+	/**
+	* Get resource and validate domain.
+	*/
+	get(locator: string): Promise<RXR6>;
+	/**
+	* Resolve resource and validate domain.
+	*/
+	resolve<
+		TArgs = void,
+		TResult = unknown
+	>(locator: string): Promise<ResolvedResource6<TArgs, TResult>>;
+}
+/**
+* Factory function to create domain validation middleware.
+*
+* @example
+* 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 };