@agentxm/registry-client 0.28.4-bootstrap.0

package/dist/src/atomic-write.js

@@ -0,0 +1,60 @@
+/**
+ * Shared atomic single-file replacement: write a uniquely named temp file in
+ * the target's directory, then rename it over the target.
+ *
+ * Deliberately duplicated from the workspace-state kernel: an integration
+ * may not depend on a kernel, and this helper is within the sanctioned
+ * duplication budget for small pure functions. The registry consumers never
+ * sweep stale temps, so that half of the original stays behind.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+/** In-process sequence so concurrent fibers never share a temp path. */
+let tempSequence = 0;
+const atomicWriteTempPrefix = (targetPath) => `${targetPath}.tmp.`;
+const makeTempPath = (targetPath) => {
+    tempSequence += 1;
+    const pid = typeof process === "object" ? process.pid.toString(36) : "x";
+    const random = Math.random().toString(36).slice(2, 8);
+    return `${atomicWriteTempPrefix(targetPath)}${pid}.${tempSequence.toString(36)}.${random}`;
+};
+const bytesEqual = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+const targetHasContent = (fs, targetPath, content) => typeof content === "string"
+    ? Effect.map(fs.readFileString(targetPath), (current) => current === content)
+    : Effect.map(fs.readFile(targetPath), (current) => bytesEqual(current, content));
+/**
+ * Atomically replace `targetPath` with `content` via a same-directory temp
+ * file and rename. Failures at each step are mapped by the caller, so error
+ * categories, details, and suggestions stay call-site specific.
+ */
+export const writeFileAtomic = (fs, options) => Effect.gen(function* () {
+    const { content, mapError, targetPath } = options;
+    const tempPath = makeTempPath(targetPath);
+    const fail = (step) => (cause) => mapError({ step, targetPath, tempPath, cause });
+    if (options.skipIfUnchanged === "fail-on-read-error") {
+        const exists = yield* fs.exists(targetPath).pipe(Effect.mapError(fail("check-target")));
+        if (exists) {
+            const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.mapError(fail("read-target")));
+            if (unchanged)
+                return "skipped";
+        }
+    }
+    else if (options.skipIfUnchanged === "ignore-read-errors") {
+        const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.option);
+        if (Option.isSome(unchanged) && unchanged.value)
+            return "skipped";
+    }
+    yield* Effect.gen(function* () {
+        yield* (typeof content === "string"
+            ? fs.writeFileString(tempPath, content)
+            : fs.writeFile(tempPath, content)).pipe(Effect.mapError(fail("write-temp")));
+        if (options.removeTargetBeforeRename === true) {
+            yield* fs.remove(targetPath).pipe(Effect.ignore);
+        }
+        yield* fs.rename(tempPath, targetPath).pipe(Effect.mapError(fail("rename")));
+    }).pipe(Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
+    return "written";
+});
+//# sourceMappingURL=atomic-write.js.map

package/dist/src/axm-package-meta.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Schema for axm package metadata shipped by library authors.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+export declare const PackageExtensionDeclarationSchema: Schema.Struct<{
+    readonly ref: Schema.String;
+    readonly versionRange: Schema.optional<Schema.NullOr<Schema.brand<Schema.NonEmptyString, "VersionRange">>>;
+}>;
+export type PackageExtensionDeclaration = Schema.Schema.Type<typeof PackageExtensionDeclarationSchema>;
+/**
+ * Schema for the axm package metadata file that library authors ship
+ * to surface recommended axm extensions for their package.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const AxmPackageMetaSchema: Schema.Struct<{
+    readonly $schema: Schema.optional<Schema.String>;
+    readonly extensions: Schema.$Array<Schema.Struct<{
+        readonly ref: Schema.String;
+        readonly versionRange: Schema.optional<Schema.NullOr<Schema.brand<Schema.NonEmptyString, "VersionRange">>>;
+    }>>;
+}>;
+/**
+ * Inferred type for AxmPackageMeta schema.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type AxmPackageMeta = Schema.Schema.Type<typeof AxmPackageMetaSchema>;
+//# sourceMappingURL=axm-package-meta.d.ts.map

package/dist/src/axm-package-meta.js

@@ -0,0 +1,31 @@
+/**
+ * Schema for axm package metadata shipped by library authors.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { ExtensionFqnSchema } from "@agentxm/extension-model/unstable/extensions/common";
+import { VersionRangeSchema } from "@agentxm/extension-model/unstable/version-constraints";
+export const PackageExtensionDeclarationSchema = Schema.Struct({
+    ref: ExtensionFqnSchema,
+    versionRange: Schema.optional(Schema.NullOr(VersionRangeSchema)),
+}).annotate({
+    identifier: "PackageExtensionDeclaration",
+    title: "Package Extension Declaration",
+    description: "An extension declared by package-native AXM metadata, with an optional semver version range.",
+});
+/**
+ * Schema for the axm package metadata file that library authors ship
+ * to surface recommended axm extensions for their package.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const AxmPackageMetaSchema = Schema.Struct({
+    $schema: Schema.optional(Schema.String),
+    extensions: Schema.Array(PackageExtensionDeclarationSchema),
+}).annotate({
+    identifier: "AxmPackageMeta",
+    title: "axm Package Metadata",
+    description: "Recommendation metadata shipped by library authors to surface axm extensions.",
+});
+//# sourceMappingURL=axm-package-meta.js.map

package/dist/src/cache-root.d.ts

@@ -0,0 +1,11 @@
+/** Platform cache placement shared by all non-authoritative AXM caches. */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+export interface AxmCacheEnvironment {
+    readonly axmUserHome?: string;
+    readonly localAppData?: string;
+    readonly xdgCacheHome?: string;
+}
+export declare const resolveAxmCacheRootPure: (pathJoin: (...segments: ReadonlyArray<string>) => string, platform: string, homeDir: string, environment: AxmCacheEnvironment) => string;
+export declare const resolveAxmCacheRoot: () => Effect.Effect<string, never, Path.Path>;
+//# sourceMappingURL=cache-root.d.ts.map

package/dist/src/cache-root.js

@@ -0,0 +1,43 @@
+/** Platform cache placement shared by all non-authoritative AXM caches. */
+import * as os from "node:os";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+const nonEmpty = (value) => value === undefined || value.length === 0 ? undefined : value;
+export const resolveAxmCacheRootPure = (pathJoin, platform, homeDir, environment) => {
+    const overriddenHome = nonEmpty(environment.axmUserHome);
+    const home = overriddenHome ?? homeDir;
+    if (platform === "darwin")
+        return pathJoin(home, "Library", "Caches", "axm");
+    if (platform === "win32") {
+        const cacheHome = overriddenHome === undefined
+            ? (nonEmpty(environment.localAppData) ?? pathJoin(home, "AppData", "Local"))
+            : pathJoin(home, "AppData", "Local");
+        return pathJoin(cacheHome, "axm", "cache");
+    }
+    const cacheHome = overriddenHome === undefined
+        ? (nonEmpty(environment.xdgCacheHome) ?? pathJoin(home, ".cache"))
+        : pathJoin(home, ".cache");
+    return pathJoin(cacheHome, "axm");
+};
+const cacheEnvironmentConfig = Config.all({
+    axmUserHome: Config.option(Config.string("AXM_USER_HOME")),
+    localAppData: Config.option(Config.string("LOCALAPPDATA")),
+    xdgCacheHome: Config.option(Config.string("XDG_CACHE_HOME")),
+});
+export const resolveAxmCacheRoot = () => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    // All fields are optional strings; failure would violate the provider contract.
+    // eslint-disable-next-line no-restricted-syntax -- Config cannot fail for an all-optional record.
+    const environment = yield* Effect.orDie(cacheEnvironmentConfig);
+    const axmUserHome = Option.getOrUndefined(environment.axmUserHome);
+    const localAppData = Option.getOrUndefined(environment.localAppData);
+    const xdgCacheHome = Option.getOrUndefined(environment.xdgCacheHome);
+    return resolveAxmCacheRootPure(path.join, process.platform, os.homedir(), {
+        ...(axmUserHome === undefined ? {} : { axmUserHome }),
+        ...(localAppData === undefined ? {} : { localAppData }),
+        ...(xdgCacheHome === undefined ? {} : { xdgCacheHome }),
+    });
+});
+//# sourceMappingURL=cache-root.js.map

package/dist/src/client.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Registry client types and factory.
+ *
+ * Domain types for registry search and extension entries,
+ * independent of any source provider abstraction.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { RegistryClientFailure } from "./errors.js";
+import type { PublishVisibility, VisibilityEvaluation, VisibilityIntent, VisibilityMutationRequest, VisibilityMutationResult } from "@agentxm/registry-protocol/unstable/publish";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+import type { Author, ExtensionDependencyConstraintMap, ExtensionName, ExtensionType } from "@agentxm/extension-model/unstable/extensions";
+import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
+import type { ExtensionIndex, VersionEntry } from "@agentxm/registry-protocol/unstable/registry/schema";
+import type { DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
+import type { Bugs, Repository } from "@agentxm/extension-model/unstable/extensions/common";
+import type { DiscoverPackagesResponse } from "@agentxm/registry-protocol/unstable/registry/discover-schema";
+import type { PackageUrlParts } from "@agentxm/extension-model/unstable/packaging/package-url";
+import type { PackageExtensionDeclaration } from "./axm-package-meta.js";
+import type { RegistryRequestPolicy } from "./request-policy.js";
+import type { Version, VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
+import type { PreviewPublicationSetRequest, PreviewPublicationSetResponse, PublicationVisibilityInput, Sha256Hex } from "@agentxm/registry-protocol/unstable/registry/publication-set";
+/**
+ * Options for searching extensions within a specific registry owner.
+ *
+ * - `owner`: owner to search (e.g. `"@acme"`)
+ * - `names`: extension names to match (empty = all)
+ * - `types`: extension types to include (empty = all)
+ * - `limit`: max results to return (default: all)
+ * - `offset`: number of results to skip (default: 0)
+ */
+export interface GetExtensionsByOwnerArgs {
+    readonly owner: Handle | "*";
+    readonly names: ReadonlyArray<string>;
+    readonly types: ReadonlyArray<ExtensionType>;
+    readonly limit: Option.Option<number>;
+    readonly offset: number;
+}
+/**
+ * Options for fetching a specific extension version from a registry.
+ *
+ * - `owner`: owner in the registry path (e.g. `"@acme"`)
+ * - `type`: extension type
+ * - `name`: extension name
+ * - `version`: specific version to fetch, or `None` for latest
+ */
+export interface GetExtensionPackageArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Option.Option<Version | VersionRange>;
+    /** Marks an archive read used only to verify compatibility before selection. */
+    readonly usagePurpose?: "verification";
+}
+/**
+ * Options for fetching extension index metadata from a registry.
+ *
+ * - `owner`: owner in the registry path (e.g. `"@acme"`)
+ * - `type`: extension type
+ * - `name`: extension name
+ */
+export interface GetExtensionIndexArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+}
+export interface GetExactExtensionVersionArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+    /** Ephemeral exact publish capability used to settle an ambiguous upload. */
+    readonly accessToken?: string;
+}
+export interface ExactExtensionVersion {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+    readonly integrity: string;
+    readonly status: "available";
+}
+/**
+ * Options for publishing an extension version to a registry.
+ *
+ * - `owner`: owner in the registry path (e.g. `"@acme"`)
+ * - `type`: extension type
+ * - `name`: extension name
+ * - `version`: version string to publish
+ * - `archive`: zip archive bytes
+ * - `metadata`: version entry metadata
+ */
+export interface PublishExtensionArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+    readonly archive: Uint8Array;
+    readonly metadata: VersionEntry;
+    /** Exact repository/CLI visibility input bound by the publication descriptor digest. */
+    readonly visibilityInput: PublicationVisibilityInput;
+    /** Authoritative establishment value and provenance from publication preview. */
+    readonly visibility?: PublishVisibility;
+    /** Ephemeral exact publish capability. Never persisted by the registry client. */
+    readonly accessToken?: string;
+    /** Opaque authoritative preview condition, sent as If-Match. */
+    readonly condition?: string;
+    /** Digest of the complete publication set authorized by the preview. */
+    readonly publicationSetDigest?: Sha256Hex;
+    /** Digest of this exact publication descriptor. */
+    readonly publicationDescriptorDigest?: Sha256Hex;
+}
+export type ExtensionVisibility = "public" | "private";
+export interface PublishPreviewTarget {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+}
+export type PreviewExtensionPublishesArgs = PreviewPublicationSetRequest;
+export type PublishPreviewResult = PreviewPublicationSetResponse;
+export interface GetExtensionVisibilityArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly intent: VisibilityIntent | null;
+}
+export type UpdateExtensionVisibilityArgs = VisibilityMutationRequest;
+/**
+ * Options for checking whether an extension exists in a registry.
+ *
+ * - `owner`: owner in the registry path (e.g. `"@acme"`)
+ * - `type`: extension type
+ * - `name`: extension name
+ */
+export interface ExtensionExistsArgs {
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+}
+/**
+ * Result from a registry extension search.
+ */
+export interface GetExtensionsByOwnerResponse {
+    readonly extensions: ReadonlyArray<RegistryExtensionManifest<ExtensionType>>;
+    readonly total: number;
+}
+/**
+ * Response from fetching a specific extension version archive.
+ */
+export interface GetExtensionPackageResponse {
+    readonly archive: Uint8Array;
+    readonly warnings?: ReadonlyArray<string>;
+}
+/**
+ * Response from publishing an extension version.
+ */
+export interface ExtensionLinks {
+    readonly html: string;
+}
+export interface PublishExtensionResponse {
+    readonly published: true;
+    readonly owner: Handle;
+    readonly type: ExtensionType;
+    readonly name: ExtensionName;
+    readonly version: Version;
+    readonly integrity: string;
+    readonly status: "pending" | "available" | "failed";
+    readonly visibility: PublishVisibility;
+    readonly links?: ExtensionLinks;
+    readonly warnings: ReadonlyArray<RegistryPublishWarning>;
+}
+export interface RegistryPublishWarning {
+    readonly ruleId: string;
+    readonly severity: "warning";
+    readonly message: string;
+    readonly suggestions: ReadonlyArray<SuggestedAction>;
+}
+/**
+ * Response from checking whether an owner exists in a registry.
+ */
+export interface OwnerExistsResponse {
+    readonly exists: boolean;
+}
+/**
+ * Response from checking whether an extension exists in a registry.
+ */
+export interface ExtensionExistsResponse {
+    readonly exists: boolean;
+}
+/**
+ * Options for discovering extensions compatible with detected packages
+ * and workspace recommendations.
+ *
+ * - `packages`: detected package purls to match against extension compatibility
+ * - `declaredExtensions`: extension refs declared by the package's native AXM metadata
+ */
+export interface DiscoverPackageInput {
+    readonly purl: PackageUrlParts;
+    readonly version: string;
+    readonly declaredExtensions: ReadonlyArray<PackageExtensionDeclaration>;
+}
+export interface DiscoverPackagesArgs {
+    readonly packages: ReadonlyArray<DiscoverPackageInput>;
+}
+/**
+ * A discovered extension entry from a registry search.
+ *
+ * Represents a single matched extension with its resolved version and integrity.
+ */
+export interface RegistryExtensionManifest<T extends ExtensionType = ExtensionType> {
+    readonly owner: Handle;
+    readonly type: T;
+    readonly name: ExtensionName;
+    /** Immutable publisher epoch for this coordinate. */
+    readonly publisherBindingId: string;
+    readonly description: Option.Option<string>;
+    readonly repository: Option.Option<Repository>;
+    readonly bugs: Option.Option<Bugs>;
+    readonly license: Option.Option<string>;
+    readonly authors: ReadonlyArray<Author>;
+    readonly dependencies: ExtensionDependencyConstraintMap;
+    readonly version: Version;
+    readonly integrity: string;
+    /** Package URLs this extension is compatible with. Empty when absent in registry metadata. */
+    readonly packages: ReadonlyArray<PackageUrlParts>;
+    readonly deprecation?: DeprecationView;
+    readonly lifecycleWarnings?: ReadonlyArray<string>;
+}
+/**
+ * Client interface for interacting with a registry.
+ *
+ * All operations are scoped to a registry root provided at construction time.
+ * Uses registry-domain types only — no source provider dependencies.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface RegistryClient {
+    readonly getExtensionsByScope: (args: GetExtensionsByOwnerArgs) => Effect.Effect<GetExtensionsByOwnerResponse, RegistryClientFailure>;
+    readonly ownerExists: (owner: Handle) => Effect.Effect<OwnerExistsResponse, RegistryClientFailure>;
+    readonly getExtensionIndex: (args: GetExtensionIndexArgs) => Effect.Effect<Option.Option<ExtensionIndex>, RegistryClientFailure>;
+    readonly getExactExtensionVersion: (args: GetExactExtensionVersionArgs) => Effect.Effect<Option.Option<ExactExtensionVersion>, RegistryClientFailure>;
+    readonly getExtensionPackage: (args: GetExtensionPackageArgs) => Effect.Effect<GetExtensionPackageResponse, RegistryClientFailure>;
+    readonly publishExtension: (args: PublishExtensionArgs) => Effect.Effect<PublishExtensionResponse, RegistryClientFailure>;
+    readonly previewExtensionPublishes: (args: PreviewExtensionPublishesArgs) => Effect.Effect<PublishPreviewResult, RegistryClientFailure>;
+    readonly getExtensionVisibility: (args: GetExtensionVisibilityArgs) => Effect.Effect<VisibilityEvaluation, RegistryClientFailure>;
+    readonly updateExtensionVisibility: (args: UpdateExtensionVisibilityArgs) => Effect.Effect<VisibilityMutationResult, RegistryClientFailure>;
+    readonly extensionExists: (args: ExtensionExistsArgs) => Effect.Effect<ExtensionExistsResponse, RegistryClientFailure>;
+    readonly discoverPackages: (args: DiscoverPackagesArgs) => Effect.Effect<DiscoverPackagesResponse, RegistryClientFailure>;
+}
+/**
+ * Create the appropriate registry client based on location scheme.
+ *
+ * - Local paths and `file://` URLs -> `LocalRegistryClient`
+ * - `http://` and `https://` URLs -> `RemoteRegistryClient`
+ *
+ * @param location - Registry location (local path, file:// URL, or https:// URL)
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const createRegistryClient: (location: string, options?: {
+    readonly requestPolicy?: RegistryRequestPolicy;
+}) => Effect.Effect<RegistryClient, never, HttpClient.HttpClient | FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.js

@@ -0,0 +1,43 @@
+/**
+ * Registry client types and factory.
+ *
+ * Domain types for registry search and extension entries,
+ * independent of any source provider abstraction.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { stripFileProtocol } from "./fs-helpers.js";
+import { makeUserArchiveCache } from "./archive-cache.js";
+import { createLocalRegistryClient } from "./local-client.js";
+import { createRemoteRegistryClient } from "./remote-client.js";
+// -----------------------------------------------------------------------------
+// Factory
+// -----------------------------------------------------------------------------
+/**
+ * Create the appropriate registry client based on location scheme.
+ *
+ * - Local paths and `file://` URLs -> `LocalRegistryClient`
+ * - `http://` and `https://` URLs -> `RemoteRegistryClient`
+ *
+ * @param location - Registry location (local path, file:// URL, or https:// URL)
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const createRegistryClient = (location, options) => Effect.gen(function* () {
+    if (location.startsWith("https://") || location.startsWith("http://")) {
+        const httpClient = yield* HttpClient.HttpClient;
+        const archiveCache = yield* makeUserArchiveCache();
+        return createRemoteRegistryClient(location, httpClient, archiveCache, options?.requestPolicy);
+    }
+    const localPath = location.startsWith("file://") ? stripFileProtocol(location) : location;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    return createLocalRegistryClient(localPath, fs, path);
+});
+//# sourceMappingURL=client.js.map

package/dist/src/deprecation-warning.d.ts

@@ -0,0 +1,3 @@
+import type { DeprecationView } from "@agentxm/extension-model/unstable/extensions/deprecation";
+export declare const formatDeprecationWarning: (extensionRef: string, deprecation: DeprecationView) => string;
+//# sourceMappingURL=deprecation-warning.d.ts.map

package/dist/src/deprecation-warning.js

@@ -0,0 +1,16 @@
+export const formatDeprecationWarning = (extensionRef, deprecation) => {
+    const guidance = [
+        deprecation.message,
+        deprecation.replacement?.status === "available"
+            ? `Use ${deprecation.replacement.fqn}`
+            : deprecation.replacement === undefined
+                ? undefined
+                : deprecation.replacement.fqn === undefined
+                    ? "The suggested replacement is unavailable or not visible"
+                    : `The suggested replacement ${deprecation.replacement.fqn} is unavailable`,
+    ].filter((value) => value !== undefined);
+    return guidance.length === 0
+        ? `${extensionRef} is deprecated`
+        : `${extensionRef} is deprecated: ${guidance.join(". ")}`;
+};
+//# sourceMappingURL=deprecation-warning.js.map

package/dist/src/error-mapping.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared error mapping helpers for registry and auth client implementations.
+ *
+ * Provides reusable predicates and mappers for converting generated client
+ * errors (RegistryClientError, HttpClientError, SchemaError) to the typed
+ * registry failure vocabulary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action";
+import type { RegistryClientError } from "./__generated__/registry-client.js";
+import { RegistryRequestFailed, type RegistryProblem } from "./errors.js";
+/**
+ * Safely read a string field from an unknown object.
+ */
+export declare const getString: (obj: unknown, field: string) => string | undefined;
+/**
+ * Create a type predicate that matches a specific RegistryClientError tag.
+ *
+ * Usage:
+ * ```ts
+ * Effect.catchIf(isRegistryClientError("ExtensionsGet404"), ...)
+ * ```
+ */
+export declare const isRegistryClientError: <Tag extends string>(tag: Tag) => (e: unknown) => e is RegistryClientError<Tag, unknown>;
+/**
+ * Type predicate for HttpClientError.
+ */
+export declare const isHttpClientError: (e: unknown) => e is HttpClientError.HttpClientError;
+/**
+ * Type predicate matching HttpClientErrors that are reasonable to retry:
+ * transport-level failures (ECONNREFUSED, DNS, etc.) and 5xx status codes.
+ * Deterministic failures — encode errors, invalid URLs, decode errors,
+ * 4xx statuses — are excluded so they fail fast.
+ */
+export declare const isTransientHttpClientError: (e: unknown) => e is HttpClientError.HttpClientError;
+/**
+ * Type predicate for SchemaError from effect/Schema.
+ */
+export declare const isSchemaError: (e: unknown) => boolean;
+/**
+ * Build user-facing suggestions for network errors.
+ * Detects localhost+HTTPS mismatches and provides targeted guidance.
+ */
+export declare const buildNetworkSuggestions: (baseUrl: string) => ReadonlyArray<SuggestedAction>;
+/**
+ * Build diagnostic details array for network errors.
+ * Detects localhost+HTTPS protocol mismatch.
+ */
+export declare const buildNetworkDiagnosis: (baseUrl: string) => ReadonlyArray<string>;
+/**
+ * Safely read the _tag from an unknown value.
+ */
+export declare const getTag: (e: unknown) => string | undefined;
+/**
+ * Check if an unknown value is a RegistryClientError (has _tag, request, response fields).
+ */
+export declare const isAnyRegistryClientError: (e: unknown) => e is RegistryClientError<string, unknown>;
+/**
+ * Check if an unknown value has a _tag ending with the given suffix.
+ */
+export declare const hasTagSuffix: (e: unknown, suffix: string) => boolean;
+/**
+ * Map an HttpClientError to a typed registry failure with the network category.
+ */
+export declare const mapNetworkError: (error: HttpClientError.HttpClientError, message: string, baseUrl: string) => RegistryRequestFailed;
+/**
+ * Map an input Schema encode error to a typed registry failure.
+ */
+export declare const mapInputSchemaError: (error: unknown, message: string) => RegistryRequestFailed;
+/**
+ * Map a response Schema decode error to a typed registry failure.
+ */
+export declare const mapResponseSchemaError: (error: unknown, message: string) => RegistryRequestFailed;
+export declare const mapSchemaError: (error: unknown, message: string) => RegistryRequestFailed;
+/**
+ * Map a RegistryClientError to a typed registry failure for unexpected status codes.
+ */
+export declare const mapUnexpectedStatusError: (error: RegistryClientError<string, unknown>, _message: string) => RegistryProblem;
+//# sourceMappingURL=error-mapping.d.ts.map