commandmate 0.11.4 → 0.12.0

package/dist/server/src/lib/skills/compatibility.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * CommandMate compatibility judgement and version resolution (Issue #1231)
+ *
+ * Pure functions: no filesystem, no network, no process state. The host version
+ * is always an explicit argument so UI, API and CLI can evaluate the same
+ * Catalog against the same rules and reach the same verdict.
+ *
+ * Every verdict carries a stable machine code *and* a human-readable message
+ * (受入条件: "互換性NGの理由がmachine-readable codeとhuman-readable messageで返る").
+ * Messages are built from the code, the declared range and the host version
+ * only — never from a path, token or URL.
+ *
+ * @module lib/skills/compatibility
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillRecommendationReason = exports.UNKNOWN_HOST_VERSION_SENTINEL = exports.SKILL_COMPATIBILITY_MESSAGE_KEYS = exports.SkillCompatibilityReason = void 0;
+exports.normalizeHostVersion = normalizeHostVersion;
+exports.evaluateCommandMateCompatibility = evaluateCommandMateCompatibility;
+exports.evaluateVersionCompatibility = evaluateVersionCompatibility;
+exports.describeAgentCompatibility = describeAgentCompatibility;
+exports.resolveSkillVersions = resolveSkillVersions;
+exports.findSkillCatalogEntry = findSkillCatalogEntry;
+// Sibling modules of the same package are imported directly rather than through
+// the `@/lib/skills` barrel, so adding this module to the barrel later can never
+// introduce an import cycle. External callers still go through the barrel.
+const constants_1 = require("../../lib/skills/constants");
+const semver_1 = require("../../lib/skills/semver");
+/** Stable reason codes for a CommandMate compatibility verdict. */
+exports.SkillCompatibilityReason = {
+    /** Host version satisfies the declared range. */
+    SATISFIED: 'SKILL_COMPAT_SATISFIED',
+    /** Host version is valid but outside the declared range. */
+    HOST_VERSION_OUT_OF_RANGE: 'SKILL_COMPAT_HOST_VERSION_OUT_OF_RANGE',
+    /** The running CommandMate version could not be determined. */
+    HOST_VERSION_UNKNOWN: 'SKILL_COMPAT_HOST_VERSION_UNKNOWN',
+    /** The publisher's range is not expressible in the supported grammar. */
+    RANGE_UNSUPPORTED: 'SKILL_COMPAT_RANGE_UNSUPPORTED',
+};
+/** i18n keys paired with each reason code, so UI and CLI share one vocabulary. */
+exports.SKILL_COMPATIBILITY_MESSAGE_KEYS = {
+    [exports.SkillCompatibilityReason.SATISFIED]: 'skills.compatibility.reason.satisfied',
+    [exports.SkillCompatibilityReason.HOST_VERSION_OUT_OF_RANGE]: 'skills.compatibility.reason.hostVersionOutOfRange',
+    [exports.SkillCompatibilityReason.HOST_VERSION_UNKNOWN]: 'skills.compatibility.reason.hostVersionUnknown',
+    [exports.SkillCompatibilityReason.RANGE_UNSUPPORTED]: 'skills.compatibility.reason.rangeUnsupported',
+};
+// =============================================================================
+// Host version
+// =============================================================================
+/**
+ * Sentinel `getServerVersion()` returns when it cannot read a real version.
+ *
+ * It is syntactically valid SemVer, so without this guard an unreadable
+ * package.json would silently produce a confident "incompatible" verdict
+ * instead of the honest "unknown".
+ */
+exports.UNKNOWN_HOST_VERSION_SENTINEL = '0.0.0';
+/**
+ * Normalize a raw CommandMate version into a strict SemVer 2.0 string.
+ *
+ * @returns The version, or null when it is absent, the unknown sentinel, or not
+ *   strict SemVer 2.0 (the Skill contract rejects the `v` prefix).
+ */
+function normalizeHostVersion(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (trimmed === exports.UNKNOWN_HOST_VERSION_SENTINEL)
+        return null;
+    return (0, semver_1.parseSemVer)(trimmed) === null ? null : trimmed;
+}
+// =============================================================================
+// Compatibility
+// =============================================================================
+function buildMessage(reasonCode, requiredRange, currentVersion) {
+    switch (reasonCode) {
+        case exports.SkillCompatibilityReason.SATISFIED:
+            return `CommandMate ${currentVersion} satisfies the required range "${requiredRange}".`;
+        case exports.SkillCompatibilityReason.HOST_VERSION_OUT_OF_RANGE:
+            return `This Skill requires CommandMate "${requiredRange}", but CommandMate ${currentVersion} is running.`;
+        case exports.SkillCompatibilityReason.HOST_VERSION_UNKNOWN:
+            return `The running CommandMate version could not be determined, so compatibility with "${requiredRange}" is unverified.`;
+        case exports.SkillCompatibilityReason.RANGE_UNSUPPORTED:
+            return `This Skill declares the unsupported CommandMate version range "${requiredRange}", so compatibility is unverified.`;
+    }
+}
+function verdict(status, reasonCode, requiredRange, currentVersion) {
+    return {
+        status,
+        reasonCode,
+        messageKey: exports.SKILL_COMPATIBILITY_MESSAGE_KEYS[reasonCode],
+        message: buildMessage(reasonCode, requiredRange, currentVersion),
+        requiredRange,
+        currentVersion,
+    };
+}
+/**
+ * Judge whether the running CommandMate satisfies a declared version range.
+ *
+ * Fails closed in both directions: an unparsable range and an undeterminable
+ * host version both yield `unknown`, never `compatible`.
+ *
+ * @param requiredRange - Range declared in `compatibility.commandmate`
+ * @param currentVersion - Host version, already passed through {@link normalizeHostVersion}
+ */
+function evaluateCommandMateCompatibility(requiredRange, currentVersion) {
+    const range = typeof requiredRange === 'string' ? requiredRange : '';
+    if (!(0, semver_1.isValidSkillVersionRange)(range)) {
+        return verdict('unknown', exports.SkillCompatibilityReason.RANGE_UNSUPPORTED, range, currentVersion ?? null);
+    }
+    if (currentVersion === null) {
+        return verdict('unknown', exports.SkillCompatibilityReason.HOST_VERSION_UNKNOWN, range, null);
+    }
+    if (!(0, semver_1.satisfiesSkillVersionRange)(currentVersion, range)) {
+        return verdict('incompatible', exports.SkillCompatibilityReason.HOST_VERSION_OUT_OF_RANGE, range, currentVersion);
+    }
+    return verdict('compatible', exports.SkillCompatibilityReason.SATISFIED, range, currentVersion);
+}
+/** Judge one Catalog version against the running CommandMate. */
+function evaluateVersionCompatibility(version, currentVersion) {
+    return evaluateCommandMateCompatibility(version.compatibility.commandmate, currentVersion);
+}
+/** Attach the shared i18n label key to each Agent support claim. */
+function describeAgentCompatibility(agents) {
+    return agents.map((entry) => ({
+        agent: entry.agent,
+        support: entry.support,
+        labelKey: constants_1.AGENT_SUPPORT_LABEL_KEYS[entry.support],
+        evidence: entry.evidence,
+    }));
+}
+// =============================================================================
+// Version resolution
+// =============================================================================
+/** Why a particular version was recommended, or why none was. */
+exports.SkillRecommendationReason = {
+    /** Highest listed version that is compatible with the running CommandMate. */
+    HIGHEST_COMPATIBLE: 'SKILL_RECOMMEND_HIGHEST_COMPATIBLE',
+    /** Host version is unknown, so the publisher's `latest` is offered unverified. */
+    LATEST_UNVERIFIED: 'SKILL_RECOMMEND_LATEST_UNVERIFIED',
+    /** Every listed version is incompatible with the running CommandMate. */
+    NONE_COMPATIBLE: 'SKILL_RECOMMEND_NONE_COMPATIBLE',
+    /** No version survived filtering (e.g. prerelease-only entry without opt-in). */
+    NO_VERSIONS: 'SKILL_RECOMMEND_NO_VERSIONS',
+};
+function isPrerelease(version) {
+    const parsed = (0, semver_1.parseSemVer)(version);
+    return parsed !== null && parsed.prerelease.length > 0;
+}
+/**
+ * Sort, filter and pick a default version for one Catalog entry.
+ *
+ * Prereleases are excluded unless explicitly requested. Versions the Catalog
+ * validator already accepted are strict SemVer 2.0, so ordering is total.
+ */
+function resolveSkillVersions(entry, options) {
+    const { currentVersion, includePrerelease = false } = options;
+    const versions = entry.versions
+        .map((version) => ({
+        version,
+        prerelease: isPrerelease(version.version),
+        compatibility: evaluateVersionCompatibility(version, currentVersion),
+    }))
+        .filter((candidate) => includePrerelease || !candidate.prerelease)
+        .sort((a, b) => ((0, semver_1.compareSemVer)(b.version.version, a.version.version) ?? 0));
+    if (versions.length === 0) {
+        return { versions, recommended: null, reasonCode: exports.SkillRecommendationReason.NO_VERSIONS };
+    }
+    const compatible = versions.find((candidate) => candidate.compatibility.status === 'compatible');
+    if (compatible) {
+        return {
+            versions,
+            recommended: compatible,
+            reasonCode: exports.SkillRecommendationReason.HIGHEST_COMPATIBLE,
+        };
+    }
+    // Host version unknown: nothing can be *proven* compatible, so the publisher's
+    // `latest` is offered with an explicit unverified reason rather than hidden.
+    if (currentVersion === null) {
+        const latest = versions.find((candidate) => candidate.version.version === entry.latest) ?? versions[0];
+        return {
+            versions,
+            recommended: latest,
+            reasonCode: exports.SkillRecommendationReason.LATEST_UNVERIFIED,
+        };
+    }
+    return { versions, recommended: null, reasonCode: exports.SkillRecommendationReason.NONE_COMPATIBLE };
+}
+/** Find one entry by exact Skill ID. Returns null when absent. */
+function findSkillCatalogEntry(catalog, id) {
+    return catalog.entries.find((entry) => entry.id === id) ?? null;
+}

package/dist/server/src/lib/skills/constants.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Agent Skills distribution contract constants (Issue #1228)
+ *
+ * Single source of truth for every limit, pattern and layout rule referenced by
+ * docs/design/agent-skills-distribution.md. Downstream issues (#1229 catalog,
+ * #1231 install, #1234 audit) must import from here rather than re-deriving
+ * values, so a contract change is a one-line change.
+ *
+ * @module lib/skills/constants
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_DECLARATION_NOTICE_KEY = exports.HTTPS_URL_PREFIX = exports.NETWORK_HOST_PATTERN = exports.COMMAND_NAME_PATTERN = exports.SPDX_LICENSE_PATTERN = exports.RFC3339_UTC_PATTERN = exports.GIT_REF_PATTERN = exports.REPOSITORY_SLUG_PATTERN = exports.GIT_COMMIT_SHA_PATTERN = exports.SHA256_HEX_PATTERN = exports.SKILL_FILE_KINDS = exports.SKILL_DECLARED_PERMISSIONS = exports.SKILL_RISK_ORDER = exports.SKILL_RISK_LEVELS = exports.SKILL_AGENT_SUPPORT_VALUES = exports.SKILL_YAML_SAFE_PROFILE = exports.SKILL_CATALOG_VERSIONS_MAX_COUNT = exports.SKILL_CATALOG_ENTRIES_MAX_COUNT = exports.SKILL_NETWORK_HOSTS_MAX_COUNT = exports.SKILL_COMMANDS_MAX_COUNT = exports.SKILL_RATIONALE_MAX_LENGTH = exports.SKILL_EVIDENCE_MAX_LENGTH = exports.SKILL_CHANGELOG_MAX_LENGTH = exports.SKILL_KEYWORD_MAX_LENGTH = exports.SKILL_KEYWORDS_MAX_COUNT = exports.SKILL_BULLET_MAX_COUNT = exports.SKILL_BULLET_MAX_LENGTH = exports.SKILL_DESCRIPTION_MAX_LENGTH = exports.SKILL_SUMMARY_MAX_LENGTH = exports.SKILL_NAME_MAX_LENGTH = exports.SKILL_PATH_MAX_LENGTH = exports.SKILL_PATH_MAX_DEPTH = exports.SKILL_PATH_SEGMENT_MAX_LENGTH = exports.SKILL_FILES_MAX_COUNT = exports.SKILL_FILE_MAX_SIZE = exports.SKILL_ARTIFACT_MAX_SIZE = exports.SKILL_ARTIFACT_CONTENT_TYPE = exports.SKILL_ARTIFACT_FORMAT = exports.REQUIRED_PACKAGE_ENTRIES = exports.SKILL_STAGING_DIRNAME = exports.SKILL_MD_FILENAME = exports.SKILL_MANIFEST_FILENAME = exports.SKILL_PRIMARY_INSTALL_ROOT_PREFIX = exports.SKILL_INSTALL_ROOT_PREFIXES = exports.SKILL_CLAUDE_INSTALL_ROOT_PREFIX = exports.SKILL_INSTALL_ROOT_PREFIX = exports.RESERVED_SKILL_IDS = exports.SKILL_ID_MAX_LENGTH = exports.SKILL_ID_PATTERN = exports.SKILL_SCHEMA_VERSION = void 0;
+exports.AGENT_SUPPORT_LABEL_KEYS = void 0;
+exports.isKnownSkillInstallRootPrefix = isKnownSkillInstallRootPrefix;
+exports.buildSkillAssetName = buildSkillAssetName;
+// =============================================================================
+// Schema version
+// =============================================================================
+/** The only schema version this build understands. Anything else fails closed. */
+exports.SKILL_SCHEMA_VERSION = 1;
+// =============================================================================
+// Skill ID
+// =============================================================================
+/**
+ * Skill ID grammar: ASCII lowercase slug.
+ *
+ * Anchored and ASCII-only by construction, so uppercase, Unicode homoglyphs,
+ * leading/trailing hyphens and dot-prefixed names are all rejected here rather
+ * than by a later, easier-to-forget check.
+ */
+exports.SKILL_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Maximum Skill ID length in characters. */
+exports.SKILL_ID_MAX_LENGTH = 64;
+/**
+ * IDs that may never be used as a Skill directory name.
+ *
+ * Covers Windows reserved device names (which resolve to devices regardless of
+ * the directory they appear in) and names CommandMate claims for itself.
+ */
+exports.RESERVED_SKILL_IDS = [
+    'commandmate',
+    'system',
+    'con',
+    'prn',
+    'aux',
+    'nul',
+    'com1',
+    'com2',
+    'com3',
+    'com4',
+    'com5',
+    'com6',
+    'com7',
+    'com8',
+    'com9',
+    'lpt1',
+    'lpt2',
+    'lpt3',
+    'lpt4',
+    'lpt5',
+    'lpt6',
+    'lpt7',
+    'lpt8',
+    'lpt9',
+];
+// =============================================================================
+// Layout
+// =============================================================================
+/** Skill payload root inside a worktree, resolved from a registered worktree ID. */
+exports.SKILL_INSTALL_ROOT_PREFIX = '.agents/skills';
+/**
+ * Claude Code Skill discovery root inside a worktree (Issue #1460).
+ *
+ * The counterpart of {@link SKILL_INSTALL_ROOT_PREFIX}: Claude reads
+ * `.claude/skills/<id>/SKILL.md` (#343) where Codex reads `.agents/skills`
+ * (#1165). Placing a package into both makes the same install discoverable by
+ * both Agents.
+ */
+exports.SKILL_CLAUDE_INSTALL_ROOT_PREFIX = '.claude/skills';
+/**
+ * Ordered set of roots an official Skill is placed into by default (#1460).
+ *
+ * Order is significant. `.agents/skills` is first and is the *primary* root: it
+ * remains the single atomic-rename commit point and the backward-compatible
+ * anchor every legacy single-root receipt names. `.claude/skills` is a
+ * *secondary* root, converged forward from the primary by reconciliation if a
+ * crash lands only one of the two renames. Adding an Agent (Gemini, OpenCode …)
+ * is a one-line addition here.
+ */
+exports.SKILL_INSTALL_ROOT_PREFIXES = [
+    exports.SKILL_INSTALL_ROOT_PREFIX,
+    exports.SKILL_CLAUDE_INSTALL_ROOT_PREFIX,
+];
+/** The primary root that stays the commit point and the receipt's `install_root`. */
+exports.SKILL_PRIMARY_INSTALL_ROOT_PREFIX = exports.SKILL_INSTALL_ROOT_PREFIX;
+/** Whether a repository-relative root prefix is one CommandMate installs into. */
+function isKnownSkillInstallRootPrefix(prefix) {
+    return exports.SKILL_INSTALL_ROOT_PREFIXES.includes(prefix);
+}
+/** Manifest filename, placed at the Skill root next to SKILL.md. */
+exports.SKILL_MANIFEST_FILENAME = 'commandmate.skill.yaml';
+/** Standard Agent Skills authoring file, required in every package. */
+exports.SKILL_MD_FILENAME = 'SKILL.md';
+/**
+ * Reserved private namespace for install-commit staging.
+ *
+ * Lives under the target `.agents/skills` so the atomic rename stays on one
+ * filesystem. Excluded from Skill discovery because the leading dot is outside
+ * {@link SKILL_ID_PATTERN}.
+ */
+exports.SKILL_STAGING_DIRNAME = '.commandmate-staging';
+/** Entries every valid package must contain, relative to the archive root directory. */
+exports.REQUIRED_PACKAGE_ENTRIES = [
+    exports.SKILL_MD_FILENAME,
+    exports.SKILL_MANIFEST_FILENAME,
+];
+// =============================================================================
+// Artifact
+// =============================================================================
+/** The only artifact format accepted in schema_version 1. */
+exports.SKILL_ARTIFACT_FORMAT = 'tar.gz';
+/** Required Content-Type of a release asset. */
+exports.SKILL_ARTIFACT_CONTENT_TYPE = 'application/gzip';
+/** Maximum artifact size in bytes (16 MiB). */
+exports.SKILL_ARTIFACT_MAX_SIZE = 16 * 1024 * 1024;
+/** Maximum size of a single payload file in bytes (4 MiB). */
+exports.SKILL_FILE_MAX_SIZE = 4 * 1024 * 1024;
+/** Maximum number of payload files declared in a manifest. */
+exports.SKILL_FILES_MAX_COUNT = 500;
+/** Build the required release asset name for a version. */
+function buildSkillAssetName(skillId, version) {
+    return `${skillId}-${version}.tar.gz`;
+}
+// =============================================================================
+// Payload paths
+// =============================================================================
+/** Maximum length of a single path segment. */
+exports.SKILL_PATH_SEGMENT_MAX_LENGTH = 100;
+/** Maximum number of path segments in a payload path. */
+exports.SKILL_PATH_MAX_DEPTH = 8;
+/** Maximum total length of a payload path. */
+exports.SKILL_PATH_MAX_LENGTH = 255;
+// =============================================================================
+// Text limits
+// =============================================================================
+exports.SKILL_NAME_MAX_LENGTH = 100;
+exports.SKILL_SUMMARY_MAX_LENGTH = 200;
+exports.SKILL_DESCRIPTION_MAX_LENGTH = 2000;
+exports.SKILL_BULLET_MAX_LENGTH = 200;
+exports.SKILL_BULLET_MAX_COUNT = 10;
+exports.SKILL_KEYWORDS_MAX_COUNT = 20;
+exports.SKILL_KEYWORD_MAX_LENGTH = 40;
+exports.SKILL_CHANGELOG_MAX_LENGTH = 4000;
+exports.SKILL_EVIDENCE_MAX_LENGTH = 300;
+exports.SKILL_RATIONALE_MAX_LENGTH = 500;
+exports.SKILL_COMMANDS_MAX_COUNT = 20;
+exports.SKILL_NETWORK_HOSTS_MAX_COUNT = 20;
+exports.SKILL_CATALOG_ENTRIES_MAX_COUNT = 500;
+exports.SKILL_CATALOG_VERSIONS_MAX_COUNT = 100;
+// =============================================================================
+// Safe YAML parse profile
+// =============================================================================
+/**
+ * Limits any manifest YAML parser must enforce.
+ *
+ * The contract (not the parser) lives here: #1229/#1231 pick an implementation
+ * but must reject aliases, anchors, merge keys, custom tags, duplicate keys and
+ * prototype-polluting keys, and must apply these bounds.
+ */
+exports.SKILL_YAML_SAFE_PROFILE = {
+    maxBytes: 64 * 1024,
+    maxDepth: 16,
+    maxNodes: 5000,
+    maxScalarLength: 8192,
+    allowAliases: false,
+    allowCustomTags: false,
+    allowDuplicateKeys: false,
+    /** Keys rejected outright to prevent prototype pollution through parsed objects. */
+    forbiddenKeys: ['__proto__', 'constructor', 'prototype'],
+};
+// =============================================================================
+// Enumerations
+// =============================================================================
+exports.SKILL_AGENT_SUPPORT_VALUES = [
+    'native',
+    'commandmate_runtime',
+    'unsupported',
+    'unknown',
+];
+exports.SKILL_RISK_LEVELS = ['low', 'moderate', 'high'];
+/** Ordering used to resolve the effective risk. Higher index wins. */
+exports.SKILL_RISK_ORDER = {
+    low: 0,
+    moderate: 1,
+    high: 2,
+};
+exports.SKILL_DECLARED_PERMISSIONS = [
+    'filesystem_read',
+    'filesystem_write',
+    'network_access',
+    'process_execution',
+    'environment_read',
+    'credential_access',
+];
+exports.SKILL_FILE_KINDS = [
+    'skill_md',
+    'instruction',
+    'script',
+    'asset',
+];
+// =============================================================================
+// Formats
+// =============================================================================
+/** Lowercase hex SHA-256. Uppercase is rejected so digests compare byte-wise. */
+exports.SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+/** Resolved git commit SHA-1, full 40 hex digits. Abbreviations are rejected. */
+exports.GIT_COMMIT_SHA_PATTERN = /^[0-9a-f]{40}$/;
+/** `owner/name` source repository coordinate. */
+exports.REPOSITORY_SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Human-facing git ref (tag or branch). `..` is rejected separately. */
+exports.GIT_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,99}$/;
+/** RFC 3339 UTC instant, `Z` suffix only, so published_at compares lexicographically. */
+exports.RFC3339_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+/** SPDX license identifier shape (expressions are out of scope for schema_version 1). */
+exports.SPDX_LICENSE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.+-]{0,63}$/;
+/** External command name a Skill may require. */
+exports.COMMAND_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+/** Network host: DNS hostname, optionally a leading `*.` wildcard label. */
+exports.NETWORK_HOST_PATTERN = /^(?:\*\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/** Artifact and homepage URLs must be HTTPS. */
+exports.HTTPS_URL_PREFIX = 'https://';
+// =============================================================================
+// UI vocabulary
+// =============================================================================
+/**
+ * Wording that must accompany any permission display.
+ *
+ * Prevents the declaration from being read as enforcement (see the ADR's
+ * "declaration is not enforcement" decision).
+ */
+exports.PERMISSION_DECLARATION_NOTICE_KEY = 'skills.permissions.declarationOnlyNotice';
+/**
+ * Labels for {@link SkillAgentSupport}, so UI and CLI use one vocabulary (UX-05).
+ * Values are i18n message keys, not user-visible strings.
+ */
+exports.AGENT_SUPPORT_LABEL_KEYS = {
+    native: 'skills.compatibility.native',
+    commandmate_runtime: 'skills.compatibility.commandmateRuntime',
+    unsupported: 'skills.compatibility.unsupported',
+    unknown: 'skills.compatibility.unknown',
+};

package/dist/server/src/lib/skills/errors.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Typed errors for the Agent Skills distribution contract (Issue #1228)
+ *
+ * Every rejection carries a stable machine code plus a JSON-Pointer-like path,
+ * so callers can branch on the reason and localize the message without parsing
+ * prose. Messages are built from the code and the document path only: they
+ * never embed a token, signed URL, secret or machine-absolute path.
+ *
+ * @module lib/skills/errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillContractErrorCode = void 0;
+exports.skillError = skillError;
+exports.skillOk = skillOk;
+exports.skillFail = skillFail;
+exports.joinPath = joinPath;
+/** Stable, client-safe reason codes for contract validation failures. */
+exports.SkillContractErrorCode = {
+    /** Document is not a plain object. */
+    NOT_AN_OBJECT: 'SKILL_NOT_AN_OBJECT',
+    /** `schema_version` is missing, malformed, or newer than this build supports. */
+    SCHEMA_VERSION_UNSUPPORTED: 'SKILL_SCHEMA_VERSION_UNSUPPORTED',
+    /** A required field is absent. */
+    MISSING_FIELD: 'SKILL_MISSING_FIELD',
+    /** A field exists but has the wrong JSON type. */
+    INVALID_TYPE: 'SKILL_INVALID_TYPE',
+    /** A field carries a value outside its enumeration. */
+    INVALID_ENUM: 'SKILL_INVALID_ENUM',
+    /** A field is syntactically wrong (pattern mismatch). */
+    INVALID_FORMAT: 'SKILL_INVALID_FORMAT',
+    /** A numeric or length bound was exceeded. */
+    LIMIT_EXCEEDED: 'SKILL_LIMIT_EXCEEDED',
+    /** An unspecified field is present; schema_version 1 is closed. */
+    UNKNOWN_FIELD: 'SKILL_UNKNOWN_FIELD',
+    /** Skill ID does not match the slug grammar. */
+    ID_INVALID: 'SKILL_ID_INVALID',
+    /** Skill ID is reserved by CommandMate or by the host filesystem. */
+    ID_RESERVED: 'SKILL_ID_RESERVED',
+    /** Skill ID collides with an existing name under case/Unicode folding. */
+    ID_COLLISION: 'SKILL_ID_COLLISION',
+    /** Directory name, SKILL.md name and manifest id disagree. */
+    ID_MISMATCH: 'SKILL_ID_MISMATCH',
+    /** Version is not valid SemVer 2.0. */
+    VERSION_INVALID: 'SKILL_VERSION_INVALID',
+    /** Version range is not expressible in the supported range grammar. */
+    VERSION_RANGE_INVALID: 'SKILL_VERSION_RANGE_INVALID',
+    /** Digest is not lowercase hex SHA-256. */
+    DIGEST_INVALID: 'SKILL_DIGEST_INVALID',
+    /** Payload path escapes the Skill root or is otherwise unsafe. */
+    FILE_PATH_UNSAFE: 'SKILL_FILE_PATH_UNSAFE',
+    /** Two entries declare the same payload path (possibly after folding). */
+    FILE_PATH_DUPLICATE: 'SKILL_FILE_PATH_DUPLICATE',
+    /** Declared file set does not match the package's payload file set. */
+    FILE_SET_MISMATCH: 'SKILL_FILE_SET_MISMATCH',
+    /** Artifact name, format or Content-Type violates the packaging rule. */
+    ARTIFACT_INVALID: 'SKILL_ARTIFACT_INVALID',
+    /** Source ref is present but the resolved commit SHA is missing or malformed. */
+    SOURCE_COMMIT_INVALID: 'SKILL_SOURCE_COMMIT_INVALID',
+    /** Catalog `latest` does not resolve to a listed version. */
+    CATALOG_LATEST_UNRESOLVED: 'SKILL_CATALOG_LATEST_UNRESOLVED',
+    /** The same identity is declared twice within one document. */
+    DUPLICATE_ENTRY: 'SKILL_DUPLICATE_ENTRY',
+    /** Two fields that must agree do not. */
+    INCONSISTENT_VALUE: 'SKILL_INCONSISTENT_VALUE',
+};
+/** Build a validation failure. */
+function skillError(code, path, message, detail) {
+    return detail ? { code, path, message, detail } : { code, path, message };
+}
+/** Wrap a validated document as a success result. */
+function skillOk(value) {
+    return { ok: true, value, errors: [] };
+}
+/** Wrap one or more failures as a failure result. */
+function skillFail(errors) {
+    return { ok: false, value: null, errors };
+}
+/** Append a segment to a JSON-Pointer-like path. */
+function joinPath(base, segment) {
+    return `${base}/${segment}`;
+}

package/dist/server/src/lib/skills/index.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Public API of the Agent Skills distribution contract (Issue #1228)
+ *
+ * This barrel is the *contract* surface only: schema, types, constants, error
+ * codes, and SemVer. It is isomorphic — it pulls in no Node builtin — so client
+ * components can import from it safely.
+ *
+ * Deliberately NOT re-exported here (import the concrete module instead):
+ *
+ * | module | why it stays out of the barrel |
+ * | --- | --- |
+ * | `artifact-downloader`, `snapshot-store`, `integrity` (#1229) | `fs` / `crypto`, transitively `version-checker` (`fs`, `path`) |
+ * | `package-reader`, `package-validator` (#1230) | `zlib` / `fs` |
+ * | `operation-lock`, `operation-journal`, `operation-store`, `operation-audit`, `operation-reconciler` (#1234) | `fs` / `os`, service-owned state root |
+ * | `catalog-client`, `compatibility` (#1231) | server-side cache ownership; `compatibility` is pure but is paired with the client |
+ * | `safe-yaml` (#1230) | pure, but only meaningful together with `package-reader` |
+ *
+ * Re-exporting those would drag `fs` / `zlib` into any consumer of
+ * `@/lib/skills`, including the `use client` components under
+ * `src/components/skills/`. Keep server-only modules concrete:
+ * `import { … } from '../../lib/skills/snapshot-store'`.
+ *
+ * @module lib/skills
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSkillCatalog = exports.validateManifestFileSet = exports.resolveEffectiveSkillRisk = exports.foldSkillIdForCollision = exports.detectSkillIdCollision = exports.computeSkillRisk = exports.canonicalizeSkillReceipt = exports.SKILL_OPTIONAL_FIELDS = exports.SKILL_DOCUMENT_FIELDS = exports.satisfiesSkillVersionRange = exports.parseSkillVersionRange = exports.parseSemVer = exports.isValidSkillVersionRange = exports.isValidSemVer = exports.compareSemVer = exports.compareParsedSemVer = exports.SEMVER_2_PATTERN = exports.skillOk = exports.skillFail = exports.skillError = exports.joinSkillErrorPath = exports.SkillContractErrorCode = exports.buildSkillAssetName = exports.REQUIRED_PACKAGE_ENTRIES = exports.SKILL_YAML_SAFE_PROFILE = exports.SKILL_STAGING_DIRNAME = exports.SKILL_SCHEMA_VERSION = exports.SKILL_RISK_ORDER = exports.SKILL_RISK_LEVELS = exports.SKILL_MD_FILENAME = exports.SKILL_MANIFEST_FILENAME = exports.SKILL_INSTALL_ROOT_PREFIX = exports.SKILL_ID_PATTERN = exports.SKILL_ID_MAX_LENGTH = exports.SKILL_FILES_MAX_COUNT = exports.SKILL_FILE_MAX_SIZE = exports.SKILL_FILE_KINDS = exports.SKILL_DECLARED_PERMISSIONS = exports.SKILL_ARTIFACT_MAX_SIZE = exports.SKILL_ARTIFACT_FORMAT = exports.SKILL_ARTIFACT_CONTENT_TYPE = exports.SKILL_AGENT_SUPPORT_VALUES = exports.SHA256_HEX_PATTERN = exports.RFC3339_UTC_PATTERN = exports.RESERVED_SKILL_IDS = exports.REPOSITORY_SLUG_PATTERN = exports.PERMISSION_DECLARATION_NOTICE_KEY = exports.GIT_REF_PATTERN = exports.GIT_COMMIT_SHA_PATTERN = exports.AGENT_SUPPORT_LABEL_KEYS = void 0;
+exports.SKILL_RECEIPT_JSON_SCHEMA = exports.SKILL_MANIFEST_JSON_SCHEMA = exports.SKILL_CATALOG_JSON_SCHEMA = exports.validateSkillPayloadPath = exports.validateSkillManifest = exports.validateSkillInstallReceipt = exports.validateSkillIdentityConsistency = exports.validateSkillId = void 0;
+var constants_1 = require("../../lib/skills/constants");
+Object.defineProperty(exports, "AGENT_SUPPORT_LABEL_KEYS", { enumerable: true, get: function () { return constants_1.AGENT_SUPPORT_LABEL_KEYS; } });
+Object.defineProperty(exports, "GIT_COMMIT_SHA_PATTERN", { enumerable: true, get: function () { return constants_1.GIT_COMMIT_SHA_PATTERN; } });
+Object.defineProperty(exports, "GIT_REF_PATTERN", { enumerable: true, get: function () { return constants_1.GIT_REF_PATTERN; } });
+Object.defineProperty(exports, "PERMISSION_DECLARATION_NOTICE_KEY", { enumerable: true, get: function () { return constants_1.PERMISSION_DECLARATION_NOTICE_KEY; } });
+Object.defineProperty(exports, "REPOSITORY_SLUG_PATTERN", { enumerable: true, get: function () { return constants_1.REPOSITORY_SLUG_PATTERN; } });
+Object.defineProperty(exports, "RESERVED_SKILL_IDS", { enumerable: true, get: function () { return constants_1.RESERVED_SKILL_IDS; } });
+Object.defineProperty(exports, "RFC3339_UTC_PATTERN", { enumerable: true, get: function () { return constants_1.RFC3339_UTC_PATTERN; } });
+Object.defineProperty(exports, "SHA256_HEX_PATTERN", { enumerable: true, get: function () { return constants_1.SHA256_HEX_PATTERN; } });
+Object.defineProperty(exports, "SKILL_AGENT_SUPPORT_VALUES", { enumerable: true, get: function () { return constants_1.SKILL_AGENT_SUPPORT_VALUES; } });
+Object.defineProperty(exports, "SKILL_ARTIFACT_CONTENT_TYPE", { enumerable: true, get: function () { return constants_1.SKILL_ARTIFACT_CONTENT_TYPE; } });
+Object.defineProperty(exports, "SKILL_ARTIFACT_FORMAT", { enumerable: true, get: function () { return constants_1.SKILL_ARTIFACT_FORMAT; } });
+Object.defineProperty(exports, "SKILL_ARTIFACT_MAX_SIZE", { enumerable: true, get: function () { return constants_1.SKILL_ARTIFACT_MAX_SIZE; } });
+Object.defineProperty(exports, "SKILL_DECLARED_PERMISSIONS", { enumerable: true, get: function () { return constants_1.SKILL_DECLARED_PERMISSIONS; } });
+Object.defineProperty(exports, "SKILL_FILE_KINDS", { enumerable: true, get: function () { return constants_1.SKILL_FILE_KINDS; } });
+Object.defineProperty(exports, "SKILL_FILE_MAX_SIZE", { enumerable: true, get: function () { return constants_1.SKILL_FILE_MAX_SIZE; } });
+Object.defineProperty(exports, "SKILL_FILES_MAX_COUNT", { enumerable: true, get: function () { return constants_1.SKILL_FILES_MAX_COUNT; } });
+Object.defineProperty(exports, "SKILL_ID_MAX_LENGTH", { enumerable: true, get: function () { return constants_1.SKILL_ID_MAX_LENGTH; } });
+Object.defineProperty(exports, "SKILL_ID_PATTERN", { enumerable: true, get: function () { return constants_1.SKILL_ID_PATTERN; } });
+Object.defineProperty(exports, "SKILL_INSTALL_ROOT_PREFIX", { enumerable: true, get: function () { return constants_1.SKILL_INSTALL_ROOT_PREFIX; } });
+Object.defineProperty(exports, "SKILL_MANIFEST_FILENAME", { enumerable: true, get: function () { return constants_1.SKILL_MANIFEST_FILENAME; } });
+Object.defineProperty(exports, "SKILL_MD_FILENAME", { enumerable: true, get: function () { return constants_1.SKILL_MD_FILENAME; } });
+Object.defineProperty(exports, "SKILL_RISK_LEVELS", { enumerable: true, get: function () { return constants_1.SKILL_RISK_LEVELS; } });
+Object.defineProperty(exports, "SKILL_RISK_ORDER", { enumerable: true, get: function () { return constants_1.SKILL_RISK_ORDER; } });
+Object.defineProperty(exports, "SKILL_SCHEMA_VERSION", { enumerable: true, get: function () { return constants_1.SKILL_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "SKILL_STAGING_DIRNAME", { enumerable: true, get: function () { return constants_1.SKILL_STAGING_DIRNAME; } });
+Object.defineProperty(exports, "SKILL_YAML_SAFE_PROFILE", { enumerable: true, get: function () { return constants_1.SKILL_YAML_SAFE_PROFILE; } });
+Object.defineProperty(exports, "REQUIRED_PACKAGE_ENTRIES", { enumerable: true, get: function () { return constants_1.REQUIRED_PACKAGE_ENTRIES; } });
+Object.defineProperty(exports, "buildSkillAssetName", { enumerable: true, get: function () { return constants_1.buildSkillAssetName; } });
+var errors_1 = require("../../lib/skills/errors");
+Object.defineProperty(exports, "SkillContractErrorCode", { enumerable: true, get: function () { return errors_1.SkillContractErrorCode; } });
+Object.defineProperty(exports, "joinSkillErrorPath", { enumerable: true, get: function () { return errors_1.joinPath; } });
+Object.defineProperty(exports, "skillError", { enumerable: true, get: function () { return errors_1.skillError; } });
+Object.defineProperty(exports, "skillFail", { enumerable: true, get: function () { return errors_1.skillFail; } });
+Object.defineProperty(exports, "skillOk", { enumerable: true, get: function () { return errors_1.skillOk; } });
+var semver_1 = require("../../lib/skills/semver");
+Object.defineProperty(exports, "SEMVER_2_PATTERN", { enumerable: true, get: function () { return semver_1.SEMVER_2_PATTERN; } });
+Object.defineProperty(exports, "compareParsedSemVer", { enumerable: true, get: function () { return semver_1.compareParsedSemVer; } });
+Object.defineProperty(exports, "compareSemVer", { enumerable: true, get: function () { return semver_1.compareSemVer; } });
+Object.defineProperty(exports, "isValidSemVer", { enumerable: true, get: function () { return semver_1.isValidSemVer; } });
+Object.defineProperty(exports, "isValidSkillVersionRange", { enumerable: true, get: function () { return semver_1.isValidSkillVersionRange; } });
+Object.defineProperty(exports, "parseSemVer", { enumerable: true, get: function () { return semver_1.parseSemVer; } });
+Object.defineProperty(exports, "parseSkillVersionRange", { enumerable: true, get: function () { return semver_1.parseSkillVersionRange; } });
+Object.defineProperty(exports, "satisfiesSkillVersionRange", { enumerable: true, get: function () { return semver_1.satisfiesSkillVersionRange; } });
+var schema_1 = require("../../lib/skills/schema");
+Object.defineProperty(exports, "SKILL_DOCUMENT_FIELDS", { enumerable: true, get: function () { return schema_1.SKILL_DOCUMENT_FIELDS; } });
+Object.defineProperty(exports, "SKILL_OPTIONAL_FIELDS", { enumerable: true, get: function () { return schema_1.SKILL_OPTIONAL_FIELDS; } });
+Object.defineProperty(exports, "canonicalizeSkillReceipt", { enumerable: true, get: function () { return schema_1.canonicalizeSkillReceipt; } });
+Object.defineProperty(exports, "computeSkillRisk", { enumerable: true, get: function () { return schema_1.computeSkillRisk; } });
+Object.defineProperty(exports, "detectSkillIdCollision", { enumerable: true, get: function () { return schema_1.detectSkillIdCollision; } });
+Object.defineProperty(exports, "foldSkillIdForCollision", { enumerable: true, get: function () { return schema_1.foldSkillIdForCollision; } });
+Object.defineProperty(exports, "resolveEffectiveSkillRisk", { enumerable: true, get: function () { return schema_1.resolveEffectiveSkillRisk; } });
+Object.defineProperty(exports, "validateManifestFileSet", { enumerable: true, get: function () { return schema_1.validateManifestFileSet; } });
+Object.defineProperty(exports, "validateSkillCatalog", { enumerable: true, get: function () { return schema_1.validateSkillCatalog; } });
+Object.defineProperty(exports, "validateSkillId", { enumerable: true, get: function () { return schema_1.validateSkillId; } });
+Object.defineProperty(exports, "validateSkillIdentityConsistency", { enumerable: true, get: function () { return schema_1.validateSkillIdentityConsistency; } });
+Object.defineProperty(exports, "validateSkillInstallReceipt", { enumerable: true, get: function () { return schema_1.validateSkillInstallReceipt; } });
+Object.defineProperty(exports, "validateSkillManifest", { enumerable: true, get: function () { return schema_1.validateSkillManifest; } });
+Object.defineProperty(exports, "validateSkillPayloadPath", { enumerable: true, get: function () { return schema_1.validateSkillPayloadPath; } });
+var json_schema_1 = require("../../lib/skills/json-schema");
+Object.defineProperty(exports, "SKILL_CATALOG_JSON_SCHEMA", { enumerable: true, get: function () { return json_schema_1.SKILL_CATALOG_JSON_SCHEMA; } });
+Object.defineProperty(exports, "SKILL_MANIFEST_JSON_SCHEMA", { enumerable: true, get: function () { return json_schema_1.SKILL_MANIFEST_JSON_SCHEMA; } });
+Object.defineProperty(exports, "SKILL_RECEIPT_JSON_SCHEMA", { enumerable: true, get: function () { return json_schema_1.SKILL_RECEIPT_JSON_SCHEMA; } });