resourcexjs 2.5.0 → 2.5.2

package/README.md

@@ -1,6 +1,6 @@
 # resourcexjs
 
-ResourceX - Resource management protocol for AI Agents. Like npm for AI resources.
+Resource management protocol for AI Agents. Like npm for AI resources (prompts, tools, agents, configs).
 
 ## Installation
 
@@ -10,328 +10,459 @@ npm install resourcexjs
 bun add resourcexjs
 ```
 
+**Requirements:** Node.js 22+ or Bun
+
 ## Quick Start
 
 ```typescript
-import { createRegistry, parseRXL, createRXM, createRXA } from "resourcexjs";
+import { createResourceX } from "resourcexjs";
 
-// Create registry
-const registry = createRegistry();
+const rx = createResourceX();
 
-// Prepare a resource
-const manifest = createRXM({
-  name: "my-prompt",
-  type: "text",
-  version: "1.0.0",
-});
+// Add a resource from local directory
+await rx.add("./my-prompt");
 
-const rxr = {
-  locator: parseRXL(manifest.toLocator()),
-  manifest,
-  archive: await createRXA({ content: "You are a helpful assistant." }),
-};
+// Use and execute
+const result = await rx.use("my-prompt:1.0.0");
+const content = await result.execute();
+console.log(content);
+```
+
+## Core Concepts
 
-// Add to registry
-await registry.add(rxr);
+ResourceX uses four core primitives:
+
+| Primitive | Description                                         |
+| --------- | --------------------------------------------------- |
+| **RXL**   | Resource Locator - unique identifier for a resource |
+| **RXM**   | Resource Manifest - metadata (name, type, version)  |
+| **RXA**   | Resource Archive - content container (tar.gz)       |
+| **RXR**   | Resource - complete object (RXL + RXM + RXA)        |
+
+### Locator Format
+
+ResourceX uses a Docker-style locator format:
 
-// Resolve and execute
-const resolved = await registry.resolve("localhost/my-prompt.text@1.0.0");
-const text = await resolved.execute();
-console.log(text); // "You are a helpful assistant."
+```
+[registry/][path/]name[:tag]
 ```
 
-## Core Concepts
+- `name` - Resource name (required)
+- `tag` - Version or label (optional, defaults to "latest")
+- `registry` - Registry host (optional, e.g., `registry.example.com` or `localhost:3098`)
+- `path` - Path within registry (optional)
 
-### RXL - Resource Locator
+Examples:
 
-Parse resource locator strings. Format: `[domain/path/]name[.type][@version]`
+- `hello` - local resource with default tag "latest"
+- `hello:1.0.0` - local resource with version
+- `prompts/hello:1.0.0` - with path
+- `registry.example.com/hello:1.0.0` - remote resource
+- `localhost:3098/org/hello:latest` - with port and path
 
-```typescript
-import { parseRXL } from "resourcexjs";
+**Note:** The resource type (e.g., "text", "json") is specified in `resource.json`, not in the locator.
+
+### Resource Directory Structure
+
+A resource directory contains:
+
+```
+my-prompt/
+├── resource.json    # Resource metadata (required)
+└── content          # Resource content (required for text/json/binary)
+```
+
+Example `resource.json`:
+
+```json
+{
+  "name": "my-prompt",
+  "type": "text",
+  "tag": "1.0.0"
+}
+```
+
+### Storage Layout
 
-const rxl = parseRXL("deepractice.ai/sean/assistant.prompt@1.0.0");
+Resources are stored in `~/.resourcex/`:
 
-rxl.domain; // "deepractice.ai"
-rxl.path; // "sean"
-rxl.name; // "assistant"
-rxl.type; // "prompt"
-rxl.version; // "1.0.0"
-rxl.toString(); // reconstructs the locator
 ```
+~/.resourcex/
+├── local/              # Local resources (no registry)
+│   └── my-prompt/
+│       └── 1.0.0/
+│           ├── manifest.json
+│           └── archive.tar.gz
+├── cache/              # Cached remote resources
+│   └── registry.example.com/
+│       └── hello/
+│           └── 1.0.0/
+└── linked/             # Development symlinks
+    └── dev-prompt/
+        └── 1.0.0 -> /path/to/dev
+```
+
+## API Reference
 
-### RXM - Resource Manifest
+### createResourceX(config?)
 
-Create resource metadata:
+Create a ResourceX client instance.
 
 ```typescript
-import { createRXM } from "resourcexjs";
-
-const manifest = createRXM({
-  domain: "deepractice.ai", // optional, defaults to "localhost"
-  path: "sean", // optional
-  name: "assistant",
-  type: "prompt",
-  version: "1.0.0",
+import { createResourceX } from "resourcexjs";
+
+const rx = createResourceX({
+  path: "~/.resourcex", // Storage path (default: ~/.resourcex)
+  registry: "https://...", // Central registry URL (for push/pull)
+  types: [myCustomType], // Custom resource types
+  isolator: "none", // Sandbox: none | srt | cloudflare | e2b
 });
+```
+
+### Local Operations
+
+#### rx.add(path)
 
-manifest.toLocator(); // "deepractice.ai/sean/assistant.prompt@1.0.0"
-manifest.toJSON(); // plain object
+Add a resource from a local directory to local storage.
+
+```typescript
+const resource = await rx.add("./my-prompt");
+console.log(resource.locator); // "my-prompt:1.0.0"
 ```
 
-### RXA - Resource Archive
+#### rx.link(path)
 
-Archive container (tar.gz) for storage/transfer:
+Link a directory for live development (symlink). Changes to the directory are immediately available.
 
 ```typescript
-import { createRXA } from "resourcexjs";
+await rx.link("./dev-prompt");
+```
 
-// Single file
-const archive = await createRXA({ content: "Hello, World!" });
+#### rx.unlink(locator)
 
-// Multiple files
-const archive = await createRXA({
-  "index.ts": "export default 1",
-  "styles.css": "body {}",
-});
+Remove a development link.
 
-// Extract to package for file access
-const pkg = await archive.extract();
-const buffer = await pkg.file("content"); // Buffer
-const files = await pkg.files(); // Map<string, Buffer>
+```typescript
+await rx.unlink("dev-prompt:1.0.0");
+```
+
+#### rx.has(locator)
+
+Check if a resource exists locally.
 
-// Archive methods
-const tarGzBuffer = await archive.buffer();
-const stream = archive.stream;
+```typescript
+const exists = await rx.has("hello:1.0.0");
 ```
 
-### RXR - Resource
+#### rx.info(locator)
 
-Complete resource object (pure interface):
+Get detailed resource information.
 
 ```typescript
-import type { RXR } from "resourcexjs";
+const info = await rx.info("hello:1.0.0");
+console.log(info);
+// {
+//   locator: "hello:1.0.0",
+//   name: "hello",
+//   type: "text",
+//   tag: "1.0.0",
+//   files: ["content"]
+// }
+```
 
-const rxr: RXR = {
-  locator, // RXL
-  manifest, // RXM
-  archive, // RXA
-};
+#### rx.remove(locator)
+
+Remove a resource from local storage.
+
+```typescript
+await rx.remove("hello:1.0.0");
 ```
 
-### Registry
+#### rx.use(locator)
 
-Resource storage and retrieval:
+Load and prepare a resource for execution.
 
 ```typescript
-import { createRegistry, loadResource } from "resourcexjs";
+const executable = await rx.use<string>("hello:1.0.0");
 
-const registry = createRegistry({
-  path: "~/.resourcex", // optional
-  types: [customType], // optional, defaults to built-in types
-  isolator: "srt", // optional sandbox isolation
-});
+// Execute with optional arguments
+const content = await executable.execute();
 
-// Add from folder or RXR
-await registry.add("./my-prompt");
-await registry.add(rxr);
+// Access schema (if defined by the type)
+console.log(executable.schema);
+```
 
-// Link for development (symlink)
-await registry.link("./my-prompt");
+Resolution order:
 
-// Resolve and execute
-const resolved = await registry.resolve("localhost/my-prompt.text@1.0.0");
-const text = await resolved.execute();
+1. Linked directories (development priority)
+2. Local storage
+3. Cache (previously pulled)
+4. Remote registry (auto-pull if configured)
 
-// Get raw RXR
-const rxr = await registry.get("localhost/my-prompt.text@1.0.0");
+#### rx.search(query?)
 
-// Check existence
-const exists = await registry.exists("localhost/test.text@1.0.0");
+Search local resources.
 
-// Delete
-await registry.delete("localhost/test.text@1.0.0");
+```typescript
+// Search all
+const all = await rx.search();
 
-// Search
-const results = await registry.search({ query: "assistant", limit: 10 });
+// Search by keyword
+const results = await rx.search("prompt");
+// ["my-prompt:1.0.0", "system-prompt:2.0.0"]
 ```
 
-### Resource Types
+### Remote Operations
+
+#### rx.push(locator)
+
+Push a local resource to the remote registry.
 
-Built-in types:
+```typescript
+const rx = createResourceX({
+  registry: "https://registry.example.com",
+});
 
-| Type     | Aliases          | Description    |
-| -------- | ---------------- | -------------- |
-| `text`   | txt, plaintext   | Plain text     |
-| `json`   | config, manifest | JSON content   |
-| `binary` | bin, blob, raw   | Binary content |
+await rx.add("./my-prompt");
+await rx.push("my-prompt:1.0.0");
+```
 
-Custom types (requires bundling):
+#### rx.pull(locator)
+
+Pull a resource from the remote registry to local cache.
 
 ```typescript
-import { bundleResourceType, createRegistry } from "resourcexjs";
+await rx.pull("hello:1.0.0");
+// Resource is now cached locally
+```
+
+### Cache Operations
 
-// Bundle from source file
-const promptType = await bundleResourceType("./prompt.type.ts");
+#### rx.clearCache(registry?)
 
-// Create registry with type
-const registry = createRegistry({
-  types: [promptType],
+Clear cached resources.
+
+```typescript
+// Clear all cache
+await rx.clearCache();
+
+// Clear cache for specific registry
+await rx.clearCache("registry.example.com");
+```
+
+### Extension
+
+#### rx.supportType(type)
+
+Add support for a custom resource type.
+
+```typescript
+rx.supportType({
+  name: "prompt",
+  aliases: ["ai-prompt"],
+  description: "AI prompt template",
+  code: `({
+    async resolve(ctx) {
+      const template = new TextDecoder().decode(ctx.files["content"]);
+      return {
+        template,
+        render: (vars) => template.replace(/\\{\\{(\\w+)\\}\\}/g, (_, k) => vars[k])
+      };
+    }
+  })`,
 });
+
+const result = await rx.use("greeting:1.0.0");
+const { template, render } = await result.execute();
+console.log(render({ name: "World" }));
 ```
 
-### Load Resources
+## Built-in Types
+
+| Type     | Aliases          | Description        | Output       |
+| -------- | ---------------- | ------------------ | ------------ |
+| `text`   | txt, plaintext   | Plain text content | `string`     |
+| `json`   | config, manifest | JSON content       | `unknown`    |
+| `binary` | bin, blob, raw   | Binary content     | `Uint8Array` |
+
+## Core Primitives
 
-Load resources from folders:
+For advanced use cases, you can work with core primitives directly:
 
 ```typescript
-import { loadResource, FolderLoader } from "resourcexjs";
+import { parse, format, manifest, archive, resource, extract, wrap } from "resourcexjs";
 
-// Load from folder (uses FolderLoader by default)
-const rxr = await loadResource("./my-prompt");
+// Parse locator string to RXL
+const rxl = parse("hello:1.0.0");
+console.log(rxl.name); // "hello"
+console.log(rxl.tag); // "1.0.0"
 
-// Use custom loader
-const rxr = await loadResource("./my-prompt", {
-  loader: new CustomLoader(),
+// Format RXL back to string
+const str = format(rxl); // "hello:1.0.0"
+
+// Create manifest from definition
+const rxm = manifest({
+  name: "hello",
+  type: "text",
+  tag: "1.0.0",
 });
+
+// Create archive from files
+const rxa = await archive({
+  content: Buffer.from("Hello, World!"),
+});
+
+// Create complete resource
+const rxr = resource(rxm, rxa);
+
+// Extract files from archive
+const files = await extract(rxa); // Record<string, Buffer>
+
+// Wrap raw buffer as archive
+const wrapped = wrap(Buffer.from(tarGzData));
 ```
 
 ## ARP - Low-level I/O
 
-For direct file/network operations:
+ResourceX includes ARP (Agent Resource Protocol) for direct file/network operations:
 
 ```typescript
 import { createARP } from "resourcexjs/arp";
 
-// createARP() includes rxr transport for ResourceX resources
 const arp = createARP();
 
-// Parse URL
-const arl = arp.parse("arp:text:file://./config.txt");
+// File operations
+const fileArl = arp.parse("arp:text:file:///path/to/file.txt");
+const { content } = await fileArl.resolve();
+await fileArl.deposit("new content");
+await fileArl.exists();
+
+// HTTP operations
+const httpArl = arp.parse("arp:json:https://api.example.com/data");
+const { content: data } = await httpArl.resolve();
+
+// Access files inside resources (RXR transport)
+const rxrArl = arp.parse("arp:text:rxr://hello:1.0.0/content");
+const { content: fileContent } = await rxrArl.resolve();
+```
+
+## Configuration Options
+
+```typescript
+interface ResourceXConfig {
+  /**
+   * Base path for local storage.
+   * Default: ~/.resourcex
+   */
+  path?: string;
+
+  /**
+   * Central registry URL for push/pull operations.
+   */
+  registry?: string;
+
+  /**
+   * Custom resource types to register.
+   */
+  types?: BundledType[];
+
+  /**
+   * Isolator type for resolver execution.
+   * - "none": No isolation (default, fastest)
+   * - "srt": OS-level isolation
+   * - "cloudflare": Container isolation
+   * - "e2b": MicroVM isolation
+   */
+  isolator?: IsolatorType;
+}
+```
+
+## Types
 
-// Read
-const resource = await arl.resolve();
-console.log(resource.content); // string
+### Resource
 
-// Write
-await arl.deposit("hello world");
+User-facing resource object returned by `add()` and `info()`.
 
-// Operations
-await arl.exists(); // boolean
-await arl.delete();
+```typescript
+interface Resource {
+  locator: string; // Full locator string
+  registry?: string; // Registry host (if remote)
+  path?: string; // Path within registry
+  name: string; // Resource name
+  type: string; // Resource type
+  tag: string; // Version tag
+  files?: string[]; // Files in archive
+}
+```
+
+### Executable
 
-// Access files inside resources
-const rxrArl = arp.parse("arp:text:rxr://localhost/my-prompt.text@1.0.0/content");
-const { content } = await rxrArl.resolve();
+Result of `use()`.
+
+```typescript
+interface Executable<T = unknown> {
+  execute: (args?: unknown) => Promise<T>;
+  schema?: unknown; // JSON schema for arguments
+}
 ```
 
-## Exports
+### BundledType
 
-### Main Package (`resourcexjs`)
+Custom resource type definition.
 
 ```typescript
-// Errors
-export { ResourceXError, LocatorError, ManifestError, ContentError };
-export { ResourceTypeError };
-export { RegistryError };
-
-// RXL (Locator)
-export { parseRXL };
-export type { RXL };
-
-// RXM (Manifest)
-export { createRXM };
-export type { RXM, ManifestData };
-
-// RXA (Archive) and RXP (Package)
-export { createRXA };
-export type { RXA, RXP, RXAInput, PathNode };
-
-// RXR (Resource)
-export type { RXR };
-
-// Type System
-export type {
-  ResourceType,
-  ResourceResolver,
-  ResolvedResource,
-  JSONSchema,
-  BundledType,
-  IsolatorType,
-};
-export { TypeHandlerChain, bundleResourceType };
-export { textType, jsonType, binaryType, builtinTypes };
-
-// Resource Loading
-export type { ResourceLoader, LoadResourceConfig };
-export { loadResource, FolderLoader };
-
-// Registry
-export type {
-  Registry,
-  RegistryConfig,
-  ClientRegistryConfig,
-  ServerRegistryConfig,
-  CreateRegistryConfig,
-};
-export type { Storage, SearchOptions, DiscoveryResult, WellKnownResponse };
-export { DefaultRegistry, createRegistry, discoverRegistry, LocalStorage };
-
-// Middleware
-export { RegistryMiddleware, DomainValidation, withDomainValidation };
-
-// Version
-export const VERSION: string;
+interface BundledType {
+  name: string; // Type name
+  aliases?: string[]; // Alternative names
+  description: string; // Human-readable description
+  schema?: JSONSchema; // Schema for resolver arguments
+  code: string; // Bundled resolver code
+}
 ```
 
-### ARP Package (`resourcexjs/arp`)
+## Error Handling
 
 ```typescript
-// Enhanced createARP with RxrTransport
-export { createARP, ARP, type ARPConfig };
-export { VERSION };
-export { ARPError, ParseError, TransportError, SemanticError };
-export type { ARI, ARL };
-
-// Transports
-export type { TransportHandler, TransportResult, TransportParams };
-export { FileTransportHandler, fileTransport };
-export { HttpTransportHandler, httpTransport, httpsTransport };
-export { RxrTransport, clearRegistryCache, type RxrTransportRegistry };
-
-// Semantics
-export type { Resource, SemanticHandler, ResourceMeta, SemanticContext };
-export type { TextResource, BinaryResource, BinaryInput };
-export { TextSemanticHandler, textSemantic };
-export { BinarySemanticHandler, binarySemantic };
+import { RegistryError, ResourceTypeError } from "resourcexjs";
+
+try {
+  await rx.use("unknown:1.0.0");
+} catch (error) {
+  if (error instanceof RegistryError) {
+    console.error("Resource not found:", error.message);
+  }
+}
 ```
 
-## Error Hierarchy
+Error hierarchy:
 
 ```
-Error
-├── ResourceXError
-│   ├── LocatorError (RXL parsing)
-│   ├── ManifestError (RXM validation)
-│   └── ContentError (RXA/RXP operations)
-├── ResourceTypeError (Type registration)
-├── RegistryError (Registry operations)
-└── ARPError
-    ├── ParseError (URL parsing)
-    ├── TransportError (Transport operations)
-    └── SemanticError (Semantic operations)
+ResourceXError (base)
+├── LocatorError      # RXL parsing errors
+├── ManifestError     # RXM validation errors
+├── ContentError      # RXA operations errors
+└── DefinitionError   # RXD validation errors
+
+RegistryError         # Registry operations
+ResourceTypeError     # Type not found
+
+ARPError (base)
+├── ParseError        # URL parsing
+├── TransportError    # Transport operations
+└── SemanticError     # Semantic operations
 ```
 
-## Packages
+## Related Packages
 
-| Package                 | Description                   |
-| ----------------------- | ----------------------------- |
-| `resourcexjs`           | Main package (re-exports all) |
-| `@resourcexjs/core`     | RXL, RXM, RXA, RXP, RXR       |
-| `@resourcexjs/type`     | Type system, bundler          |
-| `@resourcexjs/loader`   | Resource loading              |
-| `@resourcexjs/registry` | Storage and retrieval         |
-| `@resourcexjs/arp`      | Low-level I/O protocol        |
+| Package                 | Description                            |
+| ----------------------- | -------------------------------------- |
+| `@resourcexjs/core`     | Core primitives (RXL, RXM, RXA, RXR)   |
+| `@resourcexjs/type`     | Type system and bundler                |
+| `@resourcexjs/storage`  | Storage layer (FileSystem, Memory)     |
+| `@resourcexjs/registry` | Registry layer (Local, Mirror, Linked) |
+| `@resourcexjs/loader`   | Resource loading utilities             |
+| `@resourcexjs/arp`      | Low-level I/O protocol                 |
 
 ## License
 
-MIT
+Apache-2.0