@resourcexjs/registry 2.5.0 → 2.5.2

package/README.md

@@ -1,6 +1,6 @@
 # @resourcexjs/registry
 
-Resource registry for ResourceX - storage and retrieval of resources.
+Registry layer for ResourceX. Provides business logic for RXR (ResourceX Resource) operations on top of the storage layer.
 
 ## Installation
 
@@ -10,439 +10,413 @@ bun add @resourcexjs/registry
 
 ## Overview
 
-The `@resourcexjs/registry` package provides a Maven-style registry for storing and resolving resources.
+The `@resourcexjs/registry` package provides:
 
-### Key Concepts
+- **Three registry types** for different use cases
+- **Access chain** for read-through cache pattern
+- **Middleware** for cross-cutting concerns
+- **Discovery** for well-known registry endpoints
 
-- **Registry**: Interface for resource storage and retrieval
-- **DefaultRegistry**: Main implementation combining Storage with type handling
-- **LocalStorage**: Filesystem-based storage for local resources
-- **Storage**: Abstract interface for different storage backends
-- **Well-known discovery**: Auto-discover registry endpoints via `/.well-known/resourcex`
-- **Isolator**: Sandbox execution for resolver code
+All registries implement a common `Registry` interface and use `@resourcexjs/storage` for persistence.
 
-## Usage
+## Registry Types
 
-### Create Registry
+### LocalRegistry
 
-```typescript
-import { createRegistry } from "@resourcexjs/registry";
-
-// Default registry (uses LocalStorage at ~/.resourcex)
-const registry = createRegistry();
-
-// Custom local path
-const registry2 = createRegistry({
-  path: "./my-registry",
-});
-
-// With custom resource types
-import { bundleResourceType } from "@resourcexjs/type";
-const promptType = await bundleResourceType("./prompt.type.ts");
+For local/owned resources without a registry domain in the path.
 
-const registry3 = createRegistry({
-  types: [promptType],
-});
+```typescript
+import { LocalRegistry } from "@resourcexjs/registry";
+import { FileSystemStorage } from "@resourcexjs/storage";
 
-// With sandbox isolation
-const registry4 = createRegistry({
-  isolator: "srt", // "none" | "srt" | "cloudflare" | "e2b"
-});
+const storage = new FileSystemStorage("~/.resourcex/local");
+const registry = new LocalRegistry(storage);
 
-// With remote mirror
-const registry5 = createRegistry({
-  mirror: "https://registry.deepractice.ai/v1",
-});
+// Storage structure: {name}/{tag}/manifest.json + archive.tar.gz
+await registry.put(rxr);
+const resource = await registry.get(rxl);
+```
 
-// Server mode with custom storage
-import { LocalStorage } from "@resourcexjs/registry";
+**Use cases:**
 
-const registry6 = createRegistry({
-  storage: new LocalStorage({ path: "./data" }),
-});
-```
+- Client local storage (`~/.resourcex/local/`)
+- Server authoritative storage (`./data/`)
 
-### Add Resource
+### MirrorRegistry
 
-Add a resource to the registry:
+For cached/mirrored remote resources. Includes registry domain in the path.
 
 ```typescript
-import { loadResource } from "@resourcexjs/loader";
-import { createRegistry } from "@resourcexjs/registry";
-
-// Load resource from folder
-const rxr = await loadResource("./my-prompt");
+import { MirrorRegistry } from "@resourcexjs/registry";
+import { FileSystemStorage } from "@resourcexjs/storage";
 
-// Add to registry
-const registry = createRegistry();
-await registry.add(rxr);
+const storage = new FileSystemStorage("~/.resourcex/cache");
+const registry = new MirrorRegistry(storage);
 
-// Or add directly from path
-await registry.add("./my-prompt");
+// Storage structure: {registry}/{name}/{tag}/manifest.json + archive.tar.gz
+await registry.put(rxr);
+const resource = await registry.get(rxl);
 
-// Now stored at: ~/.resourcex/local/my-prompt.text/1.0.0/
+// Cache-specific: clear cached resources
+await registry.clear(); // Clear all
+await registry.clear("deepractice.ai"); // Clear specific registry
 ```
 
-### Link Resource (Development)
+**Use cases:**
 
-Link creates a symlink for live development changes:
+- Caching remote resources locally
+- Offline access to previously fetched resources
 
-```typescript
-const registry = createRegistry();
-
-// Link directory - changes reflect immediately
-await registry.link("./my-prompts/assistant");
-```
-
-### Resolve Resource
+### LinkedRegistry
 
-Retrieve and execute a resource:
+For development symlinks. Changes in the source directory are reflected immediately.
 
 ```typescript
-const registry = createRegistry();
+import { LinkedRegistry } from "@resourcexjs/registry";
 
-// Resolve returns ResolvedResource with execute()
-const resolved = await registry.resolve("localhost/my-prompt.text@1.0.0");
+const registry = new LinkedRegistry("~/.resourcex/linked");
 
-// Execute to get content
-const text = await resolved.execute();
-console.log(text);
+// Create symlink to development directory
+const rxl = await registry.link("./my-prompt");
 
-// Check schema (for types with arguments)
-console.log(resolved.schema); // undefined for text type
-```
+// Get resource (reads from symlink target)
+const resource = await registry.get(rxl);
 
-### Get Raw Resource
+// Remove symlink
+await registry.unlink(rxl);
+```
 
-Get the RXR without resolving:
+**Use cases:**
 
-```typescript
-const rxr = await registry.get("localhost/my-prompt.text@1.0.0");
+- Live development without re-adding resources
+- Testing local changes before publishing
 
-console.log(rxr.manifest.name); // "my-prompt"
-console.log(rxr.manifest.type); // "text"
-```
+## Registry Interface
 
-### Check Existence
+All registries implement:
 
 ```typescript
-if (await registry.exists("localhost/my-prompt.text@1.0.0")) {
-  console.log("Resource exists");
+interface 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[]>;
+}
+
+interface SearchOptions {
+  query?: string; // Filter by name/path substring
+  limit?: number; // Max results
+  offset?: number; // Skip first N (pagination)
 }
 ```
 
-### Delete Resource
+## Access Chain
 
-```typescript
-await registry.delete("localhost/my-prompt.text@1.0.0");
-```
+The access chain implements a read-through cache pattern for unified resource access.
+
+### RegistryAccessChain
 
-### Search Resources
+Iterates through accessors in order. First accessor that can handle returns the result.
 
 ```typescript
-// List all resources
-const all = await registry.search();
-
-// Search by name
-const results = await registry.search({ query: "assistant" });
-
-// With pagination
-const page = await registry.search({
-  query: "prompt",
-  limit: 10,
-  offset: 20,
-});
+import {
+  RegistryAccessChain,
+  LinkedAccessor,
+  LocalAccessor,
+  CacheAccessor,
+  RemoteAccessor,
+  LocalRegistry,
+  MirrorRegistry,
+  LinkedRegistry,
+} from "@resourcexjs/registry";
+import { FileSystemStorage } from "@resourcexjs/storage";
+
+// Create registries
+const linkedRegistry = new LinkedRegistry("~/.resourcex/linked");
+const localRegistry = new LocalRegistry(new FileSystemStorage("~/.resourcex/local"));
+const cacheRegistry = new MirrorRegistry(new FileSystemStorage("~/.resourcex/cache"));
+
+// Create accessor chain
+const chain = new RegistryAccessChain(
+  [
+    new LinkedAccessor(linkedRegistry), // 1. Dev symlinks (highest priority)
+    new LocalAccessor(localRegistry), // 2. Local resources (no domain)
+    new CacheAccessor(cacheRegistry), // 3. Cached remote resources
+    new RemoteAccessor(fetcher, cacheRegistry), // 4. Fetch + auto-cache
+  ],
+  { memCache: true } // Optional in-memory cache
+);
+
+// Get resource (tries each accessor in order)
+const rxr = await chain.get(rxl);
+
+// Check existence
+const exists = await chain.has(rxl);
+
+// Cache management
+chain.invalidate(rxl); // Remove specific resource from memory cache
+chain.clearCache(); // Clear entire memory cache
 ```
 
-### Support Custom Types
+### Accessor Types
 
-```typescript
-import { bundleResourceType } from "@resourcexjs/type";
+| Accessor         | Handles                    | Description                    |
+| ---------------- | -------------------------- | ------------------------------ |
+| `LinkedAccessor` | All (if linked)            | Dev symlinks, highest priority |
+| `LocalAccessor`  | Resources without registry | Local storage                  |
+| `CacheAccessor`  | Resources with registry    | Cached remote resources        |
+| `RemoteAccessor` | Resources with registry    | Fetch + auto-cache             |
+
+### RemoteFetcher Interface
 
-const registry = createRegistry();
+`RemoteAccessor` requires a fetcher implementation:
 
-// Bundle and add type at runtime
-const promptType = await bundleResourceType("./prompt.type.ts");
-registry.supportType(promptType);
+```typescript
+interface RemoteFetcher {
+  fetch(rxl: RXL): Promise<RXR>;
+}
 
-// Now can resolve prompt resources
-const resolved = await registry.resolve("localhost/assistant.prompt@1.0.0");
+// Example implementation
+const fetcher: RemoteFetcher = {
+  async fetch(rxl) {
+    const url = `https://${rxl.registry}/api/v1/resources/${rxl.name}/${rxl.tag}`;
+    const response = await fetch(url);
+    // ... parse response to RXR
+    return rxr;
+  },
+};
 ```
 
-## API Reference
+## Middleware
 
-### `createRegistry(config?)`
+### RegistryMiddleware
 
-Create a new registry instance.
+Base class for creating custom middleware. Delegates all operations to the inner registry.
 
-**Parameters:**
+```typescript
+import { RegistryMiddleware } from "@resourcexjs/registry";
+import type { RXL, RXR } from "@resourcexjs/core";
 
-- `config?: ClientRegistryConfig | ServerRegistryConfig`
+class LoggingMiddleware extends RegistryMiddleware {
+  async get(rxl: RXL): Promise<RXR> {
+    console.log("Getting:", rxl);
+    const rxr = await this.inner.get(rxl);
+    console.log("Got:", rxr.manifest.name);
+    return rxr;
+  }
+}
 
-**Client mode (default):**
+const logged = new LoggingMiddleware(registry);
+```
 
-- `path?: string` - Local cache path (default: `~/.resourcex`)
-- `mirror?: string` - Mirror URL for remote fetch
-- `types?: BundledType[]` - Custom resource types
-- `isolator?: IsolatorType` - Sandbox isolation level
+### DomainValidation
 
-**Server mode:**
+Built-in middleware that validates resource registry matches a trusted registry.
 
-- `storage: Storage` - Custom storage implementation
-- `types?: BundledType[]` - Custom resource types
-- `isolator?: IsolatorType` - Sandbox isolation level
+```typescript
+import { withDomainValidation } from "@resourcexjs/registry";
 
-**Returns**: `Registry`
+const validated = withDomainValidation(registry, "deepractice.ai");
 
-```typescript
-// Client mode
-const registry = createRegistry({
-  path: "~/.resourcex",
-  mirror: "https://registry.deepractice.ai/v1",
-  types: [promptType],
-  isolator: "srt",
-});
-
-// Server mode
-const registry = createRegistry({
-  storage: new LocalStorage({ path: "./data" }),
-  types: [promptType],
-});
+// Throws RegistryError if resource.manifest.registry !== "deepractice.ai"
+await validated.get(rxl);
 ```
 
-### `discoverRegistry(domain)`
-
-Discover registry endpoints for a domain via well-known.
+**Use cases:**
 
-**Parameters:**
+- Server-side validation to prevent registry impersonation
+- Ensuring resources are from trusted sources
 
-- `domain: string` - Domain to discover (e.g., "deepractice.ai")
+## Discovery
 
-**Returns**: `Promise<DiscoveryResult>`
+Discover registry endpoints via well-known URL.
 
 ```typescript
+import { discoverRegistry } from "@resourcexjs/registry";
+
 const result = await discoverRegistry("deepractice.ai");
-// { domain: "deepractice.ai", registries: ["https://..."] }
+// {
+//   domain: "deepractice.ai",
+//   registries: ["https://registry.deepractice.ai/api/v1"]
+// }
 ```
 
-### Registry Interface
-
-#### `supportType(type: BundledType): void`
-
-Add support for a custom resource type at runtime.
-
-#### `link(path: string): Promise<void>`
-
-Create a symlink for development. Changes in the source directory are immediately reflected.
-
-#### `add(source: string | RXR): Promise<void>`
-
-Add resource to storage. Accepts a folder path or RXR object.
-
-#### `get(locator: string): Promise<RXR>`
+**Well-known format** (`https://{domain}/.well-known/resourcex`):
 
-Get raw RXR by locator without resolving.
+```json
+{
+  "version": "1.0",
+  "registries": ["https://registry.example.com/api/v1"]
+}
+```
 
-#### `resolve<TArgs, TResult>(locator: string): Promise<ResolvedResource<TArgs, TResult>>`
+## Storage Structure
 
-Resolve resource and return structured result with execute function.
+```
+~/.resourcex/
+├── local/                          # LocalRegistry - local resources
+│   └── {path/}{name}/
+│       └── {tag}/
+│           ├── manifest.json
+│           └── archive.tar.gz
+│
+├── cache/                          # MirrorRegistry - cached remote
+│   └── {registry}/
+│       └── {path/}{name}/
+│           └── {tag}/
+│               ├── manifest.json
+│               └── archive.tar.gz
+│
+└── linked/                         # LinkedRegistry - dev symlinks
+    └── {registry}/
+        └── {path/}{name}/
+            └── {tag} -> /path/to/dev/folder
+```
 
-#### `exists(locator: string): Promise<boolean>`
+## Error Handling
 
-Check if resource exists.
+```typescript
+import { RegistryError } from "@resourcexjs/registry";
 
-#### `delete(locator: string): Promise<void>`
+try {
+  await registry.get(rxl);
+} catch (error) {
+  if (error instanceof RegistryError) {
+    console.error("Registry error:", error.message);
+  }
+}
+```
 
-Delete resource from storage.
+**Common errors:**
 
-#### `search(options?: SearchOptions): Promise<RXL[]>`
+- `Resource not found: {locator}`
+- `Resource not found in cache: {locator}`
+- `Linked resource not found: {locator}`
+- `LinkedRegistry does not support put(). Use link() instead.`
+- `Well-known discovery failed for {domain}: {status}`
+- `Untrusted registry: resource claims "{claimed}" but registry only trusts "{trusted}"`
 
-Search for resources.
+## API Reference
 
-- `query?: string` - Filter by locator substring
-- `limit?: number` - Max results
-- `offset?: number` - Skip first N results
+### Registries
 
-### Storage Interface
+#### `LocalRegistry`
 
 ```typescript
-interface Storage {
-  readonly type: string;
-  get(locator: string): Promise<RXR>;
-  put(rxr: RXR): Promise<void>;
-  exists(locator: string): Promise<boolean>;
-  delete(locator: string): Promise<void>;
-  search(options?: SearchOptions): Promise<RXL[]>;
-}
+new LocalRegistry(storage: Storage)
 ```
 
-### LocalStorage
+Registry for local resources without registry domain.
 
-Filesystem-based storage implementation.
+#### `MirrorRegistry`
 
 ```typescript
-import { LocalStorage } from "@resourcexjs/registry";
-
-const storage = new LocalStorage({
-  path: "~/.resourcex", // optional, defaults to ~/.resourcex
-});
+new MirrorRegistry(storage: Storage)
 ```
 
-## Storage Structure
+Registry for cached remote resources with registry domain.
 
-Resources are stored in two areas:
+**Additional methods:**
 
-```
-~/.resourcex/
-├── local/                              # Development resources
-│   └── {name}.{type}/
-│       └── {version}/
-│           ├── manifest.json
-│           └── archive.tar.gz
-│
-└── cache/                              # Remote cached resources
-    └── {domain}/
-        └── {path}/
-            └── {name}.{type}/
-                └── {version}/
-                    ├── manifest.json
-                    └── archive.tar.gz
-```
+- `clear(registry?: string): Promise<void>` - Clear cached resources
 
-### Resolution Order
+#### `LinkedRegistry`
 
-1. **local/** is checked first (development resources)
-2. **cache/** is checked second (remote cached resources)
-3. If not found and domain is not localhost, fetches from remote
+```typescript
+new LinkedRegistry(basePath: string)
+```
 
-## Remote Fetch Flow
+Registry for development symlinks.
 
-For non-localhost domains:
+**Additional methods:**
 
-1. Check local storage (cache)
-2. If mirror configured, try mirror first
-3. Discover source via `https://{domain}/.well-known/resourcex`
-4. Fetch from discovered endpoint
-5. Cache to local storage
+- `link(devPath: string): Promise<RXL>` - Create symlink to development directory
+- `unlink(rxl: RXL): Promise<void>` - Remove symlink (alias for `remove`)
 
-**Well-known format:**
+### Access Chain
 
-```json
-{
-  "version": "1.0",
-  "registries": ["https://registry.example.com/v1"]
-}
+#### `RegistryAccessChain`
+
+```typescript
+new RegistryAccessChain(accessors: RegistryAccessor[], options?: { memCache?: boolean })
 ```
 
-## Middleware
+**Methods:**
 
-### RegistryMiddleware
+- `get(rxl: RXL): Promise<RXR>` - Get resource through chain
+- `has(rxl: RXL): Promise<boolean>` - Check existence
+- `clearCache(): void` - Clear memory cache
+- `invalidate(rxl: RXL): void` - Remove specific resource from memory cache
 
-Base class for creating custom middleware:
+#### `RegistryAccessor`
 
 ```typescript
-import { RegistryMiddleware } from "@resourcexjs/registry";
-
-class LoggingMiddleware extends RegistryMiddleware {
-  async get(locator: string) {
-    console.log("Getting:", locator);
-    return this.inner.get(locator);
-  }
+interface RegistryAccessor {
+  readonly name: string;
+  canHandle(rxl: RXL): Promise<boolean>;
+  get(rxl: RXL): Promise<RXR>;
 }
 ```
 
-### DomainValidation
+### Middleware
 
-Built-in middleware for validating resource domains:
+#### `RegistryMiddleware`
 
 ```typescript
-import { withDomainValidation } from "@resourcexjs/registry";
-
-const validatedRegistry = withDomainValidation(registry, "deepractice.ai");
-
-// Throws if resource.manifest.domain !== "deepractice.ai"
-await validatedRegistry.get("deepractice.ai/assistant.text@1.0.0");
+abstract class RegistryMiddleware implements Registry {
+  constructor(protected readonly inner: Registry)
+}
 ```
 
-## Isolator Types
-
-Sandbox isolation for resolver execution:
-
-| Type           | Description                | Latency |
-| -------------- | -------------------------- | ------- |
-| `"none"`       | No isolation (development) | ~10ms   |
-| `"srt"`        | OS-level isolation         | ~50ms   |
-| `"cloudflare"` | Container isolation        | ~100ms  |
-| `"e2b"`        | MicroVM isolation          | ~150ms  |
+#### `DomainValidation`
 
 ```typescript
-const registry = createRegistry({
-  isolator: "srt",
-});
+new DomainValidation(inner: Registry, trustedRegistry: string)
 ```
 
-## Error Handling
+Middleware class that validates resource registry matches the trusted registry.
 
-```typescript
-import { RegistryError } from "@resourcexjs/registry";
+#### `withDomainValidation`
 
-try {
-  const rxr = await registry.get("localhost/not-exist.text@1.0.0");
-} catch (error) {
-  if (error instanceof RegistryError) {
-    console.error("Registry error:", error.message);
-  }
-}
+```typescript
+withDomainValidation(registry: Registry, trustedRegistry: string): Registry
 ```
 
-### Common Errors
-
-- `Resource not found: {locator}`
-- `Unsupported resource type: {type}`
-- `Well-known discovery failed for {domain}: {status}`
-- `{storage} is read-only: {operation} not supported`
+Factory function to create `DomainValidation` middleware.
 
-## Examples
+### Discovery
 
-### Complete Workflow
+#### `discoverRegistry`
 
 ```typescript
-import { loadResource } from "@resourcexjs/loader";
-import { createRegistry } from "@resourcexjs/registry";
-
-// 1. Create registry
-const registry = createRegistry();
-
-// 2. Load and add resource
-const rxr = await loadResource("./my-prompts/assistant");
-await registry.add(rxr);
-
-// 3. Resolve and execute
-const resolved = await registry.resolve("localhost/assistant.text@1.0.0");
-const text = await resolved.execute();
-console.log(text);
+discoverRegistry(domain: string): Promise<DiscoveryResult>
 ```
 
-### With Custom Types
+**Types:**
 
 ```typescript
-import { createRegistry } from "@resourcexjs/registry";
-import { bundleResourceType } from "@resourcexjs/type";
+interface DiscoveryResult {
+  domain: string;
+  registries: string[];
+}
 
-// Bundle custom type
-const promptType = await bundleResourceType("./prompt.type.ts");
+interface WellKnownResponse {
+  version?: string;
+  registries: string[];
+}
+```
 
-// Create registry with type
-const registry = createRegistry({
-  types: [promptType],
-});
+### Error
 
-// Add and resolve
-await registry.add("./my-prompt");
-const resolved = await registry.resolve<void, string>("localhost/my-prompt.prompt@1.0.0");
-const text = await resolved.execute();
+#### `RegistryError`
+
+```typescript
+class RegistryError extends ResourceXError {
+  constructor(message: string, options?: ErrorOptions);
+}
 ```
 
 ## License
 
-MIT
+Apache-2.0