@resourcexjs/arp 1.7.0 → 2.1.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)
 - **location**: Resource location (path, URL)
 
 ### Examples
@@ -27,9 +27,25 @@ arp:{semantic}:{transport}://{location}
 ```
 arp:text:file://~/data.txt
 arp:binary:https://example.com/image.png
-arp:text:agentvm://sandbox/config.json
 ```
 
+### Built-in Handlers
+
+**createARP()** auto-registers standard protocol handlers:
+
+**Transports:**
+
+- `file` - Local filesystem (read-write)
+- `http`, `https` - Network resources (read-only)
+
+> **Note:** For `rxr` transport (ResourceX-specific), use `resourcexjs/arp` instead.
+> The main package provides an enhanced `createARP()` that includes RxrTransport.
+
+**Semantics:**
+
+- `text` - UTF-8 text → string
+- `binary` - Raw bytes → Buffer
+
 ## Usage
 
 ### Basic Operations
@@ -289,21 +305,34 @@ 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/`).
+> **Moved to main package:** RxrTransport is now available in `resourcexjs/arp`.
+> Use the main package for ResourceX-specific functionality.
 
 ```typescript
-arp.parse("arp:text:agentvm://sandbox/config.json");
-// Maps to: ~/.agentvm/sandbox/config.json
+// Use resourcexjs/arp for rxr transport
+import { createARP, RxrTransport } from "resourcexjs/arp";
+
+// createARP() from main package auto-registers RxrTransport
+const arp = createARP();
+const arl = arp.parse("arp:text:rxr://localhost/my-prompt.text@1.0.0/content");
+const { content } = await arl.resolve();
 ```
 
+**Format:** `arp:{semantic}:rxr://{rxl}/{internal-path}`
+
 **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)
 
 ## Error Handling
 

package/dist/index.d.ts

@@ -11,6 +11,19 @@
 */
 type TransportParams = Record<string, string>;
 /**
+* Options for list operation
+*/
+interface ListOptions {
+	/**
+	* Whether to list recursively
+	*/
+	recursive?: boolean;
+	/**
+	* Glob pattern to filter results (e.g., "*.json")
+	*/
+	pattern?: string;
+}
+/**
 * Result from transport get operation
 */
 interface TransportResult {
@@ -86,6 +99,20 @@ interface TransportHandler {
 	* @param location - The location string (format depends on transport)
 	*/
 	delete(location: string): Promise<void>;
+	/**
+	* List contents at location (optional - not all transports support this)
+	*
+	* @param location - The directory location
+	* @param options - List options (recursive, pattern filter)
+	* @returns Array of file/directory paths relative to location
+	*/
+	list?(location: string, options?: ListOptions): Promise<string[]>;
+	/**
+	* Create directory at location (optional - not all transports support this)
+	*
+	* @param location - The directory location to create
+	*/
+	mkdir?(location: string): Promise<void>;
 }
 /**
 * Resource metadata
@@ -205,6 +232,15 @@ interface ARL extends ARI {
 	*/
 	delete(): Promise<void>;
 	/**
+	* List directory contents (only supported by some transports)
+	* @param options - List options (recursive, pattern filter)
+	*/
+	list(options?: ListOptions): Promise<string[]>;
+	/**
+	* Create directory (only supported by some transports)
+	*/
+	mkdir(): Promise<void>;
+	/**
 	* Convert to ARP URL string
 	*/
 	toString(): string;
@@ -246,6 +282,14 @@ declare class ARL2 implements ARL {
 	*/
 	delete(): Promise<void>;
 	/**
+	* List directory contents
+	*/
+	list(options?: ListOptions): Promise<string[]>;
+	/**
+	* Create directory
+	*/
+	mkdir(): Promise<void>;
+	/**
 	* Convert to ARP URL string
 	*/
 	toString(): string;
@@ -378,6 +422,14 @@ declare class FileTransportHandler implements TransportHandler {
 	* Delete file or directory
 	*/
 	delete(location: string): Promise<void>;
+	/**
+	* List directory contents
+	*/
+	list(location: string, options?: ListOptions): Promise<string[]>;
+	/**
+	* Create directory (recursively)
+	*/
+	mkdir(location: string): Promise<void>;
 }
 declare const fileTransport: FileTransportHandler;
 declare class HttpTransportHandler implements TransportHandler {
@@ -408,67 +460,6 @@ 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 RemoteRegistry
-	*/
-	private getRegistry;
-	/**
-	* 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;
@@ -498,4 +489,4 @@ declare class BinarySemanticHandler implements SemanticHandler<Buffer> {
 }
 declare const binarySemantic: BinarySemanticHandler;
 declare const VERSION: string;
-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 };
+export { textSemantic, httpsTransport, httpTransport, fileTransport, createARP, binarySemantic, VERSION, TransportResult, TransportParams, TransportHandler, TransportError, TextSemanticHandler, TextResource, SemanticHandler, SemanticError, SemanticContext, ResourceMeta, Resource, ParseError, ListOptions, HttpTransportHandler, FileTransportHandler, BinarySemanticHandler, BinaryResource, BinaryInput, ARPError, ARPConfig, ARP, ARL, ARI };