@senior-skills/core 1.0.0

package/dist/domain/resolver.js

@@ -0,0 +1,238 @@
+import { AgentSkillsError, ErrorCode } from "./errors.js";
+import { LATEST } from "./skill-ref.js";
+import { compareVersions, intersects, maxSatisfying } from "./version.js";
+const DIRECT_REQUESTER = '<requested>';
+const MAX_ITERATIONS = 1000;
+/**
+ * Breadth-first constraint resolution without backtracking.
+ *
+ * Adding a constraint can only lower the chosen version, never raise it, so the fixed-point
+ * loop terminates; the iteration cap exists to turn a hypothetical resolver bug into a clear
+ * error rather than a hang.
+ */
+export class Resolver {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    async resolve(refs, options = {}) {
+        const constraints = new Map();
+        const registryHint = new Map();
+        const chosen = new Map();
+        const directNames = new Set();
+        const warnings = [];
+        const pinned = options.pinned ?? {};
+        for (const ref of refs) {
+            directNames.add(ref.name);
+            if (ref.registry !== undefined)
+                registryHint.set(ref.name, ref.registry);
+            addConstraint(constraints, ref.name, {
+                range: rangeFor(ref, pinned[ref.name]),
+                requester: DIRECT_REQUESTER,
+                optional: false,
+            });
+        }
+        for (let iteration = 0; iteration <= MAX_ITERATIONS; iteration += 1) {
+            const stale = this.findStale(constraints, chosen);
+            if (stale === undefined) {
+                return { order: topologicalOrder(chosen, directNames), warnings };
+            }
+            if (iteration === MAX_ITERATIONS)
+                break;
+            const skillConstraints = constraints.get(stale);
+            const resolved = await this.choose(stale, skillConstraints, registryHint.get(stale));
+            if (resolved === undefined) {
+                // Every constraint on this name came from optional dependencies: drop it.
+                constraints.delete(stale);
+                chosen.delete(stale);
+                continue;
+            }
+            chosen.set(stale, {
+                ...resolved,
+                direct: directNames.has(stale),
+                requiredBy: skillConstraints
+                    .filter((constraint) => constraint.requester !== DIRECT_REQUESTER)
+                    .map((constraint) => constraint.requester),
+            });
+            if (options.skipDependencies === true)
+                continue;
+            const requester = `${resolved.name}@${resolved.version}`;
+            for (const dependency of resolved.manifest.dependencies) {
+                addConstraint(constraints, dependency.name, {
+                    range: pinned[dependency.name] ?? dependency.version,
+                    requester,
+                    optional: false,
+                });
+            }
+            for (const dependency of resolved.manifest.optionalDependencies) {
+                addConstraint(constraints, dependency.name, {
+                    range: pinned[dependency.name] ?? dependency.version,
+                    requester,
+                    optional: true,
+                });
+            }
+            assertNoCycle(chosen, constraints);
+        }
+        throw new AgentSkillsError(ErrorCode.INTERNAL, 'Dependency resolution did not converge', {
+            details: [`Gave up after ${MAX_ITERATIONS} iterations.`],
+            hints: ['Please report this with the skills you were installing'],
+            data: { names: [...constraints.keys()] },
+        });
+    }
+    /** The first name (alphabetically, for determinism) whose choice does not satisfy its constraints. */
+    findStale(constraints, chosen) {
+        for (const name of [...constraints.keys()].sort()) {
+            const current = chosen.get(name);
+            if (current === undefined)
+                return name;
+            const ranges = constraints.get(name).map((constraint) => constraint.range);
+            if (!ranges.every((range) => satisfiesRange(current.version, range)))
+                return name;
+        }
+        return undefined;
+    }
+    async choose(name, constraints, registry) {
+        const allOptional = constraints.every((constraint) => constraint.optional);
+        let listed;
+        try {
+            listed = await this.source.listVersions(name, registry);
+        }
+        catch (cause) {
+            if (allOptional)
+                return undefined;
+            throw cause;
+        }
+        const ranges = constraints.map((constraint) => constraint.range);
+        if (!intersects(ranges)) {
+            if (allOptional)
+                return undefined;
+            throw conflictError(name, constraints, listed.versions);
+        }
+        // Deprecated versions stay resolvable only when a constraint names one exactly, so an
+        // existing lockfile keeps working while `latest` moves on.
+        const candidates = listed.versions
+            .filter((entry) => !entry.deprecated || ranges.some((range) => range === entry.version))
+            .map((entry) => entry.version);
+        // Filter by the whole constraint set at once, so the pick is order-independent.
+        const best = candidates
+            .filter((version) => ranges.every((range) => satisfiesRange(version, range)))
+            .sort((a, b) => compareVersions(b, a))[0];
+        if (best === undefined) {
+            if (allOptional)
+                return undefined;
+            throw conflictError(name, constraints, listed.versions);
+        }
+        const entry = listed.versions.find((candidate) => candidate.version === best);
+        const manifest = await this.source.loadManifest(name, best, listed.registry);
+        return { name, version: best, registry: listed.registry, entry, manifest };
+    }
+}
+function rangeFor(ref, pinnedVersion) {
+    if (ref.range !== undefined && ref.range !== LATEST)
+        return ref.range;
+    // An explicit `@latest` deliberately ignores the lockfile pin; a bare name honours it.
+    if (ref.range === LATEST)
+        return '*';
+    return pinnedVersion ?? '*';
+}
+function addConstraint(constraints, name, constraint) {
+    const existing = constraints.get(name);
+    if (existing === undefined) {
+        constraints.set(name, [constraint]);
+        return;
+    }
+    const duplicate = existing.some((item) => item.range === constraint.range && item.requester === constraint.requester);
+    if (!duplicate)
+        existing.push(constraint);
+}
+function satisfiesRange(version, range) {
+    return maxSatisfying([version], range) !== undefined;
+}
+function conflictError(name, constraints, available) {
+    const width = Math.max(...constraints.map((constraint) => constraint.requester.length));
+    const lines = constraints.map((constraint) => `  ${constraint.requester.padEnd(width)}  requires ${constraint.range}`);
+    const versions = available.map((entry) => entry.version).join(', ');
+    return new AgentSkillsError(ErrorCode.DEPENDENCY_CONFLICT, `Version conflict for "${name}"`, {
+        details: [
+            ...lines,
+            '',
+            `  No published version satisfies all of them.`,
+            `  Available: ${versions === '' ? '(none)' : versions}`,
+        ],
+        hints: [
+            `senior-skills info ${name}   to see every published version`,
+            'Relax a constraint, or install a newer version of the skill that requires the old range',
+        ],
+        data: {
+            name,
+            constraints: constraints.map((constraint) => ({
+                requester: constraint.requester,
+                range: constraint.range,
+            })),
+            available: available.map((entry) => entry.version),
+        },
+    });
+}
+/** Depth-first cycle detection over the graph implied by the manifests chosen so far. */
+function assertNoCycle(chosen, constraints) {
+    const edges = new Map();
+    for (const [name, skill] of chosen) {
+        edges.set(name, [...skill.manifest.dependencies, ...skill.manifest.optionalDependencies]
+            .map((dependency) => dependency.name)
+            .filter((dependency) => constraints.has(dependency)));
+    }
+    const visiting = new Set();
+    const done = new Set();
+    const path = [];
+    const visit = (name) => {
+        if (done.has(name))
+            return;
+        if (visiting.has(name)) {
+            const start = path.indexOf(name);
+            const cycle = [...path.slice(start), name].join(' → ');
+            throw new AgentSkillsError(ErrorCode.DEPENDENCY_CYCLE, 'Circular dependency detected', {
+                details: [`  ${cycle}`],
+                hints: ['Break the cycle by removing one of these dependencies'],
+                data: { cycle: [...path.slice(start), name] },
+            });
+        }
+        visiting.add(name);
+        path.push(name);
+        for (const next of edges.get(name) ?? [])
+            visit(next);
+        path.pop();
+        visiting.delete(name);
+        done.add(name);
+    };
+    for (const name of [...edges.keys()].sort())
+        visit(name);
+}
+/** Dependencies first. Cycles are already rejected, so a stable topological order exists. */
+function topologicalOrder(chosen, directNames) {
+    const ordered = [];
+    const emitted = new Set();
+    const emit = (name) => {
+        if (emitted.has(name))
+            return;
+        const skill = chosen.get(name);
+        if (skill === undefined)
+            return;
+        emitted.add(name);
+        for (const dependency of [
+            ...skill.manifest.dependencies,
+            ...skill.manifest.optionalDependencies,
+        ]
+            .map((dep) => dep.name)
+            .sort()) {
+            emit(dependency);
+        }
+        ordered.push(skill);
+    };
+    // Seed with direct requests first so the order is stable regardless of map insertion order.
+    for (const name of [...directNames].sort())
+        emit(name);
+    for (const name of [...chosen.keys()].sort())
+        emit(name);
+    return ordered;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/domain/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/domain/resolver.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill-document.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `SKILL.md` is the agent-facing entrypoint: YAML frontmatter plus a Markdown body.
+ * Both Claude Code and Codex require `name` and `description` and ignore the rest, which
+ * is why the neutral format keeps distribution metadata in `skill.yaml` instead.
+ */
+export interface SkillDocument {
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    readonly body: string;
+}
+export declare function parseSkillDocument(text: string, source?: string): SkillDocument;
+export declare function stringifySkillDocument(doc: SkillDocument): string;
+/** Reads the frontmatter `name`, which must agree with the manifest and directory name. */
+export declare function documentName(doc: SkillDocument): string | undefined;
+export declare function documentDescription(doc: SkillDocument): string | undefined;
+export declare function documentVersion(doc: SkillDocument): string | undefined;
+//# sourceMappingURL=skill-document.d.ts.map

package/dist/domain/skill-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-document.d.ts","sourceRoot":"","sources":["../../src/domain/skill-document.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,aAAa,CAgDnF;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAIjE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAG1E;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAGtE"}

package/dist/domain/skill-document.js

@@ -0,0 +1,60 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { AgentSkillsError, ErrorCode } from "./errors.js";
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function parseSkillDocument(text, source = 'SKILL.md') {
+    // A BOM before `---` would otherwise defeat the delimiter match.
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const match = FRONTMATTER_PATTERN.exec(normalized);
+    if (match === null) {
+        throw new AgentSkillsError(ErrorCode.INVALID_PACKAGE, `${source} has no YAML frontmatter`, {
+            details: ['The file must start with a --- delimited YAML block.'],
+            hints: [
+                'Example:',
+                '---',
+                'name: my-skill',
+                'description: What it does and when to use it.',
+                '---',
+            ],
+            data: { source },
+        });
+    }
+    let frontmatter;
+    try {
+        frontmatter = parseYaml(match[1] ?? '');
+    }
+    catch (cause) {
+        throw new AgentSkillsError(ErrorCode.INVALID_PACKAGE, `${source} has invalid frontmatter YAML`, {
+            details: [cause instanceof Error ? cause.message : String(cause)],
+            cause,
+            data: { source },
+        });
+    }
+    if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+        throw new AgentSkillsError(ErrorCode.INVALID_PACKAGE, `${source} frontmatter must be a mapping`, {
+            data: { source },
+        });
+    }
+    return {
+        frontmatter: frontmatter,
+        body: normalized.slice(match[0].length),
+    };
+}
+export function stringifySkillDocument(doc) {
+    const yaml = stringifyYaml(doc.frontmatter, { lineWidth: 100, singleQuote: false }).trimEnd();
+    const body = doc.body.startsWith('\n') ? doc.body.slice(1) : doc.body;
+    return `---\n${yaml}\n---\n\n${body.trimStart()}`;
+}
+/** Reads the frontmatter `name`, which must agree with the manifest and directory name. */
+export function documentName(doc) {
+    const name = doc.frontmatter['name'];
+    return typeof name === 'string' ? name.trim() : undefined;
+}
+export function documentDescription(doc) {
+    const description = doc.frontmatter['description'];
+    return typeof description === 'string' ? description.trim() : undefined;
+}
+export function documentVersion(doc) {
+    const version = doc.frontmatter['version'];
+    return typeof version === 'string' ? version.trim() : undefined;
+}
+//# sourceMappingURL=skill-document.js.map

package/dist/domain/skill-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-document.js","sourceRoot":"","sources":["../../src/domain/skill-document.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill-package.d.ts

@@ -0,0 +1,43 @@
+import { type PackageKind, type SkillManifest } from './manifest.ts';
+import { type SkillDocument } from './skill-document.ts';
+/**
+ * One file inside a package. Paths are always POSIX and relative to the package root;
+ * content is bytes so that `assets/` can hold images without a lossy round-trip.
+ */
+export interface PackageFile {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+    /** Present for files that came from a real filesystem; used for streaming copies. */
+    readonly sourcePath?: string;
+}
+/**
+ * A validated, in-memory skill package: the neutral artefact that registries produce and
+ * adapters project onto agent-specific layouts. Nothing here is agent-aware.
+ */
+export interface SkillPackage {
+    readonly manifest: SkillManifest;
+    readonly document: SkillDocument;
+    readonly files: readonly PackageFile[];
+}
+/**
+ * Reads a kind's entrypoint into the one neutral shape the rest of the system understands.
+ *
+ * Markdown kinds carry their identity in YAML frontmatter; a workflow carries it in
+ * `export const meta`. Normalising here — rather than teaching every caller about both — is
+ * what keeps validation, search and `info` identical across kinds.
+ */
+export declare function parseEntrypoint(kind: PackageKind, text: string, source: string): SkillDocument;
+export declare function decodeText(bytes: Uint8Array): string;
+export declare function encodeText(text: string): Uint8Array;
+export declare function findFile(pkg: SkillPackage, path: string): PackageFile | undefined;
+export declare function readTextFile(pkg: SkillPackage, path: string): string | undefined;
+/**
+ * Assembles a package from raw files, parsing the entrypoint. Structural validation beyond
+ * "can this be loaded at all" belongs to `ValidatePackage`, which reports every problem
+ * rather than failing on the first.
+ */
+export declare function buildSkillPackage(manifest: SkillManifest, files: readonly PackageFile[]): SkillPackage;
+/** Total uncompressed size, used for reporting and for archive-bomb limits. */
+export declare function packageSize(pkg: SkillPackage): number;
+export declare function isManifestFile(path: string): boolean;
+//# sourceMappingURL=skill-package.d.ts.map

package/dist/domain/skill-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-package.d.ts","sourceRoot":"","sources":["../../src/domain/skill-package.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAK7E;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAI9F;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEnD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGjF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,SAAS,WAAW,EAAE,GAC5B,YAAY,CA2Bd;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAErD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD"}

package/dist/domain/skill-package.js

@@ -0,0 +1,63 @@
+import { MANIFEST_FILENAME, entrypointFor, } from "./manifest.js";
+import { parseSkillDocument } from "./skill-document.js";
+import { parseWorkflowDocument } from "./workflow-document.js";
+import { AgentSkillsError, ErrorCode } from "./errors.js";
+import { normalize } from "./posix-path.js";
+/**
+ * Reads a kind's entrypoint into the one neutral shape the rest of the system understands.
+ *
+ * Markdown kinds carry their identity in YAML frontmatter; a workflow carries it in
+ * `export const meta`. Normalising here — rather than teaching every caller about both — is
+ * what keeps validation, search and `info` identical across kinds.
+ */
+export function parseEntrypoint(kind, text, source) {
+    return kind === 'workflow'
+        ? parseWorkflowDocument(text, source)
+        : parseSkillDocument(text, source);
+}
+const decoder = new TextDecoder('utf-8', { fatal: false });
+export function decodeText(bytes) {
+    return decoder.decode(bytes);
+}
+export function encodeText(text) {
+    return new TextEncoder().encode(text);
+}
+export function findFile(pkg, path) {
+    const target = normalize(path);
+    return pkg.files.find((file) => file.path === target);
+}
+export function readTextFile(pkg, path) {
+    const file = findFile(pkg, path);
+    return file === undefined ? undefined : decodeText(file.bytes);
+}
+/**
+ * Assembles a package from raw files, parsing the entrypoint. Structural validation beyond
+ * "can this be loaded at all" belongs to `ValidatePackage`, which reports every problem
+ * rather than failing on the first.
+ */
+export function buildSkillPackage(manifest, files) {
+    const normalizedFiles = files
+        .map((file) => ({ ...file, path: normalize(file.path) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const entrypoint = entrypointFor(manifest.kind);
+    const entry = normalizedFiles.find((file) => file.path === entrypoint);
+    if (entry === undefined) {
+        throw new AgentSkillsError(ErrorCode.INVALID_PACKAGE, `Package "${manifest.name}" is missing ${entrypoint}`, {
+            hints: [`Every ${manifest.kind} package must contain a ${entrypoint} at its root`],
+            data: { name: manifest.name, kind: manifest.kind },
+        });
+    }
+    return {
+        manifest,
+        document: parseEntrypoint(manifest.kind, decodeText(entry.bytes), `${manifest.name}/${entrypoint}`),
+        files: normalizedFiles,
+    };
+}
+/** Total uncompressed size, used for reporting and for archive-bomb limits. */
+export function packageSize(pkg) {
+    return pkg.files.reduce((total, file) => total + file.bytes.byteLength, 0);
+}
+export function isManifestFile(path) {
+    return normalize(path) === MANIFEST_FILENAME;
+}
+//# sourceMappingURL=skill-package.js.map

package/dist/domain/skill-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-package.js","sourceRoot":"","sources":["../../src/domain/skill-package.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill-ref.d.ts

@@ -0,0 +1,30 @@
+export declare const SKILL_NAME_MIN_LENGTH = 2;
+export declare const SKILL_NAME_MAX_LENGTH = 64;
+export declare function isValidSkillName(name: string): boolean;
+/** Returns human-readable reasons the name is unusable, or an empty list when it is fine. */
+export declare function validateSkillName(name: string): readonly string[];
+export declare function assertValidSkillName(name: string): void;
+/** `latest` is a resolution instruction, not a version; it is modelled explicitly. */
+export declare const LATEST = "latest";
+export interface SkillRef {
+    /** Registry name when the reference was qualified (`company:java-perf`), else undefined. */
+    readonly registry?: string;
+    readonly name: string;
+    /** A semver range, or `latest`. Undefined means "whatever the lockfile or latest says". */
+    readonly range?: string;
+    /** The original text, preserved for error messages. */
+    readonly raw: string;
+}
+/**
+ * Parses `[registry:]name[@range]`.
+ *
+ * Examples:
+ *   java-performance
+ *   java-performance@1.2.0
+ *   java-performance@^1.2.0
+ *   java-performance@latest
+ *   company:java-performance@~1.0
+ */
+export declare function parseSkillRef(raw: string): SkillRef;
+export declare function formatSkillRef(ref: SkillRef): string;
+//# sourceMappingURL=skill-ref.d.ts.map

package/dist/domain/skill-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-ref.d.ts","sourceRoot":"","sources":["../../src/domain/skill-ref.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAKxC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAoBjE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQvD;AAED,sFAAsF;AACtF,eAAO,MAAM,MAAM,WAAW,CAAC;AAE/B,MAAM,WAAW,QAAQ;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CA2DnD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAIpD"}

package/dist/domain/skill-ref.js

@@ -0,0 +1,119 @@
+import semver from 'semver';
+import { AgentSkillsError, ErrorCode } from "./errors.js";
+/**
+ * Skill names are directory names on three operating systems and identifiers in YAML,
+ * URLs and lockfiles. The grammar is therefore the intersection of what is safe
+ * everywhere: lowercase alphanumerics and single inner hyphens.
+ *
+ * `@` and `/` are deliberately excluded and reserved for a future `@org/skill` scoping
+ * scheme, so adding scopes later is not a breaking change.
+ */
+const SKILL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const REGISTRY_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
+export const SKILL_NAME_MIN_LENGTH = 2;
+export const SKILL_NAME_MAX_LENGTH = 64;
+/** Names that would collide with our own on-disk bookkeeping or with OS reserved words. */
+const RESERVED_SKILL_NAMES = new Set(['senior-skills', 'con', 'prn', 'aux', 'nul', 'node-modules']);
+export function isValidSkillName(name) {
+    return validateSkillName(name).length === 0;
+}
+/** Returns human-readable reasons the name is unusable, or an empty list when it is fine. */
+export function validateSkillName(name) {
+    const problems = [];
+    if (name.length < SKILL_NAME_MIN_LENGTH) {
+        problems.push(`must be at least ${SKILL_NAME_MIN_LENGTH} characters`);
+    }
+    if (name.length > SKILL_NAME_MAX_LENGTH) {
+        problems.push(`must be at most ${SKILL_NAME_MAX_LENGTH} characters`);
+    }
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        problems.push('must be lowercase alphanumerics separated by single hyphens (e.g. "java-performance")');
+    }
+    if (name.includes('--')) {
+        problems.push('must not contain consecutive hyphens');
+    }
+    if (RESERVED_SKILL_NAMES.has(name)) {
+        problems.push(`"${name}" is reserved`);
+    }
+    return problems;
+}
+export function assertValidSkillName(name) {
+    const problems = validateSkillName(name);
+    if (problems.length === 0)
+        return;
+    throw new AgentSkillsError(ErrorCode.INVALID_SKILL_NAME, `Invalid skill name "${name}"`, {
+        details: problems.map((problem) => `- ${problem}`),
+        hints: ['Skill names look like: java-performance, jvm-gc-tuning, react-testing'],
+        data: { name, problems },
+    });
+}
+/** `latest` is a resolution instruction, not a version; it is modelled explicitly. */
+export const LATEST = 'latest';
+/**
+ * Parses `[registry:]name[@range]`.
+ *
+ * Examples:
+ *   java-performance
+ *   java-performance@1.2.0
+ *   java-performance@^1.2.0
+ *   java-performance@latest
+ *   company:java-performance@~1.0
+ */
+export function parseSkillRef(raw) {
+    const text = raw.trim();
+    if (text === '') {
+        throw new AgentSkillsError(ErrorCode.USAGE, 'Empty skill reference', {
+            hints: ['Expected something like: java-performance or java-performance@1.2.0'],
+        });
+    }
+    let rest = text;
+    let registry;
+    const colon = rest.indexOf(':');
+    if (colon !== -1) {
+        registry = rest.slice(0, colon);
+        rest = rest.slice(colon + 1);
+        if (!REGISTRY_NAME_PATTERN.test(registry)) {
+            throw new AgentSkillsError(ErrorCode.USAGE, `Invalid registry qualifier "${registry}" in "${raw}"`, {
+                hints: ['Registry names are lowercase, e.g. official:java-performance'],
+                data: { raw },
+            });
+        }
+    }
+    let range;
+    const at = rest.lastIndexOf('@');
+    if (at > 0) {
+        range = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+    }
+    assertValidSkillName(rest);
+    if (range !== undefined) {
+        if (range === '') {
+            throw new AgentSkillsError(ErrorCode.USAGE, `Missing version after "@" in "${raw}"`, {
+                hints: [`Use ${rest}@latest, ${rest}@1.2.0 or ${rest}@^1.2.0`],
+                data: { raw },
+            });
+        }
+        if (range !== LATEST && semver.validRange(range) === null) {
+            throw new AgentSkillsError(ErrorCode.INVALID_VERSION, `Invalid version range "${range}"`, {
+                details: [`In reference: ${raw}`],
+                hints: ['Valid forms: 1.2.0, ^1.2.0, ~1.2, >=1.0.0 <2.0.0, latest'],
+                data: { raw, range },
+            });
+        }
+    }
+    const ref = {
+        name: rest,
+        raw: text,
+    };
+    if (registry !== undefined)
+        ref.registry = registry;
+    if (range !== undefined)
+        ref.range = range;
+    return ref;
+}
+export function formatSkillRef(ref) {
+    const qualifier = ref.registry === undefined ? '' : `${ref.registry}:`;
+    const range = ref.range === undefined ? '' : `@${ref.range}`;
+    return `${qualifier}${ref.name}${range}`;
+}
+//# sourceMappingURL=skill-ref.js.map

package/dist/domain/skill-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-ref.js","sourceRoot":"","sources":["../../src/domain/skill-ref.ts"],"names":[],"mappings":"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"}