@resourcexjs/arp 1.7.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

@@ -455,10 +455,14 @@ declare class RxrTransport implements TransportHandler {
 	* 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
+	* - 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

package/dist/index.js

@@ -282,9 +282,16 @@ import { join as join2 } from "node:path";
 import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, rm as rm2, stat as stat2, readdir as readdir2 } from "node:fs/promises";
 import { gzip as gzip2, gunzip as gunzip2 } from "node:zlib";
 import { promisify as promisify2 } from "node:util";
+import { homedir as homedir2 } from "node:os";
+import { join as join22 } from "node:path";
+import { readFile as readFile22, stat as stat22, readdir as readdir22, mkdir as mkdir22 } from "node:fs/promises";
+import { execSync } from "node:child_process";
 function isRemoteConfig(config) {
   return config !== undefined && "endpoint" in config;
 }
+function isGitConfig(config) {
+  return config !== undefined && "type" in config && config.type === "git";
+}
 
 class ResourceXError extends Error {
   constructor(message, options) {
@@ -1754,23 +1761,63 @@ class LocalRegistry {
   supportType(type) {
     this.typeHandler.register(type);
   }
-  buildPath(locator) {
+  buildPath(locator, area) {
     const rxl = typeof locator === "string" ? parseRXL(locator) : locator;
-    const domain = rxl.domain ?? "localhost";
+    const resourceName = rxl.type ? `${rxl.name}.${rxl.type}` : rxl.name;
     const version = rxl.version ?? "latest";
-    let path = join2(this.basePath, domain);
-    if (rxl.path) {
-      path = join2(path, rxl.path);
+    if (area === "local") {
+      return join2(this.basePath, "local", resourceName, version);
+    } else {
+      const domain = rxl.domain ?? "localhost";
+      let path = join2(this.basePath, "cache", domain);
+      if (rxl.path) {
+        path = join2(path, rxl.path);
+      }
+      return join2(path, resourceName, version);
     }
-    const resourceName = rxl.type ? `${rxl.name}.${rxl.type}` : rxl.name;
-    return join2(path, resourceName, version);
   }
-  async publish(_resource) {
-    throw new RegistryError("Remote publish not implemented yet");
+  isLocalOnlyLocator(locator) {
+    const rxl = typeof locator === "string" ? parseRXL(locator) : locator;
+    return !rxl.domain || rxl.domain === "localhost";
+  }
+  async existsAt(resourcePath) {
+    const manifestPath = join2(resourcePath, "manifest.json");
+    try {
+      await stat2(manifestPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async findArea(locator) {
+    const localPath = this.buildPath(locator, "local");
+    if (await this.existsAt(localPath)) {
+      return "local";
+    }
+    const cachePath = this.buildPath(locator, "cache");
+    if (await this.existsAt(cachePath)) {
+      return "cache";
+    }
+    return null;
+  }
+  async loadFrom(resourcePath) {
+    const manifestPath = join2(resourcePath, "manifest.json");
+    const manifestContent = await readFile2(manifestPath, "utf-8");
+    const manifestData = JSON.parse(manifestContent);
+    const manifest = createRXM(manifestData);
+    const contentPath = join2(resourcePath, "content.tar.gz");
+    const data = await readFile2(contentPath);
+    return this.typeHandler.deserialize(data, manifest);
+  }
+  async pull(_locator, _options) {
+    throw new RegistryError("Pull not implemented yet - see issue #018");
+  }
+  async publish(_resource, _options) {
+    throw new RegistryError("Publish not implemented yet - see issue #018");
   }
   async link(resource) {
     const locator = resource.manifest.toLocator();
-    const resourcePath = this.buildPath(locator);
+    const resourcePath = this.buildPath(locator, "local");
     await mkdir2(resourcePath, { recursive: true });
     const manifestPath = join2(resourcePath, "manifest.json");
     await writeFile2(manifestPath, JSON.stringify(resource.manifest.toJSON(), null, 2), "utf-8");
@@ -1779,58 +1826,62 @@ class LocalRegistry {
     await writeFile2(contentPath, serialized);
   }
   async get(locator) {
-    if (!await this.exists(locator)) {
+    const area = await this.findArea(locator);
+    if (!area) {
       throw new RegistryError(`Resource not found: ${locator}`);
     }
-    const resourcePath = this.buildPath(locator);
-    const manifestPath = join2(resourcePath, "manifest.json");
-    const manifestContent = await readFile2(manifestPath, "utf-8");
-    const manifestData = JSON.parse(manifestContent);
-    const manifest = createRXM(manifestData);
-    const contentPath = join2(resourcePath, "content.tar.gz");
-    const data = await readFile2(contentPath);
-    return this.typeHandler.deserialize(data, manifest);
+    const resourcePath = this.buildPath(locator, area);
+    return this.loadFrom(resourcePath);
   }
   async resolve(locator) {
     const rxr = await this.get(locator);
     return this.typeHandler.resolve(rxr);
   }
   async exists(locator) {
-    const resourcePath = this.buildPath(locator);
-    const manifestPath = join2(resourcePath, "manifest.json");
-    try {
-      await stat2(manifestPath);
-      return true;
-    } catch {
-      return false;
-    }
+    const area = await this.findArea(locator);
+    return area !== null;
   }
   async delete(locator) {
-    if (!await this.exists(locator)) {
-      return;
+    const isLocal = this.isLocalOnlyLocator(locator);
+    if (isLocal) {
+      const localPath = this.buildPath(locator, "local");
+      if (await this.existsAt(localPath)) {
+        await rm2(localPath, { recursive: true, force: true });
+      }
+    } else {
+      const cachePath = this.buildPath(locator, "cache");
+      if (await this.existsAt(cachePath)) {
+        await rm2(cachePath, { recursive: true, force: true });
+      }
     }
-    const resourcePath = this.buildPath(locator);
-    await rm2(resourcePath, { recursive: true, force: true });
   }
   async search(options) {
     const { query, limit, offset = 0 } = options ?? {};
-    let entries;
-    try {
-      entries = await this.listRecursive(this.basePath);
-    } catch {
-      return [];
-    }
     const locators = [];
-    for (const entry of entries) {
-      if (!entry.endsWith("manifest.json")) {
-        continue;
+    const localDir = join2(this.basePath, "local");
+    try {
+      const localEntries = await this.listRecursive(localDir);
+      for (const entry of localEntries) {
+        if (!entry.endsWith("manifest.json"))
+          continue;
+        const relativePath = entry.slice(localDir.length + 1);
+        const rxl = this.parseLocalEntry(relativePath);
+        if (rxl)
+          locators.push(rxl);
       }
-      const relativePath = entry.slice(this.basePath.length + 1);
-      const rxl = this.parseEntryToRXL(relativePath);
-      if (rxl) {
-        locators.push(rxl);
+    } catch {}
+    const cacheDir = join2(this.basePath, "cache");
+    try {
+      const cacheEntries = await this.listRecursive(cacheDir);
+      for (const entry of cacheEntries) {
+        if (!entry.endsWith("manifest.json"))
+          continue;
+        const relativePath = entry.slice(cacheDir.length + 1);
+        const rxl = this.parseCacheEntry(relativePath);
+        if (rxl)
+          locators.push(rxl);
       }
-    }
+    } catch {}
     let filtered = locators;
     if (query) {
       const lowerQuery = query.toLowerCase();
@@ -1861,7 +1912,27 @@ class LocalRegistry {
     } catch {}
     return results;
   }
-  parseEntryToRXL(entry) {
+  parseLocalEntry(entry) {
+    const dirPath = entry.replace(/[/\\]manifest\.json$/, "");
+    const parts = dirPath.split(/[/\\]/);
+    if (parts.length < 2) {
+      return null;
+    }
+    const version = parts.pop();
+    const nameTypePart = parts.shift();
+    const { name, type } = this.parseNameType(nameTypePart);
+    let locatorStr = name;
+    if (type) {
+      locatorStr += `.${type}`;
+    }
+    locatorStr += `@${version}`;
+    try {
+      return parseRXL(locatorStr);
+    } catch {
+      return null;
+    }
+  }
+  parseCacheEntry(entry) {
     const dirPath = entry.replace(/[/\\]manifest\.json$/, "");
     const parts = dirPath.split(/[/\\]/);
     if (parts.length < 3) {
@@ -1871,16 +1942,7 @@ class LocalRegistry {
     const nameTypePart = parts.pop();
     const domain = parts.shift();
     const path = parts.length > 0 ? parts.join("/") : undefined;
-    const dotIndex = nameTypePart.lastIndexOf(".");
-    let name;
-    let type;
-    if (dotIndex !== -1) {
-      name = nameTypePart.substring(0, dotIndex);
-      type = nameTypePart.substring(dotIndex + 1);
-    } else {
-      name = nameTypePart;
-      type = undefined;
-    }
+    const { name, type } = this.parseNameType(nameTypePart);
     let locatorStr = domain;
     if (path) {
       locatorStr += `/${path}`;
@@ -1896,6 +1958,17 @@ class LocalRegistry {
       return null;
     }
   }
+  parseNameType(nameTypePart) {
+    const dotIndex = nameTypePart.lastIndexOf(".");
+    if (dotIndex !== -1) {
+      return {
+        name: nameTypePart.substring(0, dotIndex),
+        type: nameTypePart.substring(dotIndex + 1)
+      };
+    } else {
+      return { name: nameTypePart, type: undefined };
+    }
+  }
 }
 
 class RemoteRegistry {
@@ -1908,7 +1981,10 @@ class RemoteRegistry {
   supportType(type) {
     this.typeHandler.register(type);
   }
-  async publish(_resource) {
+  async pull(_locator, _options) {
+    throw new RegistryError("Cannot pull to remote registry - use local registry for pulling");
+  }
+  async publish(_resource, _options) {
     throw new RegistryError("Remote registry publish not implemented yet");
   }
   async link(_resource) {
@@ -1974,7 +2050,13 @@ async function discoverRegistry(domain) {
       throw new RegistryError(`Well-known discovery failed for ${domain}: ${response.statusText}`);
     }
     const data = await response.json();
-    return data.registry;
+    if (!data.registries || !Array.isArray(data.registries) || data.registries.length === 0) {
+      throw new RegistryError(`Invalid well-known response for ${domain}: missing or empty registries`);
+    }
+    return {
+      domain,
+      registries: data.registries
+    };
   } catch (error) {
     if (error instanceof RegistryError) {
       throw error;
@@ -1982,10 +2064,210 @@ async function discoverRegistry(domain) {
     throw new RegistryError(`Failed to discover registry for ${domain}: ${error.message}`);
   }
 }
+var DEFAULT_GIT_CACHE = `${homedir2()}/.resourcex/.git-cache`;
+
+class GitRegistry {
+  url;
+  ref;
+  basePath;
+  cacheDir;
+  typeHandler;
+  trustedDomain;
+  constructor(config) {
+    this.url = config.url;
+    this.ref = config.ref ?? "main";
+    this.basePath = config.basePath ?? ".resourcex";
+    this.typeHandler = TypeHandlerChain.create();
+    this.trustedDomain = config.domain;
+    if (this.isRemoteUrl(config.url) && !config.domain) {
+      throw new RegistryError(`Remote git registry requires a trusted domain.
+
+` + `Either:
+` + `1. Use discoverRegistry("your-domain.com") to auto-bind domain
+` + `2. Explicitly set domain: createRegistry({ type: "git", url: "...", domain: "your-domain.com" })
+
+` + `This ensures resources from untrusted sources cannot impersonate your domain.`);
+    }
+    this.cacheDir = this.buildCacheDir(config.url);
+  }
+  isRemoteUrl(url) {
+    return url.startsWith("git@") || url.startsWith("https://") || url.startsWith("http://");
+  }
+  buildCacheDir(url) {
+    let normalized = url;
+    if (url.startsWith("git@")) {
+      normalized = url.slice(4).replace(":", "/");
+    }
+    if (normalized.endsWith(".git")) {
+      normalized = normalized.slice(0, -4);
+    }
+    const dirName = normalized.replace(/\//g, "-");
+    return join22(DEFAULT_GIT_CACHE, dirName);
+  }
+  supportType(type) {
+    this.typeHandler.register(type);
+  }
+  async ensureCloned() {
+    const gitDir = join22(this.cacheDir, ".git");
+    try {
+      await stat22(gitDir);
+      this.gitExec(`fetch origin ${this.ref}`);
+      this.gitExec(`checkout FETCH_HEAD`);
+    } catch {
+      await mkdir22(DEFAULT_GIT_CACHE, { recursive: true });
+      execSync(`git clone --depth 1 --branch ${this.ref} ${this.url} ${this.cacheDir}`, {
+        stdio: "pipe"
+      });
+    }
+  }
+  gitExec(command) {
+    execSync(`git -C ${this.cacheDir} ${command}`, { stdio: "pipe" });
+  }
+  buildResourcePath(locator) {
+    const rxl = parseRXL(locator);
+    const domain = rxl.domain ?? "localhost";
+    const version = rxl.version ?? "latest";
+    let path = join22(this.cacheDir, this.basePath, domain);
+    if (rxl.path) {
+      path = join22(path, rxl.path);
+    }
+    const resourceName = rxl.type ? `${rxl.name}.${rxl.type}` : rxl.name;
+    return join22(path, resourceName, version);
+  }
+  async get(locator) {
+    await this.ensureCloned();
+    const resourcePath = this.buildResourcePath(locator);
+    const manifestPath = join22(resourcePath, "manifest.json");
+    try {
+      await stat22(manifestPath);
+    } catch {
+      throw new RegistryError(`Resource not found: ${locator}`);
+    }
+    const manifestContent = await readFile22(manifestPath, "utf-8");
+    const manifestData = JSON.parse(manifestContent);
+    const manifest = createRXM(manifestData);
+    if (this.trustedDomain && manifest.domain !== this.trustedDomain) {
+      throw new RegistryError(`Untrusted domain: resource claims "${manifest.domain}" but registry only trusts "${this.trustedDomain}"`);
+    }
+    const contentPath = join22(resourcePath, "content.tar.gz");
+    const data = await readFile22(contentPath);
+    return this.typeHandler.deserialize(data, manifest);
+  }
+  async resolve(locator) {
+    const rxr = await this.get(locator);
+    return this.typeHandler.resolve(rxr);
+  }
+  async exists(locator) {
+    try {
+      await this.ensureCloned();
+      const resourcePath = this.buildResourcePath(locator);
+      const manifestPath = join22(resourcePath, "manifest.json");
+      await stat22(manifestPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async search(options) {
+    await this.ensureCloned();
+    const { query, limit, offset = 0 } = options ?? {};
+    const locators = [];
+    const baseDir = join22(this.cacheDir, this.basePath);
+    try {
+      const entries = await this.listRecursive(baseDir);
+      for (const entry of entries) {
+        if (!entry.endsWith("manifest.json"))
+          continue;
+        const relativePath = entry.slice(baseDir.length + 1);
+        const rxl = this.parseEntryToRXL(relativePath);
+        if (rxl)
+          locators.push(rxl);
+      }
+    } catch {
+      return [];
+    }
+    let filtered = locators;
+    if (query) {
+      const lowerQuery = query.toLowerCase();
+      filtered = locators.filter((rxl) => {
+        const searchText = `${rxl.domain ?? ""} ${rxl.path ?? ""} ${rxl.name} ${rxl.type ?? ""}`.toLowerCase();
+        return searchText.includes(lowerQuery);
+      });
+    }
+    let result = filtered.slice(offset);
+    if (limit !== undefined) {
+      result = result.slice(0, limit);
+    }
+    return result;
+  }
+  async listRecursive(dir) {
+    const results = [];
+    try {
+      const entries = await readdir22(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join22(dir, entry.name);
+        if (entry.isDirectory()) {
+          const subEntries = await this.listRecursive(fullPath);
+          results.push(...subEntries);
+        } else {
+          results.push(fullPath);
+        }
+      }
+    } catch {}
+    return results;
+  }
+  parseEntryToRXL(entry) {
+    const dirPath = entry.replace(/[/\\]manifest\.json$/, "");
+    const parts = dirPath.split(/[/\\]/);
+    if (parts.length < 3)
+      return null;
+    const version = parts.pop();
+    const nameTypePart = parts.pop();
+    const domain = parts.shift();
+    const path = parts.length > 0 ? parts.join("/") : undefined;
+    const dotIndex = nameTypePart.lastIndexOf(".");
+    let name;
+    let type;
+    if (dotIndex !== -1) {
+      name = nameTypePart.substring(0, dotIndex);
+      type = nameTypePart.substring(dotIndex + 1);
+    } else {
+      name = nameTypePart;
+      type = undefined;
+    }
+    let locatorStr = domain;
+    if (path)
+      locatorStr += `/${path}`;
+    locatorStr += `/${name}`;
+    if (type)
+      locatorStr += `.${type}`;
+    locatorStr += `@${version}`;
+    try {
+      return parseRXL(locatorStr);
+    } catch {
+      return null;
+    }
+  }
+  async pull(_locator, _options) {
+    throw new RegistryError("GitRegistry is read-only - use LocalRegistry.pull()");
+  }
+  async publish(_resource, _options) {
+    throw new RegistryError("GitRegistry is read-only - use LocalRegistry.publish()");
+  }
+  async link(_resource) {
+    throw new RegistryError("GitRegistry is read-only - use LocalRegistry.link()");
+  }
+  async delete(_locator) {
+    throw new RegistryError("GitRegistry is read-only - use LocalRegistry.delete()");
+  }
+}
 function createRegistry(config) {
   if (isRemoteConfig(config)) {
     return new RemoteRegistry(config);
   }
+  if (isGitConfig(config)) {
+    return new GitRegistry(config);
+  }
   return new LocalRegistry(config);
 }
 
@@ -2041,8 +2323,17 @@ class RxrTransport {
       registry = createRegistry();
     } else {
       try {
-        const endpoint = await discoverRegistry(domain);
-        registry = createRegistry({ endpoint });
+        const discovery = await discoverRegistry(domain);
+        const registryUrl = discovery.registries[0];
+        if (this.isGitUrl(registryUrl)) {
+          registry = createRegistry({
+            type: "git",
+            url: registryUrl,
+            domain: discovery.domain
+          });
+        } else {
+          registry = createRegistry({ endpoint: registryUrl });
+        }
       } catch (error) {
         throw new TransportError(`Failed to discover registry for domain ${domain}: ${error.message}`, this.name);
       }
@@ -2050,6 +2341,9 @@ class RxrTransport {
     registryCache.set(domain, registry);
     return registry;
   }
+  isGitUrl(url) {
+    return url.startsWith("git@") || url.endsWith(".git");
+  }
   parseLocation(location) {
     const atIndex = location.indexOf("@");
     if (atIndex === -1) {
@@ -2270,7 +2564,7 @@ function createARP(config) {
 }
 
 // src/index.ts
-var VERSION = "1.7.0";
+var VERSION = "2.0.0";
 export {
   textSemantic,
   httpsTransport,
@@ -2292,4 +2586,4 @@ export {
   ARP
 };
 
-//# debugId=A454D6FE1CE0DCC764756E2164756E21
+//# debugId=1847C08CED2B25BC64756E2164756E21