@agentxm/extension-model 0.28.4-bootstrap.0

package/dist/src/unstable/mcps/manifest-schema.js

@@ -0,0 +1,230 @@
+/**
+ * MCP server manifest schema definition.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import { CommonManifestBaseFields, ExtensionNameSchema, NonPackManifestFields, } from "../extensions/common.js";
+/**
+ * Filename for MCP server manifest files.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const MCP_SERVER_MANIFEST_FILENAME = "mcp.json";
+/**
+ * URL for the MCP server manifest JSON Schema.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const MCP_SERVER_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/mcp.schema.json";
+/** @experimental This API is unstable and may change without notice. */
+export const MCP_SERVER_REGISTRY_SERVER_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
+const HttpUrlSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(/^https?:\/\/[^\s]+$/, {
+    message: "Expected an HTTP(S) URL.",
+})));
+const Sha256Schema = Schema.String.pipe(Schema.check(Schema.isPattern(/^[a-f0-9]{64}$/, {
+    message: "Expected a lowercase SHA-256 hex digest.",
+})));
+const McpRegistryInputFields = {
+    choices: Schema.optional(Schema.Array(Schema.String)),
+    default: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+    format: Schema.optional(Schema.Literals(["string", "number", "boolean", "filepath"])),
+    isRequired: Schema.optional(Schema.Boolean),
+    isSecret: Schema.optional(Schema.Boolean),
+    placeholder: Schema.optional(Schema.String),
+    value: Schema.optional(Schema.String),
+    variables: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+};
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryInputSchema = Schema.Struct({
+    ...McpRegistryInputFields,
+}).annotate({
+    identifier: "McpRegistryInput",
+    title: "MCP Registry Input",
+    description: "Input metadata from the MCP registry server.json schema.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryKeyValueInputSchema = Schema.Struct({
+    ...McpRegistryInputFields,
+    name: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "input name is required" })),
+}).annotate({
+    identifier: "McpRegistryKeyValueInput",
+    title: "MCP Registry Key/Value Input",
+    description: "Named header or environment variable input.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryNamedArgumentSchema = Schema.Struct({
+    ...McpRegistryInputFields,
+    type: Schema.Literal("named"),
+    name: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "argument name is required" })),
+    isRepeated: Schema.optional(Schema.Boolean),
+}).annotate({
+    identifier: "McpRegistryNamedArgument",
+    title: "MCP Registry Named Argument",
+    description: "A named command-line argument.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryPositionalArgumentSchema = Schema.Union([
+    Schema.Struct({
+        ...McpRegistryInputFields,
+        type: Schema.Literal("positional"),
+        isRepeated: Schema.optional(Schema.Boolean),
+        valueHint: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "positional argument valueHint is required" })),
+    }),
+    Schema.Struct({
+        ...McpRegistryInputFields,
+        type: Schema.Literal("positional"),
+        isRepeated: Schema.optional(Schema.Boolean),
+        value: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "positional argument value is required" })),
+    }),
+]).annotate({
+    identifier: "McpRegistryPositionalArgument",
+    title: "MCP Registry Positional Argument",
+    description: "A positional command-line argument.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryArgumentSchema = Schema.Union([
+    McpRegistryPositionalArgumentSchema,
+    McpRegistryNamedArgumentSchema,
+]).annotate({
+    identifier: "McpRegistryArgument",
+    title: "MCP Registry Argument",
+    description: "Command-line argument metadata from the MCP registry schema.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryIconSchema = Schema.Struct({
+    src: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "icon src is required" })),
+    mimeType: Schema.optional(Schema.Literals(["image/png", "image/jpeg", "image/jpg", "image/svg+xml", "image/webp"])),
+    sizes: Schema.optional(Schema.Array(Schema.String.pipe(Schema.check(Schema.isPattern(/^(\d+x\d+|any)$/, {
+        message: "Expected an icon size like 48x48 or any.",
+    }))))),
+    theme: Schema.optional(Schema.Literals(["light", "dark"])),
+}).annotate({
+    identifier: "McpRegistryIcon",
+    title: "MCP Registry Icon",
+    description: "Optional icon metadata from the MCP registry schema.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryStdioTransportSchema = Schema.Struct({
+    type: Schema.Literal("stdio"),
+}).annotate({
+    identifier: "McpRegistryStdioTransport",
+    title: "MCP Registry Stdio Transport",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryStreamableHttpTransportSchema = Schema.Struct({
+    type: Schema.Literal("streamable-http"),
+    url: HttpUrlSchema.pipe(Schema.annotateKey({ messageMissingKey: "transport url is required" })),
+    headers: Schema.optional(Schema.Array(McpRegistryKeyValueInputSchema)),
+}).annotate({
+    identifier: "McpRegistryStreamableHttpTransport",
+    title: "MCP Registry Streamable HTTP Transport",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistrySseTransportSchema = Schema.Struct({
+    type: Schema.Literal("sse"),
+    url: HttpUrlSchema.pipe(Schema.annotateKey({ messageMissingKey: "transport url is required" })),
+    headers: Schema.optional(Schema.Array(McpRegistryKeyValueInputSchema)),
+}).annotate({
+    identifier: "McpRegistrySseTransport",
+    title: "MCP Registry SSE Transport",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryLocalTransportSchema = Schema.Union([
+    McpRegistryStdioTransportSchema,
+    McpRegistryStreamableHttpTransportSchema,
+    McpRegistrySseTransportSchema,
+]).annotate({
+    identifier: "McpRegistryLocalTransport",
+    title: "MCP Registry Local Transport",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryRemoteTransportSchema = Schema.Union([
+    Schema.Struct({
+        type: Schema.Literal("streamable-http"),
+        url: HttpUrlSchema.pipe(Schema.annotateKey({ messageMissingKey: "transport url is required" })),
+        headers: Schema.optional(Schema.Array(McpRegistryKeyValueInputSchema)),
+        variables: Schema.optional(Schema.Record(Schema.String, McpRegistryInputSchema)),
+    }),
+    Schema.Struct({
+        type: Schema.Literal("sse"),
+        url: HttpUrlSchema.pipe(Schema.annotateKey({ messageMissingKey: "transport url is required" })),
+        headers: Schema.optional(Schema.Array(McpRegistryKeyValueInputSchema)),
+        variables: Schema.optional(Schema.Record(Schema.String, McpRegistryInputSchema)),
+    }),
+]).annotate({
+    identifier: "McpRegistryRemoteTransport",
+    title: "MCP Registry Remote Transport",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryPackageSchema = Schema.Struct({
+    registryType: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "package registryType is required" })),
+    identifier: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "package identifier is required" })),
+    transport: McpRegistryLocalTransportSchema.pipe(Schema.annotateKey({ messageMissingKey: "package transport is required" })),
+    version: Schema.optional(Schema.NonEmptyString.pipe(Schema.check(Schema.makeFilter((value) => value === "latest" ? "Package version must not be latest." : true)))),
+    registryBaseUrl: Schema.optional(Schema.String),
+    runtimeHint: Schema.optional(Schema.String),
+    runtimeArguments: Schema.optional(Schema.Array(McpRegistryArgumentSchema)),
+    packageArguments: Schema.optional(Schema.Array(McpRegistryArgumentSchema)),
+    environmentVariables: Schema.optional(Schema.Array(McpRegistryKeyValueInputSchema)),
+    fileSha256: Schema.optional(Sha256Schema),
+}).annotate({
+    identifier: "McpRegistryPackage",
+    title: "MCP Registry Package",
+    description: "Installable MCP server package distribution.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryRepositorySchema = Schema.Struct({
+    url: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "repository url is required" })),
+    source: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "repository source is required" })),
+    id: Schema.optional(Schema.String),
+    subfolder: Schema.optional(Schema.String),
+}).annotate({
+    identifier: "McpRegistryRepository",
+    title: "MCP Registry Repository",
+    description: "Repository metadata for an MCP server.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const McpRegistryServerDetailSchema = Schema.Struct({
+    $schema: Schema.optional(Schema.String),
+    name: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "MCP registry server name is required" }), Schema.check(Schema.isPattern(/^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/, {
+        message: "Expected reverse-DNS MCP server name with one slash.",
+    }))),
+    description: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "MCP registry server description is required" })),
+    version: Schema.String.pipe(Schema.annotateKey({ messageMissingKey: "MCP registry server version is required" })),
+    title: Schema.optional(Schema.NonEmptyString),
+    packages: Schema.optional(Schema.Array(McpRegistryPackageSchema)),
+    remotes: Schema.optional(Schema.Array(McpRegistryRemoteTransportSchema)),
+    repository: Schema.optional(McpRegistryRepositorySchema),
+    icons: Schema.optional(Schema.Array(McpRegistryIconSchema)),
+    websiteUrl: Schema.optional(Schema.String),
+    _meta: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}).annotate({
+    identifier: "McpRegistryServerDetail",
+    title: "MCP Registry Server Detail",
+    description: "Verbatim MCP registry server.json ServerDetail embedded in AXM mcp.json manifests.",
+});
+/**
+ * Schema for MCP server manifest files (mcp.json).
+ *
+ * MCP servers provide Model Context Protocol endpoints that
+ * extend coding agent capabilities with external tools and resources.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const McpServerManifestSchema = Schema.Struct({
+    $schema: Schema.optional(Schema.String),
+    ...CommonManifestBaseFields,
+    ...NonPackManifestFields,
+    type: Schema.Literal("mcp-server"),
+    name: ExtensionNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "MCP server name is required" }), Schema.annotate({
+        description: "Short name for this MCP server within its owner namespace. Combined with owner, forms the FQN @owner/mcps/<name>.",
+    })),
+    server: McpRegistryServerDetailSchema.pipe(Schema.annotateKey({ messageMissingKey: "MCP registry server detail is required" })),
+}).annotate({
+    identifier: "McpServerManifest",
+    title: "MCP Server Manifest",
+    description: "Extension manifest file for MCP server. Registers a Model Context Protocol server that coding agents can connect to for additional tools and resources.",
+});
+//# sourceMappingURL=manifest-schema.js.map

package/dist/src/unstable/package-urls/companion-package.d.ts

@@ -0,0 +1,14 @@
+import * as Schema from "effect/Schema";
+export declare const CompanionPackageSchema: Schema.Struct<{
+    readonly purl: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+    readonly versionRange: Schema.optional<Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+        readonly raw: Schema.NonEmptyString;
+        readonly scheme: Schema.NonEmptyString;
+        readonly constraints: Schema.$Array<Schema.Struct<{
+            readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+            readonly version: Schema.NonEmptyString;
+        }>>;
+    }>>, Schema.NonEmptyString, never, never>, "VersRange">>;
+}>;
+export type CompanionPackage = Schema.Schema.Type<typeof CompanionPackageSchema>;
+//# sourceMappingURL=companion-package.d.ts.map

package/dist/src/unstable/package-urls/companion-package.js

@@ -0,0 +1,44 @@
+import * as Schema from "effect/Schema";
+import { parsePurlIdentity } from "./internal.js";
+import { PackageIdentityPurlSchema } from "./package-identity-purl.js";
+import { isConcreteEcosystemScheme, splitVersAtScheme, VersRangeSchema } from "./vers-range.js";
+const CompanionPackageShapeSchema = Schema.Struct({
+    purl: PackageIdentityPurlSchema,
+    versionRange: Schema.optional(VersRangeSchema),
+}).annotate({
+    identifier: "CompanionPackageShape",
+    title: "Companion Package",
+    description: "A companion package purl identity with an optional VERS compatibility range.",
+});
+const validateCompanionPackage = (value) => {
+    const parsed = parsePurlIdentity(value.purl);
+    if (typeof parsed === "string") {
+        return parsed;
+    }
+    if (!isConcreteEcosystemScheme(parsed.type)) {
+        return `Companion package purl ecosystem '${parsed.type}' is not supported.`;
+    }
+    if (value.versionRange === undefined) {
+        return undefined;
+    }
+    let versionRangeScheme;
+    if (typeof value.versionRange === "string") {
+        const split = splitVersAtScheme(value.versionRange);
+        if (typeof split === "string") {
+            return split;
+        }
+        versionRangeScheme = split.scheme;
+    }
+    else {
+        versionRangeScheme = value.versionRange.scheme;
+    }
+    return parsed.type === versionRangeScheme
+        ? undefined
+        : `Companion package purl ecosystem '${parsed.type}' must match VERS scheme '${versionRangeScheme}'.`;
+};
+export const CompanionPackageSchema = CompanionPackageShapeSchema.pipe(Schema.check(Schema.makeFilter(validateCompanionPackage)), Schema.annotate({
+    identifier: "CompanionPackage",
+    title: "Companion Package",
+    description: "A companion package declaration. The purl is an identity-only Package URL; versionRange is an optional VERS expression whose scheme must match the purl ecosystem.",
+}));
+//# sourceMappingURL=companion-package.js.map

package/dist/src/unstable/package-urls/index.d.ts

@@ -0,0 +1,4 @@
+export { CompanionPackageSchema, type CompanionPackage } from "./companion-package.js";
+export { PACKAGE_IDENTITY_PURL_DESCRIPTION, PackageIdentityPurlSchema, type PackageIdentityPurl, } from "./package-identity-purl.js";
+export { VersComparatorSchema, VersConstraintSchema, VersRangeSchema, parseVersRange, splitVersAtScheme, type VersComparator, type VersConstraint, type VersRange, } from "./vers-range.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/package-urls/index.js

@@ -0,0 +1,4 @@
+export { CompanionPackageSchema } from "./companion-package.js";
+export { PACKAGE_IDENTITY_PURL_DESCRIPTION, PackageIdentityPurlSchema, } from "./package-identity-purl.js";
+export { VersComparatorSchema, VersConstraintSchema, VersRangeSchema, parseVersRange, splitVersAtScheme, } from "./vers-range.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/package-urls/internal.d.ts

@@ -0,0 +1,6 @@
+export interface ParsedPurlIdentity {
+    readonly type: string;
+    readonly version: string | undefined;
+}
+export declare const parsePurlIdentity: (value: string) => ParsedPurlIdentity | string;
+//# sourceMappingURL=internal.d.ts.map

package/dist/src/unstable/package-urls/internal.js

@@ -0,0 +1,17 @@
+import { PackageURL } from "packageurl-js";
+export const parsePurlIdentity = (value) => {
+    try {
+        const [type, , , version] = PackageURL.parseString(value);
+        if (type === undefined) {
+            return `Expected valid purl, got: ${value}`;
+        }
+        return {
+            type: type.toLowerCase(),
+            version: version ?? undefined,
+        };
+    }
+    catch {
+        return `Expected valid purl, got: ${value}`;
+    }
+};
+//# sourceMappingURL=internal.js.map

package/dist/src/unstable/package-urls/package-identity-purl.d.ts

@@ -0,0 +1,5 @@
+import * as Schema from "effect/Schema";
+export declare const PACKAGE_IDENTITY_PURL_DESCRIPTION = "A Package URL (purl) identity for a companion package. Companion package purls are identities, not pins: omit the purl @version segment and put compatibility constraints in versionRange.";
+export declare const PackageIdentityPurlSchema: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+export type PackageIdentityPurl = Schema.Schema.Type<typeof PackageIdentityPurlSchema>;
+//# sourceMappingURL=package-identity-purl.d.ts.map

package/dist/src/unstable/package-urls/package-identity-purl.js

@@ -0,0 +1,26 @@
+import * as Schema from "effect/Schema";
+import { parsePurlIdentity } from "./internal.js";
+export const PACKAGE_IDENTITY_PURL_DESCRIPTION = "A Package URL (purl) identity for a companion package. Companion package purls are identities, not pins: omit the purl @version segment and put compatibility constraints in versionRange.";
+const PACKAGE_URL_PATTERN = /^[Pp][Kk][Gg]:[a-zA-Z][a-zA-Z0-9.+-]*\/.+$/;
+const validatePackageIdentityPurl = (value) => {
+    const parsed = parsePurlIdentity(value);
+    if (typeof parsed === "string") {
+        return `Expected valid companion package purl, got: ${value}`;
+    }
+    return parsed.version === undefined
+        ? undefined
+        : `Companion package purls are identities, not pins. Move ${value}'s version into versionRange.`;
+};
+export const PackageIdentityPurlSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.isPattern(PACKAGE_URL_PATTERN, {
+    title: "Package Identity Purl",
+    description: PACKAGE_IDENTITY_PURL_DESCRIPTION,
+    examples: ["pkg:npm/react", "pkg:pypi/requests", "pkg:cargo/serde"],
+    message: "Expected a Package URL like pkg:npm/react",
+})), Schema.check(Schema.makeFilter(validatePackageIdentityPurl)), Schema.annotate({
+    identifier: "PackageIdentityPurl",
+    title: "Package Identity Purl",
+    description: PACKAGE_IDENTITY_PURL_DESCRIPTION,
+    examples: ["pkg:npm/react", "pkg:pypi/requests", "pkg:cargo/serde"],
+    message: "Companion package purls are identities, not pins. Use versionRange for versions.",
+}), Schema.brand("PackageIdentityPurl"));
+//# sourceMappingURL=package-identity-purl.js.map

package/dist/src/unstable/package-urls/vers-range.d.ts

@@ -0,0 +1,34 @@
+import * as Schema from "effect/Schema";
+export declare const CONCRETE_ECOSYSTEM_SCHEMES: readonly ["apk", "bazel", "cargo", "cocoapods", "composer", "conan", "conda", "cpan", "cran", "deb", "docker", "gem", "golang", "hackage", "hex", "huggingface", "julia", "jsr", "luarocks", "maven", "mojo", "npm", "nuget", "opam", "pub", "pypi", "rpm", "swift", "zig"];
+export declare const VersComparatorSchema: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+export type VersComparator = Schema.Schema.Type<typeof VersComparatorSchema>;
+export declare const VersConstraintSchema: Schema.Struct<{
+    readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+    readonly version: Schema.NonEmptyString;
+}>;
+export type VersConstraint = Schema.Schema.Type<typeof VersConstraintSchema>;
+declare const VersRangeDecodedSchema: Schema.Struct<{
+    readonly raw: Schema.NonEmptyString;
+    readonly scheme: Schema.NonEmptyString;
+    readonly constraints: Schema.$Array<Schema.Struct<{
+        readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+        readonly version: Schema.NonEmptyString;
+    }>>;
+}>;
+export declare const isConcreteEcosystemScheme: (scheme: string) => boolean;
+export declare const splitVersAtScheme: (value: string) => {
+    readonly scheme: string;
+    readonly constraintsText: string;
+} | string;
+export declare const parseVersRange: (value: string) => Schema.Schema.Type<typeof VersRangeDecodedSchema> | string;
+export declare const VersRangeSchema: Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+    readonly raw: Schema.NonEmptyString;
+    readonly scheme: Schema.NonEmptyString;
+    readonly constraints: Schema.$Array<Schema.Struct<{
+        readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+        readonly version: Schema.NonEmptyString;
+    }>>;
+}>>, Schema.NonEmptyString, never, never>, "VersRange">;
+export type VersRange = Schema.Schema.Type<typeof VersRangeSchema>;
+export {};
+//# sourceMappingURL=vers-range.d.ts.map

package/dist/src/unstable/package-urls/vers-range.js

@@ -0,0 +1,163 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+const VERS_PREFIX = "vers:";
+const SENTINEL_SCHEMES = [
+    "all",
+    "none",
+    "semver",
+    "generic",
+    "intdot",
+    "lexicographic",
+    "datetime",
+];
+export const CONCRETE_ECOSYSTEM_SCHEMES = [
+    "apk",
+    "bazel",
+    "cargo",
+    "cocoapods",
+    "composer",
+    "conan",
+    "conda",
+    "cpan",
+    "cran",
+    "deb",
+    "docker",
+    "gem",
+    "golang",
+    "hackage",
+    "hex",
+    "huggingface",
+    "julia",
+    "jsr",
+    "luarocks",
+    "maven",
+    "mojo",
+    "npm",
+    "nuget",
+    "opam",
+    "pub",
+    "pypi",
+    "rpm",
+    "swift",
+    "zig",
+];
+export const VersComparatorSchema = Schema.Literals(["=", "!=", "<", "<=", ">", ">="]).annotate({
+    identifier: "VersComparator",
+    title: "VERS Comparator",
+    description: "A comparator inside an AgentXM-supported VERS constraint.",
+});
+export const VersConstraintSchema = Schema.Struct({
+    comparator: VersComparatorSchema,
+    version: Schema.NonEmptyString,
+}).annotate({
+    identifier: "VersConstraint",
+    title: "VERS Constraint",
+    description: "A parsed comparator and version from an AgentXM-supported VERS range.",
+});
+const VersRangeDecodedSchema = Schema.Struct({
+    raw: Schema.NonEmptyString,
+    scheme: Schema.NonEmptyString,
+    constraints: Schema.Array(VersConstraintSchema),
+}).annotate({
+    identifier: "VersRangeDecoded",
+    title: "VERS Range",
+    description: "A decoded VERS range with its raw value, ecosystem scheme, and constraints.",
+});
+const isSentinelScheme = (scheme) => SENTINEL_SCHEMES.some((candidate) => candidate === scheme);
+export const isConcreteEcosystemScheme = (scheme) => CONCRETE_ECOSYSTEM_SCHEMES.some((candidate) => candidate === scheme);
+const parseComparator = (constraint) => {
+    if (constraint.startsWith(">="))
+        return ">=";
+    if (constraint.startsWith("<="))
+        return "<=";
+    if (constraint.startsWith("!="))
+        return "!=";
+    if (constraint.startsWith(">"))
+        return ">";
+    if (constraint.startsWith("<"))
+        return "<";
+    if (constraint.startsWith("="))
+        return "=";
+    return undefined;
+};
+const parseConstraint = (constraint) => {
+    const comparator = parseComparator(constraint);
+    if (comparator === undefined) {
+        return `Expected VERS constraint to start with one of =, !=, <, <=, >, or >=, got: ${constraint}`;
+    }
+    const version = constraint.slice(comparator.length);
+    if (version.length === 0) {
+        return `Expected VERS constraint version after ${comparator}`;
+    }
+    return { comparator, version };
+};
+export const splitVersAtScheme = (value) => {
+    if (!value.startsWith(VERS_PREFIX)) {
+        return "Expected VERS range to start with the vers: prefix.";
+    }
+    const withoutPrefix = value.slice(VERS_PREFIX.length);
+    const slashIndex = withoutPrefix.indexOf("/");
+    if (slashIndex <= 0) {
+        return "Expected VERS range to include a non-empty scheme before '/'.";
+    }
+    const scheme = withoutPrefix.slice(0, slashIndex);
+    const constraintsText = withoutPrefix.slice(slashIndex + 1);
+    if (constraintsText.length === 0) {
+        return "Expected VERS range to include at least one constraint after '/'.";
+    }
+    return { scheme, constraintsText };
+};
+export const parseVersRange = (value) => {
+    if (value.includes("%")) {
+        return "VERS percent-encoded values are not supported yet.";
+    }
+    const split = splitVersAtScheme(value);
+    if (typeof split === "string") {
+        return split;
+    }
+    if (isSentinelScheme(split.scheme)) {
+        return `VERS scheme '${split.scheme}' is a generic scheme; generic schemes are not accepted for companion packages.`;
+    }
+    if (!isConcreteEcosystemScheme(split.scheme)) {
+        return `VERS scheme '${split.scheme}' is not a known concrete package ecosystem.`;
+    }
+    if (split.constraintsText === "*") {
+        return 'omit versionRange to express "any version"; wildcard-only VERS ranges are not accepted.';
+    }
+    const constraints = [];
+    for (const constraintText of split.constraintsText.split("|")) {
+        if (constraintText.length === 0) {
+            return "Expected VERS range constraints to be non-empty.";
+        }
+        const constraint = parseConstraint(constraintText);
+        if (typeof constraint === "string") {
+            return constraint;
+        }
+        constraints.push(constraint);
+    }
+    return {
+        raw: value,
+        scheme: split.scheme,
+        constraints,
+    };
+};
+const parseVersRangeEffect = (value) => {
+    const result = parseVersRange(value);
+    return typeof result === "string"
+        ? Effect.fail(new SchemaIssue.Forbidden({ message: result }, value))
+        : Effect.succeed(result);
+};
+export const VersRangeSchema = Schema.NonEmptyString.pipe(Schema.decodeTo(Schema.toType(VersRangeDecodedSchema), SchemaTransformation.transformOrFail({
+    decode: parseVersRangeEffect,
+    encode: (value) => Effect.succeed(value.raw),
+})), Schema.annotate({
+    identifier: "VersRange",
+    title: "VERS Range",
+    description: "A VERS version range like vers:npm/>=1.0.0|<2.0.0. Use a concrete package ecosystem scheme matching the companion purl type. Omit versionRange for any-version compatibility.",
+    message: "Expected a VERS range like vers:npm/>=1.0.0|<2.0.0",
+}), Schema.annotateEncoded({
+    examples: ["vers:npm/>=18.0.0|<19.0.0", "vers:pypi/>=2.31.0", "vers:cargo/>=1.0.0"],
+}), Schema.brand("VersRange"));
+//# sourceMappingURL=vers-range.js.map

package/dist/src/unstable/packaging/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { type PackageType, PackageTypeSchema } from "./package-type.js";
+export { type PackageUrlParts, PackageUrlPartsSchema, PackageUrlSchema, formatPackageDisplay, } from "./package-url.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/packaging/index.js

@@ -0,0 +1,8 @@
+/**
+ * Area barrel for the package public surface.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export { PackageTypeSchema } from "./package-type.js";
+export { PackageUrlPartsSchema, PackageUrlSchema, formatPackageDisplay, } from "./package-url.js";
+//# sourceMappingURL=index.js.map

package/dist/src/unstable/packaging/package-type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Package type schema for purl type components.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Branded string schema for purl package types (e.g. "npm", "pypi", "maven").
+ *
+ * Enforces the purl spec character set and lowercase canonical form. To
+ * accept inputs in any case, decode through {@link PackageUrlSchema} which
+ * normalises the type before constructing parts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const PackageTypeSchema: Schema.brand<Schema.String, "PackageType">;
+/**
+ * Inferred type for purl package types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type PackageType = Schema.Schema.Type<typeof PackageTypeSchema>;
+//# sourceMappingURL=package-type.d.ts.map

package/dist/src/unstable/packaging/package-type.js

@@ -0,0 +1,31 @@
+/**
+ * Package type schema for purl type components.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Spec-conformant character set for a purl type: lowercase ASCII letters,
+ * digits, period, plus, and dash; must start with a letter. The purl spec
+ * declares `type` case-insensitive with a lowercase canonical form, so this
+ * schema accepts only the canonical form.
+ *
+ * @see https://github.com/package-url/purl-spec
+ */
+const PACKAGE_TYPE_PATTERN = /^[a-z][a-z0-9.+-]*$/;
+/**
+ * Branded string schema for purl package types (e.g. "npm", "pypi", "maven").
+ *
+ * Enforces the purl spec character set and lowercase canonical form. To
+ * accept inputs in any case, decode through {@link PackageUrlSchema} which
+ * normalises the type before constructing parts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const PackageTypeSchema = Schema.String.pipe(Schema.check(Schema.isPattern(PACKAGE_TYPE_PATTERN, {
+    title: "Package Type",
+    description: "A purl package type identifier in canonical lowercase form (e.g. npm, pypi, maven). Allowed characters: ASCII letters, digits, '.', '+', '-'; must start with a letter.",
+    examples: ["npm", "pypi", "maven", "golang"],
+    message: "Expected a lowercase purl package type like npm or pypi",
+})), Schema.brand("PackageType"), Schema.annotate({ identifier: "PackageType" }));
+//# sourceMappingURL=package-type.js.map