@resourcexjs/arp 1.6.0 → 2.0.0

package/README.md

@@ -19,7 +19,7 @@ arp:{semantic}:{transport}://{location}
 ```
 
 - **semantic**: Content interpretation (text, binary)
-- **transport**: Storage backend (file, http, https, agentvm)
+- **transport**: Storage backend (file, http, https, rxr)
 - **location**: Resource location (path, URL)
 
 ### Examples
@@ -27,9 +27,24 @@ arp:{semantic}:{transport}://{location}
 ```
 arp:text:file://~/data.txt
 arp:binary:https://example.com/image.png
-arp:text:agentvm://sandbox/config.json
+arp:text:rxr://localhost/my-prompt.text@1.0.0/content
 ```
 
+### Built-in Handlers
+
+**createARP()** auto-registers all built-in handlers:
+
+**Transports:**
+
+- `file` - Local filesystem (read-write)
+- `http`, `https` - Network resources (read-only)
+- `rxr` - Files inside resources (read-only, auto-creates Registry)
+
+**Semantics:**
+
+- `text` - UTF-8 text → string
+- `binary` - Raw bytes → Buffer
+
 ## Usage
 
 ### Basic Operations
@@ -289,21 +304,48 @@ const result = await arl.resolve({ lang: "en" });
 // Fetches: https://api.example.com/data?format=json&lang=en
 ```
 
-### AgentVM Transport (`agentvm`)
+### RXR Transport (`rxr`)
 
-AgentVM sandbox storage (`~/.agentvm/`).
+Access files inside ResourceX resources (read-only).
 
 ```typescript
-arp.parse("arp:text:agentvm://sandbox/config.json");
-// Maps to: ~/.agentvm/sandbox/config.json
+// Format: arp:{semantic}:rxr://{rxl}/{internal-path}
+arp.parse("arp:text:rxr://localhost/my-prompt.text@1.0.0/content");
+arp.parse("arp:text:rxr://deepractice.ai/nuwa.text@1.0.0/thought/first-principles.md");
 ```
 
 **Operations:**
 
-- ✅ get (read)
-- ✅ set (write)
-- ✅ exists
-- ✅ delete
+- ✅ get (read file from resource)
+- ❌ set (read-only, throws error)
+- ✅ exists (check if file exists in resource)
+- ❌ delete (read-only, throws error)
+
+**Auto-creates Registry:**
+
+- `localhost` domain → LocalRegistry (filesystem)
+- Other domains → RemoteRegistry (via well-known discovery)
+
+```typescript
+// No manual setup needed - works out of the box!
+const arp = createARP();
+const arl = arp.parse("arp:text:rxr://localhost/hello.text@1.0.0/content");
+const { content } = await arl.resolve();
+// RxrTransport automatically creates LocalRegistry for localhost
+```
+
+**Manual Registry injection (optional):**
+
+```typescript
+import { createRegistry } from "@resourcexjs/registry";
+import { createARP, RxrTransport } from "@resourcexjs/arp";
+
+const registry = createRegistry({ path: "./custom-path" });
+const rxrTransport = new RxrTransport(registry);
+
+const arp = createARP();
+arp.registerTransport(rxrTransport); // Override default rxr transport
+```
 
 ## Error Handling
 

package/dist/index.d.ts

@@ -408,6 +408,71 @@ declare class HttpTransportHandler implements TransportHandler {
 }
 declare const httpsTransport: HttpTransportHandler;
 declare const httpTransport: HttpTransportHandler;
+/**
+* Minimal registry interface required by RxrTransport.
+* This allows RxrTransport to work without depending on the full Registry type.
+*/
+interface RxrTransportRegistry {
+	get(locator: string): Promise<{
+		content: {
+			files(): Promise<Map<string, Buffer>>
+		}
+	}>;
+}
+/**
+* RXR Transport - Access files inside a resource.
+*
+* Location format: {rxl}/{internal-path}
+* Example: deepractice.ai/nuwa.role@1.0.0/thought/first-principles.md
+*
+* The RXL portion ends at @version, and the internal path follows.
+*
+* When no registry is provided, automatically creates one based on domain:
+* - localhost: LocalRegistry
+* - Other domains: RemoteRegistry with well-known discovery
+*/
+declare class RxrTransport implements TransportHandler {
+	private registry?;
+	readonly name = "rxr";
+	constructor(registry?: RxrTransportRegistry);
+	/**
+	* Get file content from inside a resource.
+	*/
+	get(location: string, _params?: TransportParams): Promise<TransportResult>;
+	/**
+	* Set is not supported - RXR transport is read-only.
+	*/
+	set(_location: string, _content: Buffer, _params?: TransportParams): Promise<void>;
+	/**
+	* Check if a file exists inside a resource.
+	*/
+	exists(location: string): Promise<boolean>;
+	/**
+	* Delete is not supported - RXR transport is read-only.
+	*/
+	delete(_location: string): Promise<void>;
+	/**
+	* Get or create a registry for the given domain.
+	* - If a registry was provided in constructor, use it
+	* - localhost: create LocalRegistry
+	* - Other domains: discover endpoint via well-known and create appropriate registry
+	*/
+	private getRegistry;
+	/**
+	* Check if URL is a git repository URL.
+	*/
+	private isGitUrl;
+	/**
+	* Parse location into domain, RXL and internal path.
+	* Format: {domain}/{path}/{name}.{type}@{version}/{internal-path}
+	* Example: deepractice.ai/nuwa.role@1.0.0/thought/first-principles.md
+	*/
+	private parseLocation;
+}
+/**
+* Clear the registry cache. Useful for testing.
+*/
+declare function clearRegistryCache(): void;
 interface TextResource extends Resource<string> {
 	type: "text";
 	content: string;
@@ -437,4 +502,4 @@ declare class BinarySemanticHandler implements SemanticHandler<Buffer> {
 }
 declare const binarySemantic: BinarySemanticHandler;
 declare const VERSION: string;
-export { textSemantic, httpsTransport, httpTransport, fileTransport, createARP, binarySemantic, VERSION, TransportResult, TransportParams, TransportHandler, TransportError, TextSemanticHandler, TextResource, SemanticHandler, SemanticError, SemanticContext, ResourceMeta, Resource, ParseError, HttpTransportHandler, FileTransportHandler, BinarySemanticHandler, BinaryResource, BinaryInput, ARPError, ARPConfig, ARP, ARL, ARI };
+export { textSemantic, httpsTransport, httpTransport, fileTransport, createARP, clearRegistryCache, binarySemantic, VERSION, TransportResult, TransportParams, TransportHandler, TransportError, TextSemanticHandler, TextResource, SemanticHandler, SemanticError, SemanticContext, RxrTransportRegistry, RxrTransport, ResourceMeta, Resource, ParseError, HttpTransportHandler, FileTransportHandler, BinarySemanticHandler, BinaryResource, BinaryInput, ARPError, ARPConfig, ARP, ARL, ARI };