@agentxm/registry-client 0.28.4-bootstrap.0

package/dist/src/utils.js

@@ -0,0 +1,187 @@
+/**
+ * Registry utility functions extracted from sources/providers/registry.ts.
+ *
+ * Shared helpers for registry operations: version selection, integrity
+ * computation, zip extraction, type pluralization, and path building.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { unzipSync } from "fflate";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as semver from "semver";
+import { RegistryOperationFailed } from "./errors.js";
+import { safeChildPath } from "./path-safety.js";
+import { makeAbsolutePath } from "@agentxm/extension-model/unstable/path-types";
+import { resolveVersionInRange } from "@agentxm/extension-model/unstable/version-constraints";
+import { toExtensionTypePlural, } from "@agentxm/extension-model/unstable/extensions";
+import { filterMatureVersions, isVersionEntryEligibleAt, releaseAgeEvidence, } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
+import {} from "@agentxm/extension-model/unstable/extensions/release-age";
+// -----------------------------------------------------------------------------
+// Version Selection
+// -----------------------------------------------------------------------------
+/**
+ * Select the best matching version from a list of versions.
+ *
+ * Returns the maximum non-yanked version, independent of input order.
+ */
+export const selectVersion = (versions) => {
+    const availableVersions = versions.filter((entry) => entry.yankedAt === undefined);
+    return resolveVersionInRange(availableVersions, Option.none());
+};
+export const resolveVersionEntry = (versions, versionRange) => {
+    if (Option.isNone(versionRange)) {
+        return selectVersion(versions);
+    }
+    if (semver.valid(versionRange.value) === versionRange.value) {
+        return Option.fromUndefinedOr(versions.find((candidate) => candidate.version === versionRange.value));
+    }
+    const availableVersions = versions.filter((entry) => entry.yankedAt === undefined);
+    const resolved = resolveVersionInRange(availableVersions, versionRange);
+    if (Option.isNone(resolved)) {
+        return Option.none();
+    }
+    return Option.fromUndefinedOr(availableVersions.find((candidate) => candidate.version === resolved.value.version));
+};
+export const extensionLifecycleWarnings = (index, version) => {
+    const warnings = [];
+    const extensionRef = `${index.owner}/${toExtensionTypePlural(index.type)}/${index.name}`;
+    if (version.yankedAt !== undefined) {
+        const context = [version.yankCategory, version.yankNotice].filter((value) => value !== undefined);
+        warnings.push(context.length === 0
+            ? `${extensionRef}@${version.version} is yanked`
+            : `${extensionRef}@${version.version} is yanked: ${context.join(": ")}`);
+    }
+    return warnings;
+};
+export const resolveVersionEntryWithReleaseAge = (versions, versionRange, minimumReleaseAge) => {
+    if (Option.isNone(minimumReleaseAge)) {
+        return Effect.succeed(resolveVersionEntry(versions, versionRange));
+    }
+    return filterMatureVersions(versions, minimumReleaseAge.value).pipe(Effect.map((mature) => resolveVersionEntry(mature, versionRange)));
+};
+/**
+ * Resolve one visible Registry index under one caller-supplied release-age
+ * evaluation. The supplied timestamp makes a complete operation deterministic.
+ * An accepted version that satisfies the requested range is a lower bound for
+ * unattended selection, even while that version is itself under age.
+ */
+export const resolveVersionEntryForReleaseAge = (versions, versionRange, evaluation, exemption, acceptedVersion) => {
+    const otherwiseSelected = resolveVersionEntry(versions, versionRange);
+    if (Option.isNone(otherwiseSelected)) {
+        return { kind: "version_unsatisfied" };
+    }
+    const candidate = otherwiseSelected.value;
+    const candidateEligible = isVersionEntryEligibleAt(candidate, evaluation);
+    if (!candidateEligible && exemption !== undefined) {
+        return {
+            kind: "exempted",
+            version: candidate,
+            bypassed: releaseAgeEvidence(candidate, evaluation),
+            exemption,
+        };
+    }
+    const eligible = versions.filter((entry) => isVersionEntryEligibleAt(entry, evaluation));
+    const eligibleSelection = resolveVersionEntry(eligible, versionRange);
+    const accepted = versions.find((entry) => {
+        if (entry.version !== acceptedVersion)
+            return false;
+        if (Option.isNone(versionRange))
+            return true;
+        return semver.valid(versionRange.value) === versionRange.value
+            ? entry.version === versionRange.value
+            : semver.satisfies(entry.version, versionRange.value);
+    });
+    const selected = accepted !== undefined &&
+        (Option.isNone(eligibleSelection) ||
+            semver.compareBuild(accepted.version, eligibleSelection.value.version) > 0)
+        ? Option.some(accepted)
+        : eligibleSelection;
+    if (Option.isNone(selected)) {
+        return {
+            kind: "policy_held",
+            candidate: releaseAgeEvidence(candidate, evaluation),
+        };
+    }
+    const selectedAcceptedFloor = accepted?.version === selected.value.version && !candidateEligible;
+    return {
+        kind: "selected",
+        version: selected.value,
+        ...(candidateEligible ||
+            (candidate.version === selected.value.version && !selectedAcceptedFloor)
+            ? {}
+            : { newerHeld: releaseAgeEvidence(candidate, evaluation) }),
+    };
+};
+// -----------------------------------------------------------------------------
+// Type Pluralization
+// -----------------------------------------------------------------------------
+/** Pluralize extension type for directory segments. */
+export const pluralizeType = (type) => toExtensionTypePlural(type);
+// -----------------------------------------------------------------------------
+// Extension Directory
+// -----------------------------------------------------------------------------
+/** Build the path to an extension's directory within a registry. */
+export const extensionDir = (registryRoot, owner, type, name, join) => join(registryRoot, "extensions", owner, pluralizeType(type), name);
+// -----------------------------------------------------------------------------
+// Zip Extraction
+// -----------------------------------------------------------------------------
+/**
+ * Extract a zip archive to a target directory.
+ * Uses fflate for in-memory decompression (portable across platforms).
+ */
+export const extractZip = (archive, targetDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    // Decompress zip archive in memory
+    const entries = yield* Effect.try({
+        try: () => unzipSync(archive),
+        catch: (e) => new RegistryOperationFailed({
+            category: "validation",
+            detail: "Failed to decompress zip archive",
+            cause: e,
+        }),
+    });
+    // Resolve the target directory once for containment checks.
+    const baseDir = makeAbsolutePath(path, targetDir);
+    // Write each entry to the target directory
+    yield* Effect.forEach(Object.entries(entries), ([name, data]) => Effect.gen(function* () {
+        // Reject any entry whose resolved path escapes the target directory
+        // (zip slip): `..` traversal or an absolute path.
+        const safePath = yield* safeChildPath(baseDir, name);
+        if (Option.isNone(safePath)) {
+            return yield* new RegistryOperationFailed({
+                category: "validation",
+                detail: `Refusing to extract entry outside the target directory: ${name}`,
+            });
+        }
+        const fullPath = safePath.value;
+        // Directory entries end with '/'
+        if (name.endsWith("/")) {
+            yield* fs.makeDirectory(fullPath, { recursive: true }).pipe(Effect.mapError((e) => new RegistryOperationFailed({
+                category: "network",
+                detail: `Failed to create directory: ${name}`,
+                cause: e,
+            })));
+        }
+        else {
+            // Ensure parent directory exists
+            const parentDir = path.dirname(fullPath);
+            yield* fs.makeDirectory(parentDir, { recursive: true }).pipe(Effect.mapError((e) => new RegistryOperationFailed({
+                category: "network",
+                detail: `Failed to create parent directory for: ${name}`,
+                cause: e,
+            })));
+            yield* fs.writeFile(fullPath, data).pipe(Effect.mapError((e) => new RegistryOperationFailed({
+                category: "network",
+                detail: `Failed to write file: ${name}`,
+                cause: e,
+            })));
+        }
+    }), { concurrency: 1 });
+});
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@agentxm/registry-client",
+  "version": "0.28.4-bootstrap.0",
+  "description": "AXM registry integration: local and remote registry clients over the generated OpenAPI transport, request policy and retries, typed registry failures, archive cache, and lifecycle administration for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
+  "type": "module",
+  "license": "FSL-1.1-MIT",
+  "homepage": "https://axm.sh",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git",
+    "directory": "packages/registry-client"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "fflate": "^0.8.3",
+    "semver": "^7.8.5",
+    "@agentxm/extension-model": "^0.28.4-bootstrap.0",
+    "@agentxm/registry-protocol": "^0.28.4-bootstrap.0"
+  },
+  "devDependencies": {
+    "@effect/openapi-generator": "4.0.0-rc.112",
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/bun": "^1.3.14",
+    "@types/semver": "^7.5.8",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "swagger2openapi": "^7.0.8",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}