skillex 0.2.0

package/dist/install.js

@@ -0,0 +1,895 @@
+import * as path from "node:path";
+import { DEFAULT_AGENT_SKILLS_DIR, DEFAULT_REF, DEFAULT_REPO, getStatePaths } from "./config.js";
+import { confirmAction } from "./confirm.js";
+import { ensureDir, pathExists, readJson, removePath, writeJson, writeText } from "./fs.js";
+import { fetchOptionalJson, fetchOptionalText, fetchText } from "./http.js";
+import { buildRawGitHubUrl, loadCatalog, resolveSource } from "./catalog.js";
+import { resolveAdapterState } from "./adapters.js";
+import { loadInstalledSkillDocuments, syncAdapterFiles } from "./sync.js";
+import { parseSkillFrontmatter } from "./skill.js";
+import { CliError, InstallError } from "./types.js";
+/**
+ * Initializes the local Skillex workspace state.
+ *
+ * @param options - Project initialization options.
+ * @returns Lockfile initialization result.
+ * @throws {InstallError} When initialization fails.
+ */
+export async function initProject(options = {}) {
+    try {
+        const cwd = options.cwd || process.cwd();
+        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const now = getNow(options);
+        await ensureDir(statePaths.stateDir);
+        await ensureDir(statePaths.skillsDirPath);
+        await ensureDir(statePaths.generatedDirPath);
+        const existing = await readJson(statePaths.lockfilePath, null);
+        const source = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+        const lockfile = normalizeLockfile(existing, source, now);
+        lockfile.adapters = await resolveAdapterState({
+            cwd,
+            ...(options.adapter || lockfile.adapters.active
+                ? { adapter: options.adapter || lockfile.adapters.active || undefined }
+                : {}),
+        });
+        if (options.repo) {
+            lockfile.sources = [toLockfileSource(source)];
+        }
+        lockfile.settings.autoSync = options.autoSync ?? lockfile.settings.autoSync;
+        if (lockfile.settings.autoSync && !lockfile.adapters.active) {
+            throw new InstallError("Auto-sync requires an active adapter. Use --adapter <id> or run in a detectable workspace.", "AUTO_SYNC_REQUIRES_ADAPTER");
+        }
+        lockfile.updatedAt = now();
+        await writeJson(statePaths.lockfilePath, lockfile);
+        // Create .gitignore for the state directory on first init
+        const gitignorePath = path.join(statePaths.stateDir, ".gitignore");
+        if (!(await pathExists(gitignorePath))) {
+            await writeText(gitignorePath, ".cache/\n*.log\n");
+        }
+        return { created: !existing, statePaths, lockfile };
+    }
+    catch (error) {
+        throw toInstallError(error, "Failed to initialize project");
+    }
+}
+/**
+ * Installs one or more catalog skills or direct GitHub skills into the local workspace state.
+ *
+ * @param requestedSkillIds - Requested skill ids or `owner/repo[@ref]` direct references.
+ * @param options - Installation options.
+ * @returns Install summary.
+ * @throws {InstallError} When installation fails.
+ */
+export async function installSkills(requestedSkillIds, options = {}) {
+    try {
+        const cwd = options.cwd || process.cwd();
+        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const now = getNow(options);
+        const catalogLoader = options.catalogLoader || loadCatalog;
+        const downloader = options.downloader || downloadSkill;
+        await ensureDir(statePaths.stateDir);
+        await ensureDir(statePaths.skillsDirPath);
+        await ensureDir(statePaths.generatedDirPath);
+        const existing = await readJson(statePaths.lockfilePath, null);
+        const overrideSource = options.repo ? resolveSource(toCatalogSourceInput(options, { repo: options.repo, ref: options.ref })) : null;
+        const defaultSource = overrideSource || resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+        const lockfile = normalizeLockfile(existing, defaultSource, now);
+        if (!lockfile.adapters.active) {
+            lockfile.adapters = await resolveAdapterState({
+                cwd,
+                ...(options.adapter ? { adapter: options.adapter } : {}),
+            });
+        }
+        const directRefs = requestedSkillIds
+            .map((skillId) => ({ input: skillId, reference: parseDirectGitHubRef(skillId) }))
+            .filter((entry) => entry.reference !== null);
+        const catalogIds = requestedSkillIds.filter((skillId) => parseDirectGitHubRef(skillId) === null);
+        const installedSkills = [];
+        if (options.installAll && directRefs.length > 0) {
+            throw new InstallError("Do not mix --all with direct GitHub references.", "INSTALL_ALL_WITH_DIRECT_REF");
+        }
+        if (options.installAll || catalogIds.length > 0) {
+            const selectedSkills = await selectSkillsFromSources(lockfile, catalogIds, options, catalogLoader);
+            const totalCount = selectedSkills.length + directRefs.length;
+            for (let i = 0; i < selectedSkills.length; i++) {
+                const selection = selectedSkills[i];
+                const skill = selection.skill;
+                options.onProgress?.(i + 1, totalCount, skill.id);
+                await downloader(skill, selection.catalog, statePaths.skillsDirPath);
+                lockfile.installed[skill.id] = buildInstalledMetadata(skill, {
+                    cwd,
+                    statePaths,
+                    installedAt: now(),
+                    source: `catalog:${selection.catalog.repo}@${selection.catalog.ref}`,
+                });
+                installedSkills.push(skill);
+            }
+        }
+        else if (!directRefs.length) {
+            throw new InstallError("Provide at least one skill-id, use --all, or pass owner/repo[@ref].", "INSTALL_REQUIRES_SKILL");
+        }
+        for (const directRef of directRefs) {
+            if (!options.trust) {
+                await confirmDirectInstall(directRef.input, options);
+            }
+            const directSkill = await fetchDirectGitHubSkill(directRef.reference);
+            await downloadDirectGitHubSkill(directSkill, statePaths.skillsDirPath);
+            lockfile.installed[directSkill.manifest.id] = buildInstalledMetadata(directSkill.manifest, {
+                cwd,
+                statePaths,
+                installedAt: now(),
+                source: directSkill.source,
+            });
+            installedSkills.push(directSkill.manifest);
+        }
+        lockfile.updatedAt = now();
+        await writeJson(statePaths.lockfilePath, lockfile);
+        const autoSync = await maybeAutoSync(withAgentSkillsDir({
+            cwd,
+            adapter: lockfile.adapters.active,
+            enabled: lockfile.settings.autoSync,
+            now,
+            changed: installedSkills.length > 0,
+            mode: options.mode,
+        }, options.agentSkillsDir));
+        return {
+            installedCount: installedSkills.length,
+            installedSkills,
+            statePaths,
+            autoSync,
+        };
+    }
+    catch (error) {
+        throw toInstallError(error, "Failed to install skills");
+    }
+}
+/**
+ * Updates installed skills from the configured remote catalog or their direct GitHub sources.
+ *
+ * @param requestedSkillIds - Optional subset of installed skills to update.
+ * @param options - Update options.
+ * @returns Update summary.
+ * @throws {InstallError} When update fails.
+ */
+export async function updateInstalledSkills(requestedSkillIds, options = {}) {
+    try {
+        const cwd = options.cwd || process.cwd();
+        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const now = getNow(options);
+        const catalogLoader = options.catalogLoader || loadCatalog;
+        const downloader = options.downloader || downloadSkill;
+        const existing = await readJson(statePaths.lockfilePath, null);
+        if (!existing) {
+            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+        }
+        const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+        const lockfile = normalizeLockfile(existing, defaultSource, now);
+        const skillIds = resolveInstalledSkillIds(lockfile, requestedSkillIds);
+        const directIds = skillIds.filter((skillId) => {
+            const metadata = lockfile.installed[skillId];
+            return Boolean(metadata?.source?.startsWith("github:"));
+        });
+        const catalogIds = skillIds.filter((skillId) => !directIds.includes(skillId));
+        const updatedSkills = [];
+        const missingFromCatalog = [];
+        if (catalogIds.length > 0) {
+            for (const skillId of catalogIds) {
+                const metadata = lockfile.installed[skillId];
+                const catalogSelection = await resolveInstalledCatalogSelection(skillId, metadata?.source, options, lockfile, catalogLoader);
+                if (!catalogSelection) {
+                    missingFromCatalog.push(skillId);
+                    continue;
+                }
+                const skill = catalogSelection.skill;
+                await downloader(skill, catalogSelection.catalog, statePaths.skillsDirPath);
+                lockfile.installed[skill.id] = buildInstalledMetadata(skill, {
+                    cwd,
+                    statePaths,
+                    installedAt: now(),
+                    source: `catalog:${catalogSelection.catalog.repo}@${catalogSelection.catalog.ref}`,
+                });
+                updatedSkills.push(skill);
+            }
+        }
+        for (const skillId of directIds) {
+            const metadata = lockfile.installed[skillId];
+            const directRef = metadata?.source ? parseGitHubSource(metadata.source) : null;
+            if (!directRef) {
+                throw new InstallError(`Invalid direct source for "${skillId}".`, "DIRECT_SOURCE_INVALID");
+            }
+            const directSkill = await fetchDirectGitHubSkill(directRef);
+            await downloadDirectGitHubSkill(directSkill, statePaths.skillsDirPath);
+            lockfile.installed[directSkill.manifest.id] = buildInstalledMetadata(directSkill.manifest, {
+                cwd,
+                statePaths,
+                installedAt: now(),
+                source: directSkill.source,
+            });
+            updatedSkills.push(directSkill.manifest);
+        }
+        lockfile.updatedAt = now();
+        await writeJson(statePaths.lockfilePath, lockfile);
+        const autoSync = await maybeAutoSync(withAgentSkillsDir({
+            cwd,
+            adapter: lockfile.adapters.active,
+            enabled: lockfile.settings.autoSync,
+            now,
+            changed: updatedSkills.length > 0,
+            mode: options.mode,
+        }, options.agentSkillsDir));
+        return {
+            statePaths,
+            updatedSkills,
+            missingFromCatalog,
+            autoSync,
+        };
+    }
+    catch (error) {
+        throw toInstallError(error, "Failed to update skills");
+    }
+}
+/**
+ * Removes installed skills from the local workspace state.
+ *
+ * @param requestedSkillIds - Skill ids to remove.
+ * @param options - Remove options.
+ * @returns Remove summary.
+ * @throws {InstallError} When removal fails.
+ */
+export async function removeSkills(requestedSkillIds, options = {}) {
+    try {
+        const cwd = options.cwd || process.cwd();
+        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const now = getNow(options);
+        const existing = await readJson(statePaths.lockfilePath, null);
+        if (!existing) {
+            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+        }
+        if (!requestedSkillIds.length) {
+            throw new InstallError("Provide at least one skill-id to remove.", "REMOVE_REQUIRES_SKILL");
+        }
+        const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+        const lockfile = normalizeLockfile(existing, defaultSource, now);
+        const removedSkills = [];
+        const missingSkills = [];
+        for (const skillId of requestedSkillIds) {
+            const metadata = lockfile.installed[skillId];
+            if (!metadata) {
+                missingSkills.push(skillId);
+                continue;
+            }
+            await removePath(path.resolve(cwd, metadata.path));
+            delete lockfile.installed[skillId];
+            removedSkills.push(skillId);
+        }
+        lockfile.updatedAt = now();
+        await writeJson(statePaths.lockfilePath, lockfile);
+        const autoSync = await maybeAutoSync(withAgentSkillsDir({
+            cwd,
+            adapter: lockfile.adapters.active,
+            enabled: lockfile.settings.autoSync,
+            now,
+            changed: removedSkills.length > 0,
+            mode: options.mode,
+        }, options.agentSkillsDir));
+        return {
+            statePaths,
+            removedSkills,
+            missingSkills,
+            autoSync,
+        };
+    }
+    catch (error) {
+        throw toInstallError(error, "Failed to remove skills");
+    }
+}
+/**
+ * Synchronizes installed skills to the active or requested adapter target.
+ *
+ * @param options - Sync options.
+ * @returns Sync command result.
+ * @throws {InstallError} When workspace state is missing or invalid.
+ */
+export async function syncInstalledSkills(options = {}) {
+    try {
+        const cwd = options.cwd || process.cwd();
+        const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+        const now = getNow(options);
+        const existing = await readJson(statePaths.lockfilePath, null);
+        if (!existing) {
+            throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+        }
+        const defaultSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+        const lockfile = normalizeLockfile(existing, defaultSource, now);
+        const adapterId = options.adapter || lockfile.adapters.active;
+        if (!adapterId) {
+            throw new InstallError("No active adapter configured. Run: skillex init --adapter <id> or use --adapter.", "ACTIVE_ADAPTER_MISSING");
+        }
+        const skills = await loadInstalledSkillDocuments({
+            cwd,
+            lockfile,
+        });
+        const syncResult = await syncAdapterFiles({
+            cwd,
+            adapterId,
+            statePaths,
+            skills,
+            ...(options.mode ? { mode: options.mode } : {}),
+            ...(options.dryRun !== undefined ? { dryRun: options.dryRun } : {}),
+        });
+        if (options.dryRun) {
+            return {
+                statePaths,
+                sync: {
+                    adapter: syncResult.adapter,
+                    targetPath: syncResult.targetPath,
+                },
+                skillCount: skills.length,
+                changed: syncResult.changed,
+                diff: syncResult.diff,
+                dryRun: true,
+                syncMode: syncResult.syncMode,
+            };
+        }
+        lockfile.sync = {
+            adapter: syncResult.adapter,
+            targetPath: syncResult.targetPath,
+            syncedAt: now(),
+        };
+        lockfile.syncMode = syncResult.syncMode;
+        lockfile.updatedAt = now();
+        await writeJson(statePaths.lockfilePath, lockfile);
+        return {
+            statePaths,
+            sync: lockfile.sync,
+            skillCount: skills.length,
+            changed: syncResult.changed,
+            diff: syncResult.diff,
+            dryRun: false,
+            syncMode: syncResult.syncMode,
+        };
+    }
+    catch (error) {
+        throw toInstallError(error, "Failed to synchronize skills");
+    }
+}
+/**
+ * Reads the local workspace lockfile when it exists.
+ *
+ * @param options - Project lookup options.
+ * @returns Normalized lockfile state or `null` when no install exists.
+ */
+export async function getInstalledSkills(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    if (!(await pathExists(statePaths.lockfilePath))) {
+        return null;
+    }
+    const source = resolveSource(toCatalogSourceInput(options, { repo: options.repo, ref: options.ref }));
+    const existing = await readJson(statePaths.lockfilePath, null);
+    if (!existing) {
+        return null;
+    }
+    return normalizeLockfile(existing, source, getNow(options));
+}
+/**
+ * Resolves the effective project catalog source using CLI overrides or local state.
+ *
+ * @param options - Project lookup options.
+ * @returns Resolved catalog source.
+ */
+export async function resolveProjectSource(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const existing = await readJson(statePaths.lockfilePath, null);
+    return resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+}
+/**
+ * Resolves all effective project sources using CLI overrides or local state.
+ *
+ * @param options - Project lookup options.
+ * @returns Resolved source list.
+ */
+export async function resolveProjectSources(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const existing = await readJson(statePaths.lockfilePath, null);
+    if (options.repo) {
+        return [toLockfileSource(resolveSource(toCatalogSourceInput(options, { repo: options.repo, ref: options.ref })))];
+    }
+    return getLockfileSources(existing, resolveSource(toCatalogSourceInput(options)));
+}
+/**
+ * Aggregates skills from all effective project sources.
+ *
+ * @param options - Project lookup options.
+ * @param catalogLoader - Optional catalog loader override.
+ * @returns Aggregated skills grouped by source metadata.
+ */
+export async function loadProjectCatalogs(options = {}, catalogLoader = loadCatalog) {
+    const sources = await resolveProjectSources(options);
+    const loaded = await Promise.all(sources.map(async (source) => {
+        const catalog = await catalogLoader(resolveSource(toCatalogSourceInput(options, source)));
+        const skills = catalog.skills.map((skill) => ({
+            ...skill,
+            source: {
+                repo: source.repo,
+                ref: source.ref,
+                ...(source.label ? { label: source.label } : {}),
+            },
+        }));
+        return { source, catalog, skills };
+    }));
+    return {
+        formatVersion: 1,
+        skills: loaded.flatMap((entry) => entry.skills),
+        sources: loaded.map((entry) => ({ ...entry.source, skillCount: entry.catalog.skills.length })),
+    };
+}
+/**
+ * Adds a source to the workspace lockfile.
+ *
+ * @param sourceInput - Repository to add.
+ * @param options - Project options.
+ * @returns Updated normalized lockfile.
+ */
+export async function addProjectSource(sourceInput, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const now = getNow(options);
+    await ensureDir(statePaths.stateDir);
+    await ensureDir(statePaths.skillsDirPath);
+    await ensureDir(statePaths.generatedDirPath);
+    const existing = await readJson(statePaths.lockfilePath, null);
+    const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+    const lockfile = normalizeLockfile(existing, fallbackSource, now);
+    const source = toLockfileSource(resolveSource(toCatalogSourceInput(options, sourceInput)), sourceInput.label);
+    if (lockfile.sources.some((entry) => entry.repo === source.repo && entry.ref === source.ref)) {
+        throw new InstallError(`Source \"${source.repo}@${source.ref}\" is already configured.`, "SOURCE_ALREADY_EXISTS");
+    }
+    lockfile.sources.push(source);
+    lockfile.updatedAt = now();
+    await writeJson(statePaths.lockfilePath, lockfile);
+    return lockfile;
+}
+/**
+ * Removes a source from the workspace lockfile.
+ *
+ * @param repo - Repository to remove.
+ * @param options - Project options.
+ * @returns Updated normalized lockfile.
+ */
+export async function removeProjectSource(repo, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const now = getNow(options);
+    const existing = await readJson(statePaths.lockfilePath, null);
+    if (!existing) {
+        throw new InstallError("No local installation found. Run: skillex init", "LOCKFILE_MISSING");
+    }
+    const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+    const lockfile = normalizeLockfile(existing, fallbackSource, now);
+    const remaining = lockfile.sources.filter((entry) => entry.repo !== repo);
+    if (remaining.length === lockfile.sources.length) {
+        throw new InstallError(`Source \"${repo}\" is not configured.`, "SOURCE_NOT_FOUND");
+    }
+    if (remaining.length === 0) {
+        throw new InstallError("At least one source must remain configured.", "SOURCE_REMOVE_LAST");
+    }
+    lockfile.sources = remaining;
+    lockfile.updatedAt = now();
+    await writeJson(statePaths.lockfilePath, lockfile);
+    return lockfile;
+}
+/**
+ * Lists configured workspace sources.
+ *
+ * @param options - Project options.
+ * @returns Normalized source list.
+ */
+export async function listProjectSources(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const existing = await readJson(statePaths.lockfilePath, null);
+    const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
+    return getLockfileSources(existing, fallbackSource);
+}
+/**
+ * Parses a direct GitHub install reference in `owner/repo[@ref]` format.
+ *
+ * @param input - User-supplied install argument.
+ * @returns Parsed direct GitHub reference or `null` when the value is not a direct ref.
+ */
+export function parseDirectGitHubRef(input) {
+    if (!input || input.startsWith("http://") || input.startsWith("https://")) {
+        return null;
+    }
+    const match = input.trim().match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:@(.+))?$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        owner: match[1],
+        repo: match[2],
+        ref: match[3] || "main",
+    };
+}
+function createBaseLockfile(source, now) {
+    return {
+        formatVersion: 1,
+        createdAt: now(),
+        updatedAt: now(),
+        sources: [toLockfileSource(source)],
+        adapters: {
+            active: null,
+            detected: [],
+        },
+        settings: {
+            autoSync: false,
+        },
+        sync: null,
+        syncMode: null,
+        installed: {},
+    };
+}
+async function downloadSkill(skill, catalog, skillsDirPath) {
+    const skillTargetDir = path.join(skillsDirPath, skill.id);
+    await removePath(skillTargetDir);
+    await ensureDir(skillTargetDir);
+    for (const relativePath of skill.files) {
+        const remotePath = skill.path ? path.posix.join(skill.path, relativePath) : relativePath;
+        const rawUrl = buildRawGitHubUrl(catalog.repo, catalog.ref, remotePath);
+        const content = await fetchText(rawUrl, { headers: { Accept: "text/plain" } });
+        const localPath = path.join(skillTargetDir, relativePath);
+        await writeText(localPath, content);
+    }
+    await writeDownloadedManifest(skillTargetDir, {
+        ...skill,
+        source: {
+            repo: catalog.repo,
+            ref: catalog.ref,
+            path: skill.path,
+        },
+    });
+}
+async function downloadDirectGitHubSkill(skill, skillsDirPath) {
+    const skillTargetDir = path.join(skillsDirPath, skill.manifest.id);
+    await removePath(skillTargetDir);
+    await ensureDir(skillTargetDir);
+    for (const relativePath of skill.manifest.files) {
+        const remotePath = skill.manifest.path ? path.posix.join(skill.manifest.path, relativePath) : relativePath;
+        const rawUrl = buildRawGitHubUrl(skill.repo, skill.ref, remotePath);
+        const content = await fetchText(rawUrl, { headers: { Accept: "text/plain" } });
+        await writeText(path.join(skillTargetDir, relativePath), content);
+    }
+    await writeDownloadedManifest(skillTargetDir, {
+        ...skill.manifest,
+        source: {
+            repo: skill.repo,
+            ref: skill.ref,
+            path: skill.manifest.path,
+        },
+    });
+}
+async function writeDownloadedManifest(skillTargetDir, manifest) {
+    await writeJson(path.join(skillTargetDir, "skill.json"), manifest);
+}
+async function fetchDirectGitHubSkill(reference) {
+    const repoId = `${reference.owner}/${reference.repo}`;
+    const manifestUrl = buildRawGitHubUrl(repoId, reference.ref, "skill.json");
+    const manifest = await fetchOptionalJson(manifestUrl, {
+        headers: { Accept: "application/json" },
+    });
+    if (manifest) {
+        return {
+            repo: repoId,
+            ref: reference.ref,
+            source: `github:${repoId}@${reference.ref}`,
+            manifest: normalizeDirectManifest(manifest, reference),
+        };
+    }
+    const skillMarkdown = await fetchOptionalText(buildRawGitHubUrl(repoId, reference.ref, "SKILL.md"), {
+        headers: { Accept: "text/plain" },
+    });
+    if (!skillMarkdown) {
+        throw new InstallError(`No skill.json or SKILL.md found at ${repoId}@${reference.ref}.`, "DIRECT_SKILL_NOT_FOUND");
+    }
+    const frontmatter = parseSkillFrontmatter(skillMarkdown);
+    return {
+        repo: repoId,
+        ref: reference.ref,
+        source: `github:${repoId}@${reference.ref}`,
+        manifest: {
+            id: normalizeRepoSkillId(reference.repo),
+            name: frontmatter.name || toTitleCase(reference.repo),
+            version: "0.1.0",
+            description: frontmatter.description || `Skill instalada diretamente de ${repoId}.`,
+            author: reference.owner,
+            tags: [],
+            compatibility: [],
+            entry: "SKILL.md",
+            path: "",
+            files: ["SKILL.md"],
+        },
+    };
+}
+function normalizeDirectManifest(manifest, reference) {
+    return {
+        id: manifest.id || normalizeRepoSkillId(reference.repo),
+        name: manifest.name || toTitleCase(reference.repo),
+        version: manifest.version || "0.1.0",
+        description: manifest.description || `Skill instalada diretamente de ${reference.owner}/${reference.repo}.`,
+        author: manifest.author || reference.owner,
+        tags: Array.isArray(manifest.tags) ? manifest.tags : [],
+        compatibility: Array.isArray(manifest.compatibility) ? manifest.compatibility : [],
+        entry: manifest.entry || "SKILL.md",
+        path: manifest.path || "",
+        files: Array.isArray(manifest.files) && manifest.files.length > 0 ? manifest.files : [manifest.entry || "SKILL.md"],
+        ...(manifest.scripts ? { scripts: manifest.scripts } : {}),
+    };
+}
+function normalizeLockfile(existing, source, now) {
+    if (!existing) {
+        return createBaseLockfile(source, now);
+    }
+    const detectedAdapters = Array.isArray(existing.adapters)
+        ? existing.adapters
+        : Array.isArray(existing.adapters?.detected)
+            ? existing.adapters.detected
+            : [];
+    const activeAdapter = Array.isArray(existing.adapters)
+        ? existing.adapters[0] || null
+        : existing.adapters?.active || detectedAdapters[0] || null;
+    return {
+        formatVersion: Number(existing.formatVersion || 1),
+        createdAt: existing.createdAt || now(),
+        updatedAt: existing.updatedAt || now(),
+        sources: getLockfileSources(existing, source),
+        adapters: {
+            active: activeAdapter,
+            detected: [...new Set(detectedAdapters.filter(Boolean))],
+        },
+        settings: {
+            autoSync: Boolean(existing.settings?.autoSync),
+        },
+        sync: existing.sync || null,
+        syncMode: existing.syncMode || null,
+        installed: existing.installed || {},
+    };
+}
+function getLockfileSources(existing, fallbackSource) {
+    const legacyCatalog = getLegacyCatalog(existing);
+    const configuredSources = Array.isArray(existing?.sources)
+        ? existing.sources
+            .filter((entry) => Boolean(entry?.repo))
+            .map((entry) => ({
+            repo: entry.repo,
+            ref: entry.ref || DEFAULT_REF,
+            ...(entry.label ? { label: entry.label } : {}),
+        }))
+        : [];
+    if (configuredSources.length > 0) {
+        return dedupeSources(configuredSources);
+    }
+    if (legacyCatalog?.repo) {
+        return dedupeSources([
+            {
+                repo: legacyCatalog.repo,
+                ref: legacyCatalog.ref || DEFAULT_REF,
+            },
+        ]);
+    }
+    return [toLockfileSource(fallbackSource)];
+}
+function getLegacyCatalog(existing) {
+    if (!existing || !("catalog" in existing)) {
+        return null;
+    }
+    const legacyState = existing;
+    return legacyState.catalog || null;
+}
+function dedupeSources(sources) {
+    const unique = new Map();
+    for (const source of sources) {
+        const key = `${source.repo}@${source.ref}`;
+        if (!unique.has(key)) {
+            unique.set(key, source);
+        }
+    }
+    return [...unique.values()];
+}
+function toLockfileSource(source, label) {
+    return {
+        repo: source.repo,
+        ref: source.ref,
+        ...((label || source.repo === DEFAULT_REPO) && (label || source.repo === DEFAULT_REPO)
+            ? { label: label || "official" }
+            : {}),
+    };
+}
+function resolvePrimarySourceOverride(options, existing) {
+    const sources = getLockfileSources(existing, resolveSource(toCatalogSourceInput(options)));
+    const repo = options.repo || sources[0]?.repo;
+    const ref = options.ref || sources[0]?.ref;
+    return {
+        ...(repo ? { repo } : {}),
+        ...(ref ? { ref } : {}),
+    };
+}
+async function selectSkillsFromSources(lockfile, requestedSkillIds, options, catalogLoader) {
+    const sources = options.repo
+        ? [toLockfileSource(resolveSource(toCatalogSourceInput(options, { repo: options.repo, ref: options.ref })))]
+        : lockfile.sources;
+    const catalogs = await Promise.all(sources.map(async (source) => ({
+        source,
+        catalog: await catalogLoader(resolveSource(toCatalogSourceInput(options, source))),
+    })));
+    if (options.installAll) {
+        const selections = catalogs.flatMap(({ source, catalog }) => catalog.skills.map((skill) => ({ skill, catalog, source })));
+        const seen = new Map();
+        for (const entry of selections) {
+            const currentSource = `${entry.source.repo}@${entry.source.ref}`;
+            const previousSource = seen.get(entry.skill.id);
+            if (previousSource) {
+                throw new InstallError(`Skill "${entry.skill.id}" exists in multiple sources: ${previousSource}, ${currentSource}. Use --repo to choose one source at a time.`, "SKILL_AMBIGUOUS_SOURCE");
+            }
+            seen.set(entry.skill.id, currentSource);
+        }
+        return selections;
+    }
+    if (!requestedSkillIds.length) {
+        return [];
+    }
+    return requestedSkillIds.map((skillId) => {
+        const matches = catalogs.flatMap(({ source, catalog }) => {
+            const skill = catalog.skills.find((entry) => entry.id === skillId);
+            return skill ? [{ skill, catalog, source }] : [];
+        });
+        if (matches.length === 0) {
+            throw new InstallError(`Skill "${skillId}" not found in the configured sources.`, "SKILL_NOT_FOUND");
+        }
+        if (matches.length > 1) {
+            const sourceList = matches.map((entry) => `${entry.source.repo}@${entry.source.ref}`).join(", ");
+            throw new InstallError(`Skill "${skillId}" exists in multiple sources: ${sourceList}. Use --repo to choose one.`, "SKILL_AMBIGUOUS_SOURCE");
+        }
+        return matches[0];
+    });
+}
+async function resolveInstalledCatalogSelection(skillId, sourceRef, options, lockfile, catalogLoader) {
+    const explicitSource = sourceRef?.startsWith("catalog:") ? parseCatalogSource(sourceRef) : null;
+    const sources = explicitSource ? [explicitSource] : lockfile.sources;
+    for (const source of sources) {
+        const catalog = await catalogLoader(resolveSource(toCatalogSourceInput(options, source)));
+        const skill = catalog.skills.find((entry) => entry.id === skillId);
+        if (skill) {
+            return { skill, catalog, source };
+        }
+    }
+    return null;
+}
+function parseCatalogSource(source) {
+    const match = source.match(/^catalog:([^@]+\/[^@]+)@(.+)$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        repo: match[1],
+        ref: match[2],
+    };
+}
+function buildInstalledMetadata(skill, context) {
+    return {
+        name: skill.name,
+        version: skill.version,
+        path: toPosix(path.relative(context.cwd, path.join(context.statePaths.skillsDirPath, skill.id))),
+        installedAt: context.installedAt,
+        compatibility: skill.compatibility,
+        tags: skill.tags,
+        source: context.source,
+    };
+}
+function resolveInstalledSkillIds(lockfile, requestedSkillIds) {
+    const installedIds = Object.keys(lockfile.installed || {});
+    if (installedIds.length === 0) {
+        throw new InstallError("No skills installed to update.", "NO_SKILLS_INSTALLED");
+    }
+    if (!requestedSkillIds.length) {
+        return installedIds;
+    }
+    const installedSet = new Set(installedIds);
+    for (const skillId of requestedSkillIds) {
+        if (!installedSet.has(skillId)) {
+            throw new InstallError(`Skill "${skillId}" is not installed locally.`, "SKILL_NOT_INSTALLED");
+        }
+    }
+    return requestedSkillIds;
+}
+function getNow(options) {
+    return options.now || (() => new Date().toISOString());
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+async function maybeAutoSync(options) {
+    if (!options.enabled || !options.changed) {
+        return null;
+    }
+    return syncInstalledSkills({
+        cwd: options.cwd,
+        ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
+        ...(options.adapter ? { adapter: options.adapter } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        now: options.now,
+    });
+}
+function toCatalogSourceInput(options, overrides = {}) {
+    const input = {};
+    if (options.owner) {
+        input.owner = options.owner;
+    }
+    if (options.repoName) {
+        input.repoName = options.repoName;
+    }
+    if (overrides.repo ?? options.repo) {
+        input.repo = overrides.repo ?? options.repo;
+    }
+    if (overrides.ref ?? options.ref) {
+        input.ref = overrides.ref ?? options.ref;
+    }
+    if (options.catalogPath) {
+        input.catalogPath = options.catalogPath;
+    }
+    if (options.skillsDir) {
+        input.skillsDir = options.skillsDir;
+    }
+    if (options.catalogUrl !== undefined) {
+        input.catalogUrl = options.catalogUrl;
+    }
+    return input;
+}
+function withAgentSkillsDir(options, agentSkillsDir) {
+    return {
+        ...options,
+        ...(agentSkillsDir ? { agentSkillsDir } : {}),
+    };
+}
+async function confirmDirectInstall(skillRef, options) {
+    const warning = `Warning: ${skillRef} will be installed directly from GitHub and has not been verified by the active catalog.`;
+    (options.warn || console.error)(warning);
+    const confirm = options.confirm || (() => confirmAction("Continuar com a instalacao direta?"));
+    const accepted = await confirm();
+    if (!accepted) {
+        throw new InstallError("Instalacao direta cancelada pelo usuario.", "INSTALL_CANCELLED");
+    }
+}
+function parseGitHubSource(source) {
+    if (!source.startsWith("github:")) {
+        return null;
+    }
+    const withoutPrefix = source.slice("github:".length);
+    const separatorIndex = withoutPrefix.lastIndexOf("@");
+    if (separatorIndex <= 0) {
+        return null;
+    }
+    return parseDirectGitHubRef(`${withoutPrefix.slice(0, separatorIndex)}@${withoutPrefix.slice(separatorIndex + 1)}`);
+}
+function normalizeRepoSkillId(repo) {
+    return repo.trim().toLowerCase();
+}
+function toTitleCase(skillId) {
+    return skillId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function toInstallError(error, fallbackMessage) {
+    if (error instanceof InstallError) {
+        return error;
+    }
+    if (error instanceof CliError) {
+        return new InstallError(error.message, error.code);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new InstallError(`${fallbackMessage}: ${message}`);
+}