@resourcexjs/registry 2.1.1 → 2.3.0

package/README.md

@@ -66,7 +66,7 @@ const rxr = await loadResource("./my-prompt");
 
 // Link to registry
 const registry = createRegistry();
-await registry.link(rxr);
+await registry.add(rxr);
 
 // Now available at: ~/.resourcex/localhost/my-prompt.text@1.0.0/
 ```
@@ -135,7 +135,7 @@ Link a resource to local registry.
 - `resource: RXR` - Complete resource object
 
 ```typescript
-await registry.link(rxr);
+await registry.add(rxr);
 ```
 
 #### `resolve(locator: string): Promise<RXR>`
@@ -358,7 +358,7 @@ const rxr = await loadResource("./my-prompts/assistant");
 const registry = createRegistry();
 
 // 3. Link to local registry
-await registry.link(rxr);
+await registry.add(rxr);
 
 // 4. Resolve later
 const resolved = await registry.resolve("localhost/assistant.prompt@1.0.0");
@@ -374,9 +374,9 @@ console.log(text);
 const registry = createRegistry();
 
 // Link multiple versions
-await registry.link(promptV1); // v1.0.0
-await registry.link(promptV2); // v2.0.0
-await registry.link(promptV3); // v3.0.0
+await registry.add(promptV1); // v1.0.0
+await registry.add(promptV2); // v2.0.0
+await registry.add(promptV3); // v3.0.0
 
 // Resolve specific version
 const v1 = await registry.resolve("localhost/prompt.text@1.0.0");
@@ -392,7 +392,7 @@ const registry = createRegistry({
   path: "./project-registry",
 });
 
-await registry.link(rxr);
+await registry.add(rxr);
 // Stored at: ./project-registry/localhost/...
 ```
 
@@ -406,9 +406,9 @@ const registry = createRegistry({
 });
 
 // Now can handle these custom types
-await registry.link(promptResource);
-await registry.link(toolResource);
-await registry.link(agentResource);
+await registry.add(promptResource);
+await registry.add(toolResource);
+await registry.add(agentResource);
 ```
 
 ## Resolution Strategy

package/dist/index.d.ts

@@ -46,6 +46,44 @@ interface GitRegistryConfig {
 	domain?: string;
 }
 /**
+* GitHub registry configuration (internal).
+* Uses GitHub's archive API to download tarball (faster than git clone).
+*/
+interface GitHubRegistryConfig {
+	type: "github";
+	/** GitHub repository URL (format: https://github.com/owner/repo) */
+	url: string;
+	/** Git ref (branch, tag, or commit). Default: "main" */
+	ref?: string;
+	/** Base path in repo for resources. Default: ".resourcex" */
+	basePath?: string;
+	/**
+	* Trusted domain for this registry.
+	* If set, only resources with this domain in manifest are allowed.
+	*/
+	domain?: string;
+}
+/**
+* URL-based registry configuration.
+* Auto-detects registry type based on URL format:
+* - https://github.com/... → GitHubRegistry (tarball download)
+* - git@... or *.git → GitRegistry (git clone)
+* - https://... (other) → RemoteRegistry (HTTP API)
+*/
+interface UrlRegistryConfig {
+	/** Registry URL - type is auto-detected */
+	url: string;
+	/** Git ref (branch, tag, or commit). Default: "main" */
+	ref?: string;
+	/** Base path in repo for resources. Default: ".resourcex" */
+	basePath?: string;
+	/**
+	* Trusted domain for this registry.
+	* Required for remote URLs (security).
+	*/
+	domain?: string;
+}
+/**
 * Well-known discovery response format.
 * Used by discoverRegistry() to find registry for a domain.
 */
@@ -68,17 +106,9 @@ interface DiscoveryResult {
 	registries: string[];
 }
 /**
-* Registry configuration - local, remote, or git.
+* Registry configuration - local, remote, git, github, or URL-based.
 */
-type RegistryConfig = LocalRegistryConfig | RemoteRegistryConfig | GitRegistryConfig;
-/**
-* Type guard to check if config is for remote registry.
-*/
-declare function isRemoteConfig(config?: RegistryConfig): config is RemoteRegistryConfig;
-/**
-* Type guard to check if config is for git registry.
-*/
-declare function isGitConfig(config?: RegistryConfig): config is GitRegistryConfig;
+type RegistryConfig = LocalRegistryConfig | RemoteRegistryConfig | GitRegistryConfig | GitHubRegistryConfig | UrlRegistryConfig;
 /**
 * Search options for querying resources.
 */
@@ -136,6 +166,18 @@ interface Registry {
 	*/
 	supportType(type: ResourceType): void;
 	/**
+	* Link a development directory to local registry.
+	* Creates a symlink so changes are reflected immediately.
+	* @param path - Path to resource directory (must contain resource.json)
+	*/
+	link(path: string): Promise<void>;
+	/**
+	* Add resource to local registry.
+	* Copies resource content to local storage.
+	* @param source - Resource directory path or RXR object
+	*/
+	add(source: string | RXR): Promise<void>;
+	/**
 	* Pull resource from remote registry to local cache.
 	* Discovers remote registry via well-known and caches locally.
 	* @param locator - Resource locator (must include domain)
@@ -144,15 +186,10 @@ interface Registry {
 	pull(locator: string, options?: PullOptions): Promise<void>;
 	/**
 	* Publish resource to remote registry.
-	* Resource must exist in local first.
-	* @param resource - Resource to publish
-	* @param options - Publish target configuration
+	* @param source - Resource directory path or RXR object
+	* @param options - Publish target configuration (required)
 	*/
-	publish(resource: RXR, options: PublishOptions): Promise<void>;
-	/**
-	* Link resource to local registry (for development/caching).
-	*/
-	link(resource: RXR): Promise<void>;
+	publish(source: string | RXR, options: PublishOptions): Promise<void>;
 	/**
 	* Get raw resource by locator string.
 	* Returns the RXR (locator + manifest + content) without resolving.
@@ -231,12 +268,18 @@ declare class LocalRegistry implements Registry {
 	*/
 	private findArea;
 	/**
+	* Check if a path is a symlink.
+	*/
+	private isSymlink;
+	/**
 	* Load resource from a specific path.
+	* If path is a symlink, loads from the linked directory using FolderLoader.
 	*/
 	private loadFrom;
+	link(path: string): Promise<void>;
+	add(source: string | RXR2): Promise<void>;
 	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_resource: RXR2, _options: PublishOptions): Promise<void>;
-	link(resource: RXR2): Promise<void>;
+	publish(_source: string | RXR2, _options: PublishOptions): Promise<void>;
 	get(locator: string): Promise<RXR2>;
 	resolve<
 		TArgs = void,
@@ -260,113 +303,42 @@ declare class LocalRegistry implements Registry {
 	*/
 	private parseNameType;
 }
-import { RXR as RXR3, RXL as RXL3 } from "@resourcexjs/core";
-import { ResourceType as ResourceType3, ResolvedResource as ResolvedResource3 } from "@resourcexjs/type";
-/**
-* Remote registry implementation.
-* Uses HTTP API for resource access.
-*/
-declare class RemoteRegistry implements Registry {
-	private readonly endpoint;
-	private readonly typeHandler;
-	constructor(config: RemoteRegistryConfig);
-	supportType(type: ResourceType3): void;
-	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_resource: RXR3, _options: PublishOptions): Promise<void>;
-	link(_resource: RXR3): Promise<void>;
-	get(locator: string): Promise<RXR3>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource3<TArgs, TResult>>;
-	exists(locator: string): Promise<boolean>;
-	delete(_locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL3[]>;
-}
 /**
 * Discover registry for a domain using well-known.
 * @param domain - The domain to discover (e.g., "deepractice.ai")
 * @returns Discovery result with domain and authorized registries
 */
 declare function discoverRegistry(domain: string): Promise<DiscoveryResult>;
-import { RXR as RXR4, RXL as RXL4 } from "@resourcexjs/core";
-import { ResourceType as ResourceType4, ResolvedResource as ResolvedResource4 } from "@resourcexjs/type";
-declare class GitRegistry implements Registry {
-	private readonly url;
-	private readonly ref;
-	private readonly basePath;
-	private readonly cacheDir;
-	private readonly typeHandler;
-	private readonly arp;
-	private readonly isLocal;
-	constructor(config: GitRegistryConfig);
-	/**
-	* Build cache directory name from git URL.
-	* git@github.com:Deepractice/Registry.git → github.com-Deepractice-Registry
-	*/
-	private buildCacheDir;
-	supportType(type: ResourceType4): void;
-	/**
-	* Create ARP URL for a file path.
-	*/
-	private toArpUrl;
-	/**
-	* Ensure the repository is cloned and up to date.
-	* For local paths, just verify the .git directory exists.
-	* For remote URLs, includes retry logic for transient network errors.
-	*/
-	private ensureCloned;
-	/**
-	* Get the default branch name (main or master).
-	*/
-	private getDefaultBranch;
-	/**
-	* Build filesystem path for a resource in the cloned repo.
-	* Path structure: {cacheDir}/{basePath}/{domain}/{path}/{name}.{type}/{version}
-	*/
-	private buildResourcePath;
-	get(locator: string): Promise<RXR4>;
-	resolve<
-		TArgs = void,
-		TResult = unknown
-	>(locator: string): Promise<ResolvedResource4<TArgs, TResult>>;
-	exists(locator: string): Promise<boolean>;
-	search(options?: SearchOptions): Promise<RXL4[]>;
-	private parseEntryToRXL;
-	pull(_locator: string, _options?: PullOptions): Promise<void>;
-	publish(_resource: RXR4, _options: PublishOptions): Promise<void>;
-	link(_resource: RXR4): Promise<void>;
-	delete(_locator: string): Promise<void>;
-}
 /**
 * Create a registry instance.
 *
-* When a `domain` is provided in GitRegistryConfig, the registry is automatically
-* wrapped with DomainValidation middleware for security.
-*
-* @param config - Registry configuration
-*   - No config or LocalRegistryConfig: Creates LocalRegistry (filesystem-based)
-*   - RemoteRegistryConfig: Creates RemoteRegistry (HTTP-based)
-*   - GitRegistryConfig: Creates GitRegistry (git clone-based)
+* Supports multiple configuration styles:
+* - No config: LocalRegistry (filesystem-based)
+* - `{ url, domain }`: Auto-detects type based on URL format
+* - `{ endpoint }`: RemoteRegistry (HTTP API)
+* - `{ type: "git", url }`: GitRegistry (git clone)
+* - `{ type: "github", url }`: GitHubRegistry (tarball download)
 *
 * @example
 * // Local registry (default)
 * const registry = createRegistry();
-* const registry2 = createRegistry({ path: "./custom-path" });
 *
-* // Remote registry
-* const registry3 = createRegistry({ endpoint: "https://registry.deepractice.ai/v1" });
+* // URL-based (auto-detect type)
+* const registry2 = createRegistry({
+*   url: "https://github.com/Deepractice/Registry",
+*   domain: "deepractice.dev",
+* });
 *
-* // Git registry (requires domain for remote URLs)
-* const registry4 = createRegistry({
-*   type: "git",
-*   url: "git@github.com:Deepractice/Registry.git",
-*   domain: "deepractice.ai",  // Auto-wrapped with DomainValidation
+* // With discovery
+* const discovery = await discoverRegistry("deepractice.dev");
+* const registry3 = createRegistry({
+*   url: discovery.registries[0],
+*   domain: discovery.domain,
 * });
 */
 declare function createRegistry(config?: RegistryConfig): Registry;
-import { RXR as RXR5, RXL as RXL5 } from "@resourcexjs/core";
-import { ResourceType as ResourceType5, ResolvedResource as ResolvedResource5 } from "@resourcexjs/type";
+import { RXR as RXR4, RXL as RXL4 } from "@resourcexjs/core";
+import { ResourceType as ResourceType4, ResolvedResource as ResolvedResource4 } from "@resourcexjs/type";
 /**
 * Base class for Registry middleware.
 * Delegates all operations to the inner registry.
@@ -375,21 +347,22 @@ import { ResourceType as ResourceType5, ResolvedResource as ResolvedResource5 }
 declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
-	supportType(type: ResourceType5): void;
+	supportType(type: ResourceType4): void;
+	link(path: string): Promise<void>;
+	add(source: string | RXR4): Promise<void>;
 	pull(locator: string, options?: PullOptions): Promise<void>;
-	publish(resource: RXR5, options: PublishOptions): Promise<void>;
-	link(resource: RXR5): Promise<void>;
-	get(locator: string): Promise<RXR5>;
+	publish(source: string | RXR4, options: PublishOptions): Promise<void>;
+	get(locator: string): Promise<RXR4>;
 	resolve<
 		TArgs = void,
 		TResult = unknown
-	>(locator: string): Promise<ResolvedResource5<TArgs, TResult>>;
+	>(locator: string): Promise<ResolvedResource4<TArgs, TResult>>;
 	exists(locator: string): Promise<boolean>;
 	delete(locator: string): Promise<void>;
-	search(options?: SearchOptions): Promise<RXL5[]>;
+	search(options?: SearchOptions): Promise<RXL4[]>;
 }
-import { RXR as RXR6 } from "@resourcexjs/core";
-import { ResolvedResource as ResolvedResource6 } from "@resourcexjs/type";
+import { RXR as RXR5 } from "@resourcexjs/core";
+import { ResolvedResource as ResolvedResource5 } from "@resourcexjs/type";
 /**
 * Domain validation middleware.
 * Ensures all resources from this registry match the trusted domain.
@@ -404,14 +377,14 @@ declare class DomainValidation extends RegistryMiddleware {
 	/**
 	* Get resource and validate domain.
 	*/
-	get(locator: string): Promise<RXR6>;
+	get(locator: string): Promise<RXR5>;
 	/**
 	* Resolve resource and validate domain.
 	*/
 	resolve<
 		TArgs = void,
 		TResult = unknown
-	>(locator: string): Promise<ResolvedResource6<TArgs, TResult>>;
+	>(locator: string): Promise<ResolvedResource5<TArgs, TResult>>;
 }
 /**
 * Factory function to create domain validation middleware.
@@ -420,4 +393,4 @@ declare class DomainValidation extends RegistryMiddleware {
 * const registry = withDomainValidation(gitRegistry, "deepractice.ai");
 */
 declare function withDomainValidation(registry: Registry, trustedDomain: string): Registry;
-export { withDomainValidation, isRemoteConfig, isGitConfig, discoverRegistry, createRegistry, WellKnownResponse, SearchOptions, RemoteRegistryConfig, RemoteRegistry, RegistryMiddleware, RegistryError, RegistryConfig, Registry, PullOptions, PublishTarget, PublishOptions, LocalRegistryConfig, LocalRegistry, GitRegistryConfig, GitRegistry, DomainValidation, DiscoveryResult };
+export { withDomainValidation, discoverRegistry, createRegistry, WellKnownResponse, UrlRegistryConfig, SearchOptions, RemoteRegistryConfig, RegistryMiddleware, RegistryError, RegistryConfig, Registry, PullOptions, PublishTarget, PublishOptions, LocalRegistryConfig, LocalRegistry, DomainValidation, DiscoveryResult };