@resourcexjs/core 2.14.0 → 2.15.0

package/dist/index.d.ts

@@ -72,18 +72,21 @@ interface RXI {
 	readonly path?: string;
 	/** Resource name */
 	readonly name: string;
-	/** Tag (version or label). Defaults to "latest" if not specified. */
+	/** Tag (mutable pointer). Defaults to "latest" if not specified. */
 	readonly tag: string;
+	/** Content digest (immutable hash, e.g., "sha256:abc123"). */
+	readonly digest?: string;
 }
 /**
 * Format RXI to locator string.
 *
-* Docker-style format: [registry/][path/]name[:tag]
+* Docker-style format: [registry/][path/]name[:tag][@digest]
 *
 * Examples:
 * - { name: "hello", tag: "latest" } → "hello" (omit :latest)
 * - { 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"
+* - { name: "hello", tag: "latest", digest: "sha256:abc" } → "hello@sha256:abc"
+* - { name: "hello", tag: "beta", digest: "sha256:abc" } → "hello:beta@sha256:abc"
 *
 * @param rxi - Resource identifier
 * @returns Locator string
@@ -113,9 +116,11 @@ interface RXMDefinition {
 }
 /**
 * RXM Archive — packaging metadata.
-* Placeholder for future fields (digest, size, md5, etc.)
 */
-type RXMArchive = {};
+interface RXMArchive {
+	/** Deterministic content digest computed from file-level digests. Format: sha256:<hex> */
+	readonly digest?: string;
+}
 /**
 * File entry with metadata.
 */
@@ -242,7 +247,7 @@ interface TypeDetectionResult {
 	readonly type: string;
 	/** Detected resource name */
 	readonly name: string;
-	/** Tag/version (defaults to "latest" if not provided) */
+	/** Tag (defaults to "latest" if not provided) */
 	readonly tag?: string;
 	/** Description extracted from content */
 	readonly description?: string;
@@ -415,21 +420,6 @@ interface SourceLoader {
 	* @throws ResourceXError if loading fails
 	*/
 	load(source: string): Promise<RXS>;
-	/**
-	* Check if cached content for this source is still fresh.
-	*
-	* Each loader implements its own strategy:
-	* - FolderSourceLoader: compare file mtime against cachedAt
-	* - GitHubSourceLoader: not implemented (always stale)
-	*
-	* Loaders that don't implement this are treated as always stale,
-	* causing a full reload on every ingest.
-	*
-	* @param source - Source path or identifier
-	* @param cachedAt - When the resource was last cached
-	* @returns true if cache is still fresh, false if stale
-	*/
-	isFresh?(source: string, cachedAt: Date): Promise<boolean>;
 }
 /**
 * Default ResourceLoader implementation for loading resources from folders.
@@ -446,8 +436,8 @@ interface SourceLoader {
 * {
 *   "name": "resource-name",      // required
 *   "type": "text",               // required
-*   "version": "1.0.0",           // required
-*   "domain": "localhost",        // optional, defaults to "localhost"
+*   "tag": "1.0.0",              // optional, defaults to "latest"
+*   "registry": "localhost",      // optional
 *   "path": "optional/path"       // optional
 * }
 * ```
@@ -473,15 +463,6 @@ declare class FolderSourceLoader implements SourceLoader {
 	canLoad(source: string): Promise<boolean>;
 	load(source: string): Promise<RXS>;
 	/**
-	* Check if cached content is still fresh by comparing file mtimes.
-	* Returns true only if no file in the directory has been modified since cachedAt.
-	*/
-	isFresh(source: string, cachedAt: Date): Promise<boolean>;
-	/**
-	* Get the most recent mtime across all files in a folder (recursive).
-	*/
-	private getMaxMtime;
-	/**
 	* Recursively read all files in a folder.
 	*/
 	private readFolderFiles;
@@ -584,17 +565,6 @@ declare class SourceLoaderChain {
 	* @throws ResourceXError if no loader matches
 	*/
 	load(source: string): Promise<RXS>;
-	/**
-	* Check if cached content for a source is still fresh.
-	*
-	* Delegates to the matching loader's isFresh method.
-	* Returns false if the loader doesn't implement isFresh (always reload).
-	*
-	* @param source - Source path or identifier
-	* @param cachedAt - When the resource was last cached
-	* @returns true if cache is still fresh
-	*/
-	isFresh(source: string, cachedAt: Date): Promise<boolean>;
 }
 /**
 * Configuration for resolveSource.
@@ -684,6 +654,7 @@ interface StoredRXM {
 	readonly license?: string;
 	readonly keywords?: string[];
 	readonly repository?: string;
+	readonly digest?: string;
 	readonly files: Record<string, string>;
 	readonly createdAt?: Date;
 	readonly updatedAt?: Date;
@@ -778,19 +749,6 @@ interface ProviderStores {
 	rxmStore: RXMStore;
 }
 /**
-* Resource loader interface for loading from directories/archives.
-*/
-interface ResourceLoader2 {
-	/**
-	* Check if this loader can handle the given source.
-	*/
-	canLoad(source: string): boolean | Promise<boolean>;
-	/**
-	* Load resource from source.
-	*/
-	load(source: string): Promise<unknown>;
-}
-/**
 * Platform-specific defaults resolved from environment variables and config files.
 */
 interface ProviderDefaults {
@@ -823,11 +781,6 @@ interface ResourceXProvider {
 	*/
 	createStores(config: ProviderConfig): ProviderStores;
 	/**
-	* Create resource loader (optional).
-	* Not all platforms support loading from filesystem.
-	*/
-	createLoader?(config: ProviderConfig): ResourceLoader2;
-	/**
 	* Create source loader for auto-detection pipeline (optional).
 	*/
 	createSourceLoader?(config: ProviderConfig): SourceLoader;
@@ -915,8 +868,9 @@ interface Registry {
 	get(rxi: RXI): Promise<RXR>;
 	/**
 	* Store resource.
+	* @returns The stored manifest (with computed digest).
 	*/
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	/**
 	* Check if resource exists.
 	*/
@@ -936,7 +890,7 @@ declare class CASRegistry implements Registry {
 	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
 	private resolveTag;
 	get(rxi: RXI): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -994,7 +948,7 @@ declare class LinkedRegistry implements Registry {
 	* Put is not typically used for LinkedRegistry.
 	* Use link() instead to create symlinks.
 	*/
-	put(_rxr: RXR): Promise<void>;
+	put(_rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -1030,7 +984,7 @@ declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
 	get(rxi: RXI): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -1129,7 +1083,7 @@ interface ResolveContext {
 		path?: string
 		name: string
 		type: string
-		version: string
+		tag: string
 	};
 	/**
 	* Extracted files from archive.

package/dist/index.js

@@ -14597,7 +14597,6 @@ var RXDSchema = exports_external.object({
   name: exports_external.string().min(1).max(128),
   type: exports_external.string().min(1).max(64),
   tag: exports_external.string().max(64).optional(),
-  version: exports_external.string().max(64).optional(),
   registry: exports_external.string().max(256).optional(),
   path: exports_external.string().max(256).optional(),
   description: exports_external.string().max(1024).optional(),
@@ -14619,7 +14618,7 @@ function define(input) {
   const rxd = Object.assign(Object.create(null), {
     name: validated.name,
     type: validated.type,
-    tag: validated.tag ?? validated.version ?? undefined,
+    tag: validated.tag ?? undefined,
     registry: validated.registry,
     path: validated.path,
     description: validated.description,
@@ -14659,6 +14658,9 @@ function format(rxi) {
   if (rxi.tag && rxi.tag !== "latest") {
     result += `:${rxi.tag}`;
   }
+  if (rxi.digest) {
+    result += `@${rxi.digest}`;
+  }
   return result;
 }
 // src/model/locate.ts
@@ -14737,15 +14739,25 @@ function parse5(locator) {
     throw new LocatorError("Locator must be a non-empty string", locator);
   }
   validateLocatorSecurity(locator);
-  if (locator.includes("@")) {
-    throw new LocatorError("Invalid locator format. Use name:tag instead of name@version", locator);
+  let digest;
+  let locatorWithoutDigest = locator;
+  const atIndex = locator.indexOf("@");
+  if (atIndex !== -1) {
+    if (atIndex === 0) {
+      throw new LocatorError("Invalid locator format. Name is required before @", locator);
+    }
+    digest = locator.substring(atIndex + 1);
+    locatorWithoutDigest = locator.substring(0, atIndex);
+    if (!digest || digest.includes("@")) {
+      throw new LocatorError("Invalid digest format after @", locator);
+    }
   }
-  const lastSlashIndex = locator.lastIndexOf("/");
+  const lastSlashIndex = locatorWithoutDigest.lastIndexOf("/");
   let beforeSlash = "";
-  let afterSlash = locator;
+  let afterSlash = locatorWithoutDigest;
   if (lastSlashIndex !== -1) {
-    beforeSlash = locator.substring(0, lastSlashIndex);
-    afterSlash = locator.substring(lastSlashIndex + 1);
+    beforeSlash = locatorWithoutDigest.substring(0, lastSlashIndex);
+    afterSlash = locatorWithoutDigest.substring(lastSlashIndex + 1);
   }
   const colonIndex = afterSlash.lastIndexOf(":");
   let name;
@@ -14768,7 +14780,8 @@ function parse5(locator) {
       registry: undefined,
       path: undefined,
       name,
-      tag
+      tag,
+      digest
     };
   }
   const parts = beforeSlash.split("/");
@@ -14779,14 +14792,16 @@ function parse5(locator) {
       registry: registry2,
       path,
       name,
-      tag
+      tag,
+      digest
     };
   }
   return {
     registry: undefined,
     path: beforeSlash,
     name,
-    tag
+    tag,
+    digest
   };
 }
 // src/model/resource.ts
@@ -14864,7 +14879,7 @@ class ResourceJsonDetector {
     return {
       type: json2.type,
       name: json2.name,
-      tag: json2.tag ?? json2.version ?? undefined,
+      tag: json2.tag,
       description: json2.description,
       registry: json2.registry,
       path: json2.path,
@@ -15008,31 +15023,6 @@ class FolderSourceLoader {
     const files = await this.readFolderFiles(source);
     return { source, files };
   }
-  async isFresh(source, cachedAt) {
-    try {
-      const maxMtime = await this.getMaxMtime(source);
-      return maxMtime <= cachedAt;
-    } catch {
-      return false;
-    }
-  }
-  async getMaxMtime(folderPath) {
-    let max = new Date(0);
-    const entries = await readdir2(folderPath, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join2(folderPath, entry.name);
-      if (entry.isFile()) {
-        const stats = await stat2(fullPath);
-        if (stats.mtime > max)
-          max = stats.mtime;
-      } else if (entry.isDirectory()) {
-        const subMax = await this.getMaxMtime(fullPath);
-        if (subMax > max)
-          max = subMax;
-      }
-    }
-    return max;
-  }
   async readFolderFiles(folderPath, basePath = folderPath) {
     const files = {};
     const entries = await readdir2(folderPath, { withFileTypes: true });
@@ -15154,17 +15144,6 @@ class SourceLoaderChain {
     }
     throw new ResourceXError(`Cannot load source: ${source}`);
   }
-  async isFresh(source, cachedAt) {
-    for (const loader of this.loaders) {
-      if (await loader.canLoad(source)) {
-        if (loader.isFresh) {
-          return loader.isFresh(source, cachedAt);
-        }
-        return false;
-      }
-    }
-    return false;
-  }
 }
 
 // src/loader/resolveSource.ts
@@ -15278,6 +15257,22 @@ function withRegistryValidation(registry2, trustedRegistry) {
 }
 var DomainValidation = RegistryValidation;
 var withDomainValidation = withRegistryValidation;
+// src/registry/store/digest.ts
+import { createHash } from "node:crypto";
+function computeDigest(data) {
+  const hash2 = createHash("sha256").update(data).digest("hex");
+  return `sha256:${hash2}`;
+}
+function computeArchiveDigest(files) {
+  const entries = Object.keys(files).sort().map((name) => `${name}:${files[name]}`).join(`
+`);
+  const hash2 = createHash("sha256").update(entries).digest("hex");
+  return `sha256:${hash2}`;
+}
+function isValidDigest(digest) {
+  return /^sha256:[a-f0-9]{64}$/.test(digest);
+}
+
 // src/registry/registries/CASRegistry.ts
 class CASRegistry {
   rxaStore;
@@ -15320,7 +15315,9 @@ class CASRegistry {
         keywords: storedRxm.keywords,
         repository: storedRxm.repository
       },
-      archive: {},
+      archive: {
+        digest: storedRxm.digest ?? computeArchiveDigest(storedRxm.files)
+      },
       source: {}
     };
     const rxa = await archive(files);
@@ -15330,9 +15327,10 @@ class CASRegistry {
     const files = await extract(rxr.archive);
     const fileDigests = {};
     for (const [filename, content] of Object.entries(files)) {
-      const digest = await this.rxaStore.put(content);
-      fileDigests[filename] = digest;
+      const digest2 = await this.rxaStore.put(content);
+      fileDigests[filename] = digest2;
     }
+    const digest = computeArchiveDigest(fileDigests);
     const storedRxm = {
       registry: rxr.manifest.definition.registry,
       path: rxr.manifest.definition.path,
@@ -15344,12 +15342,18 @@ class CASRegistry {
       license: rxr.manifest.definition.license,
       keywords: rxr.manifest.definition.keywords,
       repository: rxr.manifest.definition.repository,
+      digest,
       files: fileDigests,
       createdAt: new Date,
       updatedAt: new Date
     };
     await this.rxmStore.put(storedRxm);
     await this.rxmStore.setLatest(rxr.manifest.definition.name, rxr.manifest.definition.tag, rxr.manifest.definition.registry);
+    return {
+      definition: rxr.manifest.definition,
+      archive: { digest },
+      source: rxr.manifest.source
+    };
   }
   async has(rxi) {
     const tag = await this.resolveTag(rxi.name, rxi.tag ?? "latest", rxi.registry);
@@ -15548,15 +15552,6 @@ class LinkedRegistry {
     }
   }
 }
-// src/registry/store/digest.ts
-import { createHash } from "node:crypto";
-function computeDigest(data) {
-  const hash2 = createHash("sha256").update(data).digest("hex");
-  return `sha256:${hash2}`;
-}
-function isValidDigest(digest) {
-  return /^sha256:[a-f0-9]{64}$/.test(digest);
-}
 // src/registry/store/MemoryRXAStore.ts
 class MemoryRXAStore {
   blobs = new Map;
@@ -15904,4 +15899,4 @@ export {
   CASRegistry
 };
 
-//# debugId=B122DF8CA052DA8364756E2164756E21
+//# debugId=2D991EC1BFB2AAA764756E2164756E21