nymor 1.0.1

package/dist/commands/validate.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCommand = validateCommand;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const paths_1 = require("../utils/paths");
+const skills_1 = require("../utils/skills");
+async function validateCommand() {
+    const projectRoot = process.cwd();
+    const skillsDir = (0, paths_1.getSkillsDir)(projectRoot);
+    const indexJsonPath = (0, paths_1.getIndexJsonPath)(projectRoot);
+    if (!(await fs_extra_1.default.pathExists(skillsDir))) {
+        console.log("No skills found. Run nymor init first.");
+        process.exitCode = 1;
+        return;
+    }
+    const indexExists = await fs_extra_1.default.pathExists(indexJsonPath);
+    const indexEntries = indexExists ? await fs_extra_1.default.readJson(indexJsonPath) : { skills: [] };
+    const indexIds = new Set(Array.isArray(indexEntries.skills) ? indexEntries.skills.map((entry) => entry.id) : []);
+    const skillDirs = await (0, skills_1.listSkillDirectories)(skillsDir);
+    console.log("Validating skills...\n");
+    let errorCount = 0;
+    const okMark = "\u2713";
+    const errMark = "\u2717";
+    for (const dirName of skillDirs) {
+        const skillPath = path_1.default.join(skillsDir, dirName, "SKILL.md");
+        const errors = [];
+        if (!(await fs_extra_1.default.pathExists(skillPath))) {
+            errors.push("missing SKILL.md");
+        }
+        else {
+            const content = await fs_extra_1.default.readFile(skillPath, "utf8");
+            try {
+                const { frontmatter, body } = (0, skills_1.parseSkillContent)(content, dirName);
+                if (!frontmatter.name) {
+                    errors.push("missing frontmatter name");
+                }
+                if (!hasSection(body, "Rule")) {
+                    errors.push("missing ## Rule section");
+                }
+                if (!hasSection(body, "Why")) {
+                    errors.push("missing ## Why section");
+                }
+                if (!hasSection(body, "Example")) {
+                    errors.push("missing ## Example section");
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                errors.push(message);
+            }
+        }
+        if (indexExists && !indexIds.has(dirName)) {
+            errors.push("not found in index.json");
+        }
+        if (errors.length === 0) {
+            console.log(`  ${okMark} ${dirName}`);
+        }
+        else {
+            errorCount += 1;
+            console.log(`  ${errMark} ${dirName} - ${errors.join("; ")}`);
+        }
+    }
+    if (!indexExists) {
+        errorCount += 1;
+        console.log("\nIndex not found. Run nymor compile to regenerate index.json.");
+    }
+    if (errorCount > 0) {
+        console.log(`\n${errorCount} issues found. Fix them or run nymor compile again.`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log("\nAll skills look good.");
+    }
+}
+function hasSection(content, heading) {
+    const regex = new RegExp(`^##\\s+${heading}\\b`, "m");
+    return regex.test(content);
+}

package/dist/compiler/agentsmd.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAgentsMarkdown = renderAgentsMarkdown;
+function renderAgentsMarkdown(skills) {
+    const alwaysApply = skills.filter((skill) => skill.frontmatter.alwaysApply);
+    if (alwaysApply.length === 0) {
+        return "No always-apply skills are currently configured.";
+    }
+    const blocks = alwaysApply.map((skill) => skill.body.trim());
+    return [
+        "# Nymor Agents",
+        "",
+        "This file is generated by nymor compile.",
+        "",
+        ...blocks.join("\n\n---\n\n").split("\n")
+    ].join("\n");
+}

package/dist/compiler/block.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderManagedBlock = renderManagedBlock;
+exports.upsertManagedBlock = upsertManagedBlock;
+const BLOCK_START = "<!-- nymor:start -->";
+const BLOCK_END = "<!-- nymor:end -->";
+function renderManagedBlock(content) {
+    const body = content.trimEnd();
+    return `${BLOCK_START}\n${body}\n${BLOCK_END}`;
+}
+function upsertManagedBlock(existing, content) {
+    const block = renderManagedBlock(content);
+    if (!existing) {
+        return `${block}\n`;
+    }
+    const pattern = new RegExp(`${escapeRegExp(BLOCK_START)}[\\s\\S]*?${escapeRegExp(BLOCK_END)}`);
+    if (pattern.test(existing)) {
+        return existing.replace(pattern, block);
+    }
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${separator}${block}\n`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&");
+}

package/dist/compiler/claude.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileClaudeSkills = compileClaudeSkills;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function compileClaudeSkills(skills, projectRoot) {
+    const outputRoot = path_1.default.join(projectRoot, ".claude", "skills");
+    await fs_extra_1.default.ensureDir(outputRoot);
+    for (const skill of skills) {
+        const targetDir = path_1.default.join(outputRoot, skill.id);
+        await fs_extra_1.default.copy(skill.dirPath, targetDir, { overwrite: true });
+    }
+}

package/dist/compiler/copilot.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileCopilotSkills = compileCopilotSkills;
+exports.renderCopilotInstructions = renderCopilotInstructions;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function compileCopilotSkills(skills, projectRoot) {
+    const outputRoot = path_1.default.join(projectRoot, ".github", "instructions");
+    await fs_extra_1.default.ensureDir(outputRoot);
+    for (const skill of skills) {
+        const fileName = `nymor-${skill.id}.instructions.md`;
+        const outputPath = path_1.default.join(outputRoot, fileName);
+        const content = renderCopilotInstructions(skill);
+        await fs_extra_1.default.writeFile(outputPath, content, "utf8");
+    }
+}
+function renderCopilotInstructions(skill) {
+    const globs = skill.frontmatter.globs ?? [];
+    const applyTo = globs.length > 0 ? globs.join(", ") : "**/*";
+    const lines = ["---", `applyTo: ${formatYamlValue(applyTo)}`, "---", ""];
+    return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}
+function formatYamlValue(value) {
+    const escaped = value.replace(/"/g, "\\\"");
+    return `"${escaped}"`;
+}

package/dist/compiler/cursor.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileCursorSkills = compileCursorSkills;
+exports.renderCursorRule = renderCursorRule;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function compileCursorSkills(skills, projectRoot) {
+    const outputRoot = path_1.default.join(projectRoot, ".cursor", "rules");
+    await fs_extra_1.default.ensureDir(outputRoot);
+    for (const skill of skills) {
+        const fileName = `nymor-${skill.id}.mdc`;
+        const outputPath = path_1.default.join(outputRoot, fileName);
+        const content = renderCursorRule(skill);
+        await fs_extra_1.default.writeFile(outputPath, content, "utf8");
+    }
+}
+function renderCursorRule(skill) {
+    const description = skill.frontmatter.description || skill.frontmatter.name;
+    const globs = skill.frontmatter.globs ?? [];
+    const alwaysApply = Boolean(skill.frontmatter.alwaysApply);
+    const lines = ["---", `description: ${formatYamlValue(description)}`];
+    if (globs.length > 0) {
+        lines.push("globs:");
+        globs.forEach((glob) => lines.push(`  - ${formatYamlValue(glob)}`));
+    }
+    else {
+        lines.push("globs: []");
+    }
+    lines.push(`alwaysApply: ${alwaysApply}`, "---", "");
+    return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}
+function formatYamlValue(value) {
+    const escaped = value.replace(/"/g, "\\\"");
+    return `"${escaped}"`;
+}

package/dist/compiler/kiro.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileKiroSkills = compileKiroSkills;
+exports.renderKiroSteering = renderKiroSteering;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function compileKiroSkills(skills, projectRoot) {
+    const outputRoot = path_1.default.join(projectRoot, ".kiro", "steering");
+    await fs_extra_1.default.ensureDir(outputRoot);
+    for (const skill of skills) {
+        const fileName = `nymor-${skill.id}.md`;
+        const outputPath = path_1.default.join(outputRoot, fileName);
+        const content = renderKiroSteering(skill);
+        await fs_extra_1.default.writeFile(outputPath, content, "utf8");
+    }
+}
+function renderKiroSteering(skill) {
+    const inclusion = skill.frontmatter.alwaysApply ? "always" : "manual";
+    const lines = ["---", `inclusion: ${inclusion}`, "---", ""];
+    return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}

package/dist/detector/agents.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAgents = detectAgents;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const targets_1 = require("../agents/targets");
+async function detectAgents(projectRoot) {
+    const entries = await Promise.all(targets_1.AGENT_TARGETS.map(async (target) => {
+        const detected = await hasAnyPath(projectRoot, target.detectPaths);
+        return [target.id, detected];
+    }));
+    return Object.fromEntries(entries);
+}
+async function hasAnyPath(projectRoot, relativePaths) {
+    for (const relativePath of relativePaths) {
+        if (await fs_extra_1.default.pathExists(path_1.default.join(projectRoot, relativePath))) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/detector/stack.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStack = detectStack;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const glob_1 = require("glob");
+const NODE_DEPENDENCIES = new Set(["express", "fastify", "koa", "hapi", "@nestjs/core"]);
+const REACT_DEPENDENCIES = new Set(["react", "next", "@remix-run/react"]);
+const VUE_DEPENDENCIES = new Set(["vue", "nuxt", "@nuxt/schema"]);
+const FULLSTACK_DEPENDENCIES = new Set(["next", "@remix-run/react"]);
+const SIGNALS = {
+    nodejs: ["server.js", "server.ts", "src/server.ts", "src/server.js"],
+    react: ["src/App.tsx", "src/App.jsx", "next.config.js", "next.config.ts"],
+    vue: ["vue.config.js", "nuxt.config.js", "nuxt.config.ts", "vite.config.ts"],
+    fullstack: ["next.config.js", "next.config.ts", "remix.config.js"],
+    python: ["requirements.txt", "pyproject.toml", "setup.py"],
+    django: ["manage.py"],
+    fastapi: ["main.py", "app/main.py"],
+    rust: ["Cargo.toml"],
+    go: ["go.mod"]
+};
+async function detectStack(projectRoot) {
+    const packageDependencies = await readPackageDependencies(projectRoot);
+    const pythonManifest = await readPythonManifest(projectRoot);
+    const detected = new Set();
+    if (hasAnyDependency(packageDependencies, FULLSTACK_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.fullstack))) {
+        detected.add("fullstack");
+    }
+    if (hasAnyDependency(packageDependencies, REACT_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.react))) {
+        detected.add("react");
+    }
+    if (hasAnyDependency(packageDependencies, VUE_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.vue))) {
+        detected.add("vue");
+    }
+    if (hasAnyDependency(packageDependencies, NODE_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.nodejs))) {
+        detected.add("nodejs");
+    }
+    if ((await hasAnySignal(projectRoot, SIGNALS.django)) && hasPythonDependency(pythonManifest, "django")) {
+        detected.add("django");
+    }
+    if (hasPythonDependency(pythonManifest, "fastapi") || (await hasAnySignal(projectRoot, SIGNALS.fastapi))) {
+        detected.add("fastapi");
+    }
+    if (pythonManifest || (await hasAnySignal(projectRoot, SIGNALS.python))) {
+        detected.add("python");
+    }
+    if (await hasAnySignal(projectRoot, SIGNALS.rust)) {
+        detected.add("rust");
+    }
+    if (await hasAnySignal(projectRoot, SIGNALS.go)) {
+        detected.add("go");
+    }
+    if (detected.has("django") || detected.has("fastapi")) {
+        detected.delete("python");
+    }
+    if (detected.size === 0) {
+        return null;
+    }
+    if (detected.has("fullstack") || detected.size > 1) {
+        return "fullstack";
+    }
+    return [...detected][0];
+}
+async function readPackageDependencies(projectRoot) {
+    const packageJsonPath = path_1.default.join(projectRoot, "package.json");
+    if (!(await fs_extra_1.default.pathExists(packageJsonPath))) {
+        return new Set();
+    }
+    try {
+        const pkg = await fs_extra_1.default.readJson(packageJsonPath);
+        return new Set(Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }));
+    }
+    catch {
+        return new Set();
+    }
+}
+async function readPythonManifest(projectRoot) {
+    const files = ["requirements.txt", "pyproject.toml", "setup.py"];
+    const contents = [];
+    for (const file of files) {
+        const filePath = path_1.default.join(projectRoot, file);
+        if (await fs_extra_1.default.pathExists(filePath)) {
+            contents.push(await fs_extra_1.default.readFile(filePath, "utf8"));
+        }
+    }
+    return contents.length > 0 ? contents.join("\n").toLowerCase() : null;
+}
+function hasAnyDependency(actual, expected) {
+    return [...expected].some((dependency) => actual.has(dependency));
+}
+function hasPythonDependency(manifest, dependency) {
+    if (!manifest) {
+        return false;
+    }
+    return new RegExp(`(^|[^a-z0-9_-])${dependency}([^a-z0-9_-]|$)`, "i").test(manifest);
+}
+async function hasAnySignal(projectRoot, patterns) {
+    for (const pattern of patterns) {
+        const matches = await (0, glob_1.glob)(pattern, {
+            cwd: projectRoot,
+            nodir: true,
+            dot: true,
+            ignore: ["**/node_modules/**", "**/.git/**"]
+        });
+        if (matches.length > 0) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const compile_1 = require("./commands/compile");
+const learn_1 = require("./commands/learn");
+const list_1 = require("./commands/list");
+const doctor_1 = require("./commands/doctor");
+const validate_1 = require("./commands/validate");
+const program = new commander_1.Command();
+program
+    .name("nymor")
+    .description("Teach your repo what your AI agents keep forgetting")
+    .version("2.0.0");
+program
+    .command("init")
+    .description("Initialize Nymor in the current repo")
+    .action(() => (0, init_1.initCommand)());
+program
+    .command("compile")
+    .description("Compile skills to agent surfaces")
+    .action(() => (0, compile_1.compileCommand)());
+program
+    .command("learn", { hidden: true })
+    .argument("<rule>", "One-line rule or convention to capture")
+    .option("--id <id>", "Local skill folder id")
+    .option("--name <name>", "Skill name")
+    .option("--description <description>", "Skill description")
+    .option("--globs <globs>", "Comma-separated file globs")
+    .option("--always-apply", "Apply the skill regardless of globs")
+    .option("--why <why>", "Why this rule matters")
+    .option("--example <example>", "Example or counter-example")
+    .description("Internal fallback for capturing a project rule as a local skill")
+    .action((rule, options) => (0, learn_1.learnCommand)(rule, options));
+program
+    .command("list")
+    .description("List active repo skills")
+    .action(() => (0, list_1.listCommand)());
+program
+    .command("doctor")
+    .description("Check skills for common issues")
+    .action(() => (0, doctor_1.doctorCommand)());
+program
+    .command("validate")
+    .description("Validate skill file format and index entries")
+    .action(() => (0, validate_1.validateCommand)());
+program.parseAsync(process.argv).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/registry/cache.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedTarball = getCachedTarball;
+exports.putCachedTarball = putCachedTarball;
+exports.getCachedIndex = getCachedIndex;
+exports.putCachedIndex = putCachedIndex;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+async function getCachedTarball(scope, name, version) {
+    const tarballPath = getTarballPath(scope, name, version);
+    if (!(await fs_extra_1.default.pathExists(tarballPath))) {
+        return null;
+    }
+    return fs_extra_1.default.readFile(tarballPath);
+}
+async function putCachedTarball(scope, name, version, tarball, integrity) {
+    const dir = getSkillVersionCacheDir(scope, name, version);
+    await fs_extra_1.default.ensureDir(dir);
+    await fs_extra_1.default.writeFile(path_1.default.join(dir, "SKILL.tar.gz"), tarball);
+    await fs_extra_1.default.writeFile(path_1.default.join(dir, "integrity.txt"), `${integrity}\n`, "utf8");
+}
+async function getCachedIndex(key, ttlMs) {
+    const indexPath = getIndexPath(key);
+    if (!(await fs_extra_1.default.pathExists(indexPath))) {
+        return null;
+    }
+    const stat = await fs_extra_1.default.stat(indexPath);
+    if (Date.now() - stat.mtimeMs > ttlMs) {
+        return null;
+    }
+    return fs_extra_1.default.readJson(indexPath);
+}
+async function putCachedIndex(key, value) {
+    const indexPath = getIndexPath(key);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(indexPath));
+    await fs_extra_1.default.writeJson(indexPath, value, { spaces: 2 });
+}
+function getTarballPath(scope, name, version) {
+    return path_1.default.join(getSkillVersionCacheDir(scope, name, version), "SKILL.tar.gz");
+}
+function getSkillVersionCacheDir(scope, name, version) {
+    return path_1.default.join(getCacheRoot(), "skills", formatSkillCacheKey(scope, name), version);
+}
+function getIndexPath(key) {
+    const fileName = key === "root" ? "root.json" : `${sanitizeCacheKey(key)}.json`;
+    return path_1.default.join(getCacheRoot(), "index", fileName);
+}
+function getCacheRoot() {
+    return path_1.default.join(process.env.HOME ?? os_1.default.homedir(), ".cicada", "cache");
+}
+function formatSkillCacheKey(scope, name) {
+    return `${scope}__${name}`;
+}
+function sanitizeCacheKey(key) {
+    return key.replace(/[\\/]/g, "__");
+}

package/dist/registry/client.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchRootIndex = fetchRootIndex;
+exports.fetchSkillIndex = fetchSkillIndex;
+exports.fetchSkillTarball = fetchSkillTarball;
+exports.extractSkillTarball = extractSkillTarball;
+exports.getSkillTarballUrl = getSkillTarballUrl;
+exports.computeIntegrity = computeIntegrity;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const tar = __importStar(require("tar"));
+const DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/cicada-skills/registry/main";
+async function fetchRootIndex() {
+    return fetchJson(joinRegistryUrl("index.json"));
+}
+async function fetchSkillIndex(scope, name) {
+    return fetchJson(joinRegistryUrl("skills", scope, name, "index.json"));
+}
+async function fetchSkillTarball(scope, name, version) {
+    const tarballUrl = getSkillTarballUrl(scope, name, version);
+    const integrityUrl = joinRegistryUrl("skills", scope, name, "versions", version, "integrity.txt");
+    const [tarball, integrityText] = await Promise.all([
+        fetchBuffer(tarballUrl),
+        fetchText(integrityUrl)
+    ]);
+    const integrity = integrityText.trim();
+    const computed = computeIntegrity(tarball);
+    if (computed !== integrity) {
+        throw new Error(`Integrity mismatch for ${scope}/${name}@${version}: expected ${integrity}, got ${computed}`);
+    }
+    return { tarball, integrity };
+}
+async function extractSkillTarball(tarball, destinationDir) {
+    await fs_extra_1.default.ensureDir(destinationDir);
+    const tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), "cicada-tarball-"));
+    const tarballPath = path_1.default.join(tempDir, "SKILL.tar.gz");
+    try {
+        await fs_extra_1.default.writeFile(tarballPath, tarball);
+        const entryPaths = [];
+        await tar.t({
+            file: tarballPath,
+            onentry: (entry) => {
+                entryPaths.push(entry.path);
+                entry.resume();
+            }
+        });
+        await tar.x({
+            file: tarballPath,
+            cwd: destinationDir,
+            strip: shouldStripLeadingDirectory(entryPaths) ? 1 : 0
+        });
+    }
+    finally {
+        await fs_extra_1.default.remove(tempDir);
+    }
+}
+function getSkillTarballUrl(scope, name, version) {
+    return joinRegistryUrl("skills", scope, name, "versions", version, "SKILL.tar.gz");
+}
+function computeIntegrity(value) {
+    return `sha256-${crypto_1.default.createHash("sha256").update(value).digest("base64")}`;
+}
+function getRegistryBaseUrl() {
+    return (process.env.CICADA_REGISTRY_URL ?? DEFAULT_REGISTRY_URL).replace(/\/+$/, "");
+}
+function joinRegistryUrl(...segments) {
+    return `${getRegistryBaseUrl()}/${segments.map((segment) => segment.replace(/^\/+|\/+$/g, "")).join("/")}`;
+}
+async function fetchJson(url) {
+    const response = await fetch(url, { headers: { connection: "close" } });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+async function fetchText(url) {
+    const response = await fetch(url, { headers: { connection: "close" } });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    return response.text();
+}
+async function fetchBuffer(url) {
+    const response = await fetch(url, { headers: { connection: "close" } });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+function shouldStripLeadingDirectory(entryPaths) {
+    const files = entryPaths.filter((entryPath) => !entryPath.endsWith("/"));
+    if (files.length === 0 || files.some((entryPath) => entryPath === "SKILL.md")) {
+        return false;
+    }
+    const [firstSegment] = files[0].split("/");
+    return Boolean(firstSegment) && files.every((entryPath) => entryPath.startsWith(`${firstSegment}/`));
+}

package/dist/registry/resolver.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionNotFoundError = void 0;
+exports.resolveVersion = resolveVersion;
+const semver_1 = __importDefault(require("semver"));
+class VersionNotFoundError extends Error {
+    constructor(spec, availableVersions) {
+        super(`No version found for range "${spec}" (available: ${availableVersions.join(", ") || "none"})`);
+        this.name = "VersionNotFoundError";
+    }
+}
+exports.VersionNotFoundError = VersionNotFoundError;
+function resolveVersion(spec, availableVersions) {
+    const versions = availableVersions.filter((version) => semver_1.default.valid(version)).sort(semver_1.default.rcompare);
+    if (versions.length === 0) {
+        throw new VersionNotFoundError(spec, availableVersions);
+    }
+    if (spec === "latest") {
+        return versions[0];
+    }
+    const max = semver_1.default.maxSatisfying(versions, spec);
+    if (!max) {
+        throw new VersionNotFoundError(spec, availableVersions);
+    }
+    return max;
+}

package/dist/registry/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });