@resourcexjs/core 2.8.0 → 2.10.0

package/README.md

@@ -14,15 +14,16 @@ bun add @resourcexjs/core
 
 ## Core Concepts
 
-ResourceX uses a layered architecture with five core primitives:
+ResourceX uses a layered architecture with six core primitives:
 
 | Primitive | Description                                              |
 | --------- | -------------------------------------------------------- |
 | **RXD**   | Resource Definition - content of `resource.json`         |
-| **RXL**   | Resource Locator - unique identifier for a resource      |
+| **RXI**   | Resource Identifier - structured identifier `{ registry?, path?, name, tag }` |
+| **RXL**   | Resource Locator - unified locator string (RXI string, directory path, or URL) |
 | **RXM**   | Resource Manifest - metadata stored within the resource  |
 | **RXA**   | Resource Archive - tar.gz container for storage/transfer |
-| **RXR**   | Resource - complete resource (RXL + RXM + RXA)           |
+| **RXR**   | Resource - complete resource (RXI + RXM + RXA)           |
 
 ### Locator Format
 
@@ -38,14 +39,14 @@ registry.example.com/org/hello  -> registry=registry.example.com, path=org, name
 
 ## API
 
-### `parse(locator: string): RXL`
+### `parse(locator: string): RXI`
 
-Parse a locator string into an RXL object.
+Parse a locator string into an RXI object.
 
 ```typescript
 import { parse } from "@resourcexjs/core";
 
-const rxl = parse("registry.example.com/prompts/hello:1.0.0");
+const rxi = parse("registry.example.com/prompts/hello:1.0.0");
 // {
 //   registry: "registry.example.com",
 //   path: "prompts",
@@ -57,9 +58,9 @@ const simple = parse("hello");
 // { registry: undefined, path: undefined, name: "hello", tag: "latest" }
 ```
 
-### `format(rxl: RXL): string`
+### `format(rxi: RXI): string`
 
-Format an RXL object back to a locator string.
+Format an RXI object back to a locator string.
 
 ```typescript
 import { format } from "@resourcexjs/core";
@@ -121,14 +122,14 @@ const rxm = manifest(rxd);
 // { name: "my-prompt", type: "text", tag: "1.0.0" }
 ```
 
-### `locate(rxm: RXM): RXL`
+### `locate(rxm: RXM): RXI`
 
-Create a locator from a manifest.
+Create an identifier from a manifest.
 
 ```typescript
 import { locate } from "@resourcexjs/core";
 
-const rxl = locate({
+const rxi = locate({
   registry: "example.com",
   path: "prompts",
   name: "hello",
@@ -212,7 +213,7 @@ const rxm = manifest(rxd);
 const rxa = await archive({ content: Buffer.from("Hello!") });
 const rxr = resource(rxm, rxa);
 // {
-//   locator: { name: "hello", tag: "1.0.0" },
+//   identifier: { name: "hello", tag: "1.0.0" },
 //   manifest: { name: "hello", type: "text", tag: "1.0.0" },
 //   archive: RXA
 // }
@@ -240,12 +241,12 @@ interface RXD {
 }
 ```
 
-### RXL - Resource Locator
+### RXI - Resource Identifier
 
-Unique identifier for a resource.
+Structured identifier for a resource.
 
 ```typescript
-interface RXL {
+interface RXI {
   readonly registry?: string; // e.g., "localhost:3098", "registry.example.com"
   readonly path?: string; // e.g., "org", "prompts"
   readonly name: string; // Resource name
@@ -253,6 +254,14 @@ interface RXL {
 }
 ```
 
+### RXL - Resource Locator
+
+Unified locator string. Can be an RXI string, directory path, or URL.
+
+```typescript
+type RXL = string;
+```
+
 ### RXM - Resource Manifest
 
 Resource metadata stored within the resource.
@@ -281,11 +290,11 @@ interface RXA {
 
 ### RXR - Resource
 
-Complete resource object combining locator, manifest, and archive.
+Complete resource object combining identifier, manifest, and archive.
 
 ```typescript
 interface RXR {
-  readonly locator: RXL;
+  readonly identifier: RXI;
   readonly manifest: RXM;
   readonly archive: RXA;
 }
@@ -324,7 +333,7 @@ try {
 
 ```
 ResourceXError (base)
-├── LocatorError     - RXL parsing errors
+├── LocatorError     - RXI parsing errors
 ├── ManifestError    - RXM validation errors
 ├── ContentError     - RXA operations errors
 └── DefinitionError  - RXD validation errors
@@ -357,7 +366,7 @@ const rxa = await archive({
 const rxr: RXR = resource(rxm, rxa);
 
 // 5. Access locator string
-const locatorStr = format(rxr.locator);
+const locatorStr = format(rxr.identifier);
 console.log(locatorStr); // "assistant-prompt:1.0.0"
 
 // 6. Extract files when needed
@@ -381,13 +390,13 @@ const cas = new CASRegistry(new MemoryRXAStore(), new MemoryRXMStore());
 await cas.put(rxr);
 
 // Get a resource
-const rxr = await cas.get(rxl);
+const rxr = await cas.get(rxi);
 
 // Check existence
-const exists = await cas.has(rxl);
+const exists = await cas.has(rxi);
 
 // Remove a resource
-await cas.remove(rxl);
+await cas.remove(rxi);
 
 // List resources
 const results = await cas.list({ query: "prompt", limit: 10 });

package/dist/index.d.ts

@@ -51,9 +51,9 @@ declare function define(input: unknown): RXD;
 */
 declare function extract(rxa: RXA): Promise<Record<string, Buffer>>;
 /**
-* RXL - ResourceX Locator
+* RXI - ResourceX Identifier
 *
-* Unique identifier for a resource (pure data object).
+* Structured identifier for a resource (pure data object).
 * Docker-style format with optional tag.
 *
 * Format: [registry/][path/]name[:tag]
@@ -65,7 +65,7 @@ declare function extract(rxa: RXA): Promise<Record<string, Buffer>>;
 * - localhost:3098/hello:1.0.0 → registry=localhost:3098, name=hello, tag=1.0.0
 * - registry.example.com/org/hello:latest → registry=registry.example.com, path=org, name=hello, tag=latest
 */
-interface RXL {
+interface RXI {
 	/** Registry host:port (e.g., "localhost:3098", "registry.example.com") */
 	readonly registry?: string;
 	/** Path within registry (e.g., "org", "prompts") */
@@ -76,7 +76,7 @@ interface RXL {
 	readonly tag: string;
 }
 /**
-* Format RXL to locator string.
+* Format RXI to locator string.
 *
 * Docker-style format: [registry/][path/]name[:tag]
 *
@@ -85,40 +85,81 @@ interface RXL {
 * - { name: "hello", tag: "1.0.0" } → "hello:1.0.0"
 * - { registry: "localhost:3098", name: "hello", tag: "1.0.0" } → "localhost:3098/hello:1.0.0"
 *
-* @param rxl - Resource locator
+* @param rxi - Resource identifier
 * @returns Locator string
 */
-declare function format(rxl: RXL): string;
+declare function format(rxi: RXI): string;
 /**
 * RXM - ResourceX Manifest
 *
-* Resource metadata stored within the resource (pure data object).
+* Resource context representation organized by RX primitives.
+* Structure: definition (RXD) + archive (RXA) + source (RXS)
 */
-interface RXM {
-	readonly registry?: string;
-	readonly path?: string;
+/**
+* RXM Definition — what the resource IS.
+* Sourced from RXD (resource.json).
+*/
+interface RXMDefinition {
 	readonly name: string;
 	readonly type: string;
 	readonly tag: string;
-	readonly files?: string[];
+	readonly registry?: string;
+	readonly path?: string;
+	readonly description?: string;
+	readonly author?: string;
+	readonly license?: string;
+	readonly keywords?: string[];
+	readonly repository?: string;
+}
+/**
+* RXM Archive — packaging metadata.
+* Placeholder for future fields (digest, size, md5, etc.)
+*/
+type RXMArchive = {};
+/**
+* File entry with metadata.
+*/
+interface FileEntry {
+	readonly size: number;
 }
 /**
-* Create RXL from RXM.
+* Recursive file tree structure.
+* Keys ending with '/' are directories containing nested FileTree.
+* Other keys are files with FileEntry metadata.
+*/
+type FileTree = {
+	readonly [key: string]: FileEntry | FileTree
+};
+/**
+* RXM Source — what's IN the resource.
+* File structure and content preview.
+*/
+interface RXMSource {
+	readonly files?: FileTree;
+	readonly preview?: string;
+}
+interface RXM {
+	readonly definition: RXMDefinition;
+	readonly archive: RXMArchive;
+	readonly source: RXMSource;
+}
+/**
+* Create RXI from RXM.
 *
 * @param rxm - Resource manifest
-* @returns RXL locator object (pure data)
+* @returns RXI identifier object (pure data)
 */
-declare function locate(rxm: RXM): RXL;
+declare function locate(rxm: RXM): RXI;
 /**
 * Create RXM from RXD.
-* Extracts only the core metadata fields (pure data object).
+* Maps RXD fields into the structured RXM format.
 *
 * @param rxd - Resource definition
 * @returns RXM manifest object
 */
 declare function manifest(rxd: RXD): RXM;
 /**
-* Parse locator string to RXL.
+* Parse locator string to RXI.
 *
 * Docker-style format: [registry/][path/]name[:tag]
 *
@@ -129,17 +170,17 @@ declare function manifest(rxd: RXD): RXM;
 * - localhost:3098/hello:1.0.0 → registry=localhost:3098, name=hello, tag=1.0.0
 *
 * @param locator - Locator string
-* @returns RXL object
+* @returns RXI object
 * @throws LocatorError if parsing fails
 */
-declare function parse(locator: string): RXL;
+declare function parse(locator: string): RXI;
 /**
 * RXR - ResourceX Resource
 *
-* Complete resource object combining locator, manifest, and archive.
+* Complete resource object combining identifier, manifest, and archive.
 */
 interface RXR {
-	readonly locator: RXL;
+	readonly identifier: RXI;
 	readonly manifest: RXM;
 	readonly archive: RXA;
 }
@@ -152,6 +193,19 @@ interface RXR {
 */
 declare function resource(rxm: RXM, rxa: RXA): RXR;
 /**
+* RXL - ResourceX Locator
+*
+* Unified locator type for any resource reference.
+* An RXL can be:
+* - An RXI identifier string (e.g., "hello:1.0.0", "deepractice/skill-creator:0.1.0")
+* - A local directory path (e.g., "/home/user/skills/my-skill")
+* - A URL (e.g., "https://github.com/org/repo/tree/main/skills/my-skill")
+*
+* RXL is the input type for `ingest()` — the unified entry point that
+* accepts any form of resource reference and resolves it.
+*/
+type RXL = string;
+/**
 * RXS - ResourceX Source
 *
 * Intermediate representation of raw files from any source.
@@ -590,6 +644,11 @@ interface StoredRXM {
 	readonly name: string;
 	readonly type: string;
 	readonly tag: string;
+	readonly description?: string;
+	readonly author?: string;
+	readonly license?: string;
+	readonly keywords?: string[];
+	readonly repository?: string;
 	readonly files: Record<string, string>;
 	readonly createdAt?: Date;
 	readonly updatedAt?: Date;
@@ -773,10 +832,10 @@ interface SearchOptions {
 */
 interface Registry {
 	/**
-	* Get resource by locator.
+	* Get resource by identifier.
 	* @throws RegistryError if not found
 	*/
-	get(rxl: RXL): Promise<RXR>;
+	get(rxi: RXI): Promise<RXR>;
 	/**
 	* Store resource.
 	*/
@@ -784,26 +843,26 @@ interface Registry {
 	/**
 	* Check if resource exists.
 	*/
-	has(rxl: RXL): Promise<boolean>;
+	has(rxi: RXI): Promise<boolean>;
 	/**
 	* Delete resource.
 	*/
-	remove(rxl: RXL): Promise<void>;
+	remove(rxi: RXI): Promise<void>;
 	/**
 	* List resources matching options.
 	*/
-	list(options?: SearchOptions): Promise<RXL[]>;
+	list(options?: SearchOptions): Promise<RXI[]>;
 }
 declare class CASRegistry implements Registry {
 	private readonly rxaStore;
 	private readonly rxmStore;
 	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
 	private resolveTag;
-	get(rxl: RXL): Promise<RXR>;
+	get(rxi: RXI): Promise<RXR>;
 	put(rxr: RXR): Promise<void>;
-	has(rxl: RXL): Promise<boolean>;
-	remove(rxl: RXL): Promise<void>;
-	list(options?: SearchOptions): Promise<RXL[]>;
+	has(rxi: RXI): Promise<boolean>;
+	remove(rxi: RXI): Promise<void>;
+	list(options?: SearchOptions): Promise<RXI[]>;
 	/**
 	* Clear cached resources (resources with registry).
 	* @param registry - If provided, only clear resources from this registry
@@ -848,37 +907,37 @@ declare class LinkedRegistry implements Registry {
 	* Check if a path is a symlink.
 	*/
 	private isSymlink;
-	get(rxl: RXL): Promise<RXR>;
+	get(rxi: RXI): Promise<RXR>;
 	/**
 	* Put is not typically used for LinkedRegistry.
 	* Use link() instead to create symlinks.
 	*/
 	put(_rxr: RXR): Promise<void>;
-	has(rxl: RXL): Promise<boolean>;
-	remove(rxl: RXL): Promise<void>;
-	list(options?: SearchOptions): Promise<RXL[]>;
+	has(rxi: RXI): Promise<boolean>;
+	remove(rxi: RXI): Promise<void>;
+	list(options?: SearchOptions): Promise<RXI[]>;
 	/**
 	* Link a development directory.
 	* Creates a symlink so changes are reflected immediately.
 	*
 	* @param devPath - Path to development directory (must contain resource.json)
-	* @returns The RXL of the linked resource
+	* @returns The RXI of the linked resource
 	*/
-	link(devPath: string): Promise<RXL>;
+	link(devPath: string): Promise<RXI>;
 	/**
 	* Unlink a development directory.
 	* Alias for remove().
 	*/
-	unlink(rxl: RXL): Promise<void>;
+	unlink(rxi: RXI): Promise<void>;
 	/**
 	* Recursively scan for symlinks.
 	*/
 	private scanSymlinks;
 	/**
-	* Parse relative path to RXL.
+	* Parse relative path to RXI.
 	* Path format: {registry}/{path}/{name}/{tag}
 	*/
-	private parsePathToRXL;
+	private parsePathToRXI;
 }
 /**
 * Base class for Registry middleware.
@@ -888,11 +947,11 @@ declare class LinkedRegistry implements Registry {
 declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
-	get(rxl: RXL): Promise<RXR>;
+	get(rxi: RXI): Promise<RXR>;
 	put(rxr: RXR): Promise<void>;
-	has(rxl: RXL): Promise<boolean>;
-	remove(rxl: RXL): Promise<void>;
-	list(options?: SearchOptions): Promise<RXL[]>;
+	has(rxi: RXI): Promise<boolean>;
+	remove(rxi: RXI): Promise<void>;
+	list(options?: SearchOptions): Promise<RXI[]>;
 }
 /**
 * Registry validation middleware.
@@ -908,7 +967,7 @@ declare class RegistryValidation extends RegistryMiddleware {
 	/**
 	* Get resource and validate registry.
 	*/
-	get(rxl: RXL): Promise<RXR>;
+	get(rxi: RXI): Promise<RXR>;
 }
 /**
 * Factory function to create registry validation middleware.
@@ -1196,4 +1255,4 @@ declare class TypeHandlerChain {
 	*/
 	clear(): void;
 }
-export { wrap, withDomainValidation, textType, resource, resolveSource, parse, manifest, locate, loadResource, jsonType, isValidDigest, generateDefinition, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, TypeDetectorChain, TypeDetector, TypeDetectionResult, StoredRXM, SourceLoaderChain, SourceLoader, SkillDetector, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResourceJsonDetector, ResolvedResource, ResolveSourceConfig, ResolveContext, RegistryMiddleware, RegistryError, Registry, RXS, RXR, RXMStore, RXMSearchOptions, RXM, RXL, RXD, RXAStore, RXA, ProviderStores, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, GitHubSourceLoader, FolderSourceLoader, FolderLoader, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };
+export { wrap, withDomainValidation, textType, resource, resolveSource, parse, manifest, locate, loadResource, jsonType, isValidDigest, generateDefinition, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, TypeDetectorChain, TypeDetector, TypeDetectionResult, StoredRXM, SourceLoaderChain, SourceLoader, SkillDetector, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResourceJsonDetector, ResolvedResource, ResolveSourceConfig, ResolveContext, RegistryMiddleware, RegistryError, Registry, RXS, RXR, RXMStore, RXMSource, RXMSearchOptions, RXMDefinition, RXMArchive, RXM, RXL, RXI, RXD, RXAStore, RXA, ProviderStores, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, GitHubSourceLoader, FolderSourceLoader, FolderLoader, FileTree, FileEntry, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };