@agentxm/extension-model 0.28.4-bootstrap.0

package/dist/src/unstable/version-constraints/version-constraints.js

@@ -0,0 +1,144 @@
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+import * as semver from "semver";
+/**
+ * Canonical strict semver pattern from semver.org.
+ *
+ * Equivalent to `semver.valid(value) === value`: rejects leading `v`,
+ * whitespace, partial versions, and leading-zero numeric identifiers.
+ */
+export const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const SEMVER_RANGE_PATTERN = /^[~^<>=*xXvV0-9A-Za-z+| .-]+$/;
+/**
+ * Schema for an exact semver version (no ranges).
+ */
+export const VersionSchema = Schema.String.pipe(Schema.check(Schema.isPattern(SEMVER_PATTERN, {
+    message: "Expected a semver version (e.g., 1.0.0)",
+})), Schema.annotate({
+    identifier: "Version",
+    title: "Version",
+    description: "A semver version like 1.0.0. Ranges are not allowed here.",
+    examples: ["1.0.0", "2.3.1", "0.1.0-beta.1"],
+    message: "Expected a semver version (e.g., 1.0.0)",
+}), Schema.brand("Version"));
+/**
+ * Schema for a semver version range, including exact versions and range expressions.
+ */
+export const VersionRangeSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.makeFilter((value) => {
+    const normalized = semver.validRange(value);
+    return normalized !== null ? undefined : `Expected a semver version range, got: ${value}`;
+})), Schema.check(Schema.isPattern(SEMVER_RANGE_PATTERN, {
+    message: "Expected a semver version range (e.g., ^1.0.0)",
+})), Schema.annotate({
+    identifier: "VersionRange",
+    title: "Version Range",
+    description: 'A semver version range like ^1.0.0, ~2.3.0, >=1.0.0 <3.0.0, or an exact version 1.2.3. Use "*" to always resolve to the latest available version.',
+    examples: ["^1.0.0", "~2.4", ">=1 <3", "1.2.3", "*"],
+    message: "Expected a semver version range (e.g., ^1.0.0)",
+}), Schema.brand("VersionRange"));
+/**
+ * Decode a value as an exact semver version.
+ */
+export const decodeVersionSync = Schema.decodeUnknownSync(VersionSchema);
+/**
+ * Decode a value as a semver version range.
+ */
+export const decodeVersionRangeSync = Schema.decodeUnknownSync(VersionRangeSchema);
+const parseSemverVersion = (version) => semver.parse(version);
+/**
+ * Extract a version range suffix from a source string.
+ *
+ * Handles both namespaced (`@handle/name@^1.0.0`) and non-namespaced (`name@^1.0.0`) names.
+ * Returns `Option.none()` when no version suffix is present.
+ */
+export const parseVersionRange = (sourceString) => {
+    const decodeRange = (value) => {
+        try {
+            return Option.some(decodeVersionRangeSync(value));
+        }
+        catch {
+            return Option.none();
+        }
+    };
+    // For namespaced packages (@handle/name@range), find the @ after the handle
+    if (sourceString.startsWith("@")) {
+        const slashIndex = sourceString.indexOf("/");
+        if (slashIndex === -1)
+            return Option.none();
+        const afterHandle = sourceString.indexOf("@", slashIndex + 1);
+        if (afterHandle === -1)
+            return Option.none();
+        return decodeRange(sourceString.slice(afterHandle + 1));
+    }
+    // For non-namespaced packages (name@range)
+    const atIndex = sourceString.indexOf("@");
+    if (atIndex === -1)
+        return Option.none();
+    return decodeRange(sourceString.slice(atIndex + 1));
+};
+/**
+ * Check whether a string is a valid semver version range.
+ */
+export const isValidVersionRange = (range) => semver.validRange(range) !== null;
+/** Return one range representing the complete intersection, or undefined when unsatisfiable. */
+export const intersectVersionConstraints = (constraints) => {
+    let intersections = [""];
+    for (const constraint of constraints) {
+        const validRange = semver.validRange(constraint);
+        if (validRange === null)
+            return undefined;
+        const range = new semver.Range(validRange);
+        intersections = intersections.flatMap((current) => range.set.flatMap((comparators) => {
+            const candidate = [current, ...comparators.map((comparator) => comparator.value)]
+                .filter((part) => part.length > 0)
+                .join(" ");
+            return semver.minVersion(candidate) === null ? [] : [candidate];
+        }));
+        if (intersections.length === 0)
+            return undefined;
+    }
+    return intersections.join(" || ");
+};
+/**
+ * Check whether moving from `previousVersion` to `currentVersion` includes at
+ * least a minor version bump.
+ */
+export const hasMinorOrMajorVersionBump = (previousVersion, currentVersion) => {
+    const previous = parseSemverVersion(previousVersion);
+    const current = parseSemverVersion(currentVersion);
+    if (previous === null || current === null) {
+        return false;
+    }
+    return current.major > previous.major || current.minor > previous.minor;
+};
+/**
+ * Check whether a version satisfies a semver version range.
+ */
+export const versionSatisfiesRange = (version, range) => semver.satisfies(version, range);
+/**
+ * Select the maximum version that satisfies the range, independent of input
+ * order.
+ *
+ * - `Option.none()` range or `"*"` matches any version.
+ * - Invalid ranges match nothing.
+ */
+export const resolveVersionInRange = (versions, range) => {
+    const rangeStr = Option.getOrElse(range, () => "*");
+    // Wildcard means no range filtering
+    const isWildcard = rangeStr === "*";
+    // Validate the range early
+    if (!isWildcard && !isValidVersionRange(rangeStr)) {
+        return Option.none();
+    }
+    let selected;
+    for (const version of versions) {
+        if (!isWildcard && !semver.satisfies(version.version, rangeStr)) {
+            continue;
+        }
+        if (selected === undefined || semver.compareBuild(version.version, selected.version) > 0) {
+            selected = version;
+        }
+    }
+    return Option.fromUndefinedOr(selected);
+};
+//# sourceMappingURL=version-constraints.js.map

package/dist/src/unstable/workspace-files.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical filenames of the AXM workspace contract files.
+ *
+ * Both the AXM client and the AgentXM platform must agree on these names:
+ * published JSON Schemas, lint findings, and documentation all refer to them.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** The workspace settings file. */
+export declare const SETTINGS_FILENAME = "axm.json";
+/** The workspace lock file. */
+export declare const LOCKFILE_NAME = "axm-lock.yaml";
+//# sourceMappingURL=workspace-files.d.ts.map

package/dist/src/unstable/workspace-files.js

@@ -0,0 +1,13 @@
+/**
+ * Canonical filenames of the AXM workspace contract files.
+ *
+ * Both the AXM client and the AgentXM platform must agree on these names:
+ * published JSON Schemas, lint findings, and documentation all refer to them.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** The workspace settings file. */
+export const SETTINGS_FILENAME = "axm.json";
+/** The workspace lock file. */
+export const LOCKFILE_NAME = "axm-lock.yaml";
+//# sourceMappingURL=workspace-files.js.map

package/dist/src/unstable/workspace-scope.d.ts

@@ -0,0 +1,11 @@
+/**
+ * WorkspaceMutations scope helpers for CLI flags and workspace options.
+ *
+ * `project` uses the project root; `user` uses `~/.axm/workspace/`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const WORKSPACE_SCOPES: readonly ["project", "user"];
+export type WorkspaceScope = (typeof WORKSPACE_SCOPES)[number];
+export declare const DEFAULT_WORKSPACE_SCOPE: WorkspaceScope;
+//# sourceMappingURL=workspace-scope.d.ts.map

package/dist/src/unstable/workspace-scope.js

@@ -0,0 +1,10 @@
+/**
+ * WorkspaceMutations scope helpers for CLI flags and workspace options.
+ *
+ * `project` uses the project root; `user` uses `~/.axm/workspace/`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const WORKSPACE_SCOPES = ["project", "user"];
+export const DEFAULT_WORKSPACE_SCOPE = "project";
+//# sourceMappingURL=workspace-scope.js.map

package/package.json

@@ -0,0 +1,271 @@
+{
+  "name": "@agentxm/extension-model",
+  "version": "0.28.4-bootstrap.0",
+  "description": "Shared AgentXM extension model: identities, manifests, version constraints, and agent capabilities. 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/extension-model"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./unstable/agent-capabilities": {
+      "types": "./dist/src/unstable/agent-capabilities/index.d.ts",
+      "default": "./dist/src/unstable/agent-capabilities/index.js"
+    },
+    "./unstable/agent-capabilities/catalog": {
+      "types": "./dist/src/unstable/agent-capabilities/catalog.d.ts",
+      "default": "./dist/src/unstable/agent-capabilities/catalog.js"
+    },
+    "./unstable/agent-capabilities/derive": {
+      "types": "./dist/src/unstable/agent-capabilities/derive.d.ts",
+      "default": "./dist/src/unstable/agent-capabilities/derive.js"
+    },
+    "./unstable/agents/registry": {
+      "types": "./dist/src/unstable/agents/registry.d.ts",
+      "default": "./dist/src/unstable/agents/registry.js"
+    },
+    "./unstable/agents/types": {
+      "types": "./dist/src/unstable/agents/types.d.ts",
+      "default": "./dist/src/unstable/agents/types.js"
+    },
+    "./unstable/date-time": {
+      "types": "./dist/src/unstable/date-time.d.ts",
+      "default": "./dist/src/unstable/date-time.js"
+    },
+    "./unstable/discovery-walk": {
+      "types": "./dist/src/unstable/discovery-walk.d.ts",
+      "default": "./dist/src/unstable/discovery-walk.js"
+    },
+    "./unstable/extension-types": {
+      "types": "./dist/src/unstable/extension-types/index.d.ts",
+      "default": "./dist/src/unstable/extension-types/index.js"
+    },
+    "./unstable/extension-types/schema": {
+      "types": "./dist/src/unstable/extension-types/schema.d.ts",
+      "default": "./dist/src/unstable/extension-types/schema.js"
+    },
+    "./unstable/extension-types/standards": {
+      "types": "./dist/src/unstable/extension-types/standards.d.ts",
+      "default": "./dist/src/unstable/extension-types/standards.js"
+    },
+    "./unstable/extensions": {
+      "types": "./dist/src/unstable/extensions/index.d.ts",
+      "default": "./dist/src/unstable/extensions/index.js"
+    },
+    "./unstable/extensions/common": {
+      "types": "./dist/src/unstable/extensions/common.d.ts",
+      "default": "./dist/src/unstable/extensions/common.js"
+    },
+    "./unstable/extensions/deprecation": {
+      "types": "./dist/src/unstable/extensions/deprecation.d.ts",
+      "default": "./dist/src/unstable/extensions/deprecation.js"
+    },
+    "./unstable/extensions/fqn": {
+      "types": "./dist/src/unstable/extensions/fqn.d.ts",
+      "default": "./dist/src/unstable/extensions/fqn.js"
+    },
+    "./unstable/extensions/fqn-pattern": {
+      "types": "./dist/src/unstable/extensions/fqn-pattern.d.ts",
+      "default": "./dist/src/unstable/extensions/fqn-pattern.js"
+    },
+    "./unstable/extensions/handle": {
+      "types": "./dist/src/unstable/extensions/handle.d.ts",
+      "default": "./dist/src/unstable/extensions/handle.js"
+    },
+    "./unstable/extensions/installable-types": {
+      "types": "./dist/src/unstable/extensions/installable-types.d.ts",
+      "default": "./dist/src/unstable/extensions/installable-types.js"
+    },
+    "./unstable/extensions/license": {
+      "types": "./dist/src/unstable/extensions/license.d.ts",
+      "default": "./dist/src/unstable/extensions/license.js"
+    },
+    "./unstable/extensions/manifest-metadata": {
+      "types": "./dist/src/unstable/extensions/manifest-metadata.d.ts",
+      "default": "./dist/src/unstable/extensions/manifest-metadata.js"
+    },
+    "./unstable/extensions/refs/extension-ref": {
+      "types": "./dist/src/unstable/extensions/refs/extension-ref.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/extension-ref.js"
+    },
+    "./unstable/extensions/refs/hook": {
+      "types": "./dist/src/unstable/extensions/refs/hook.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/hook.js"
+    },
+    "./unstable/extensions/refs/knowledge": {
+      "types": "./dist/src/unstable/extensions/refs/knowledge.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/knowledge.js"
+    },
+    "./unstable/extensions/refs/mcp-server": {
+      "types": "./dist/src/unstable/extensions/refs/mcp-server.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/mcp-server.js"
+    },
+    "./unstable/extensions/refs/pack": {
+      "types": "./dist/src/unstable/extensions/refs/pack.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/pack.js"
+    },
+    "./unstable/extensions/refs/ref-base": {
+      "types": "./dist/src/unstable/extensions/refs/ref-base.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/ref-base.js"
+    },
+    "./unstable/extensions/refs/rule": {
+      "types": "./dist/src/unstable/extensions/refs/rule.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/rule.js"
+    },
+    "./unstable/extensions/refs/skill": {
+      "types": "./dist/src/unstable/extensions/refs/skill.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/skill.js"
+    },
+    "./unstable/extensions/refs/subagent": {
+      "types": "./dist/src/unstable/extensions/refs/subagent.d.ts",
+      "default": "./dist/src/unstable/extensions/refs/subagent.js"
+    },
+    "./unstable/extensions/registry-source": {
+      "types": "./dist/src/unstable/extensions/registry-source.d.ts",
+      "default": "./dist/src/unstable/extensions/registry-source.js"
+    },
+    "./unstable/extensions/release-age": {
+      "types": "./dist/src/unstable/extensions/release-age.d.ts",
+      "default": "./dist/src/unstable/extensions/release-age.js"
+    },
+    "./unstable/extensions/universal-skills-dir": {
+      "types": "./dist/src/unstable/extensions/universal-skills-dir.d.ts",
+      "default": "./dist/src/unstable/extensions/universal-skills-dir.js"
+    },
+    "./unstable/hooks/manifest-schema": {
+      "types": "./dist/src/unstable/hooks/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/hooks/manifest-schema.js"
+    },
+    "./unstable/knowledge": {
+      "types": "./dist/src/unstable/knowledge/index.d.ts",
+      "default": "./dist/src/unstable/knowledge/index.js"
+    },
+    "./unstable/knowledge/concept-ref": {
+      "types": "./dist/src/unstable/knowledge/concept-ref.d.ts",
+      "default": "./dist/src/unstable/knowledge/concept-ref.js"
+    },
+    "./unstable/knowledge/manifest-schema": {
+      "types": "./dist/src/unstable/knowledge/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/knowledge/manifest-schema.js"
+    },
+    "./unstable/mcps/manifest-schema": {
+      "types": "./dist/src/unstable/mcps/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/mcps/manifest-schema.js"
+    },
+    "./unstable/package-urls": {
+      "types": "./dist/src/unstable/package-urls/index.d.ts",
+      "default": "./dist/src/unstable/package-urls/index.js"
+    },
+    "./unstable/packaging": {
+      "types": "./dist/src/unstable/packaging/index.d.ts",
+      "default": "./dist/src/unstable/packaging/index.js"
+    },
+    "./unstable/packaging/package-type": {
+      "types": "./dist/src/unstable/packaging/package-type.d.ts",
+      "default": "./dist/src/unstable/packaging/package-type.js"
+    },
+    "./unstable/packaging/package-url": {
+      "types": "./dist/src/unstable/packaging/package-url.d.ts",
+      "default": "./dist/src/unstable/packaging/package-url.js"
+    },
+    "./unstable/packs/manifest-schema": {
+      "types": "./dist/src/unstable/packs/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/packs/manifest-schema.js"
+    },
+    "./unstable/path-types": {
+      "types": "./dist/src/unstable/path-types.d.ts",
+      "default": "./dist/src/unstable/path-types.js"
+    },
+    "./unstable/rules/manifest-schema": {
+      "types": "./dist/src/unstable/rules/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/rules/manifest-schema.js"
+    },
+    "./unstable/schema-issues": {
+      "types": "./dist/src/unstable/schema-issues.d.ts",
+      "default": "./dist/src/unstable/schema-issues.js"
+    },
+    "./unstable/skills/manifest-schema": {
+      "types": "./dist/src/unstable/skills/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/skills/manifest-schema.js"
+    },
+    "./unstable/sources/forge-grammar": {
+      "types": "./dist/src/unstable/sources/forge-grammar.d.ts",
+      "default": "./dist/src/unstable/sources/forge-grammar.js"
+    },
+    "./unstable/sources/parser": {
+      "types": "./dist/src/unstable/sources/parser.d.ts",
+      "default": "./dist/src/unstable/sources/parser.js"
+    },
+    "./unstable/sources/printer": {
+      "types": "./dist/src/unstable/sources/printer.d.ts",
+      "default": "./dist/src/unstable/sources/printer.js"
+    },
+    "./unstable/sources/source-hash": {
+      "types": "./dist/src/unstable/sources/source-hash.d.ts",
+      "default": "./dist/src/unstable/sources/source-hash.js"
+    },
+    "./unstable/sources/source-host-provider": {
+      "types": "./dist/src/unstable/sources/source-host-provider.d.ts",
+      "default": "./dist/src/unstable/sources/source-host-provider.js"
+    },
+    "./unstable/sources/types": {
+      "types": "./dist/src/unstable/sources/types.d.ts",
+      "default": "./dist/src/unstable/sources/types.js"
+    },
+    "./unstable/sources/workspace": {
+      "types": "./dist/src/unstable/sources/workspace.d.ts",
+      "default": "./dist/src/unstable/sources/workspace.js"
+    },
+    "./unstable/subagents/manifest-schema": {
+      "types": "./dist/src/unstable/subagents/manifest-schema.d.ts",
+      "default": "./dist/src/unstable/subagents/manifest-schema.js"
+    },
+    "./unstable/version-constraints": {
+      "types": "./dist/src/unstable/version-constraints/version-constraints.d.ts",
+      "default": "./dist/src/unstable/version-constraints/version-constraints.js"
+    },
+    "./unstable/workspace-files": {
+      "types": "./dist/src/unstable/workspace-files.d.ts",
+      "default": "./dist/src/unstable/workspace-files.js"
+    },
+    "./unstable/workspace-scope": {
+      "types": "./dist/src/unstable/workspace-scope.d.ts",
+      "default": "./dist/src/unstable/workspace-scope.js"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "effect": "4.0.0-rc.112",
+    "packageurl-js": "^2.0.1",
+    "semver": "^7.8.5",
+    "spdx-expression-parse": "4.0.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/semver": "^7.5.8",
+    "@types/spdx-expression-parse": "4.0.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  }
+}