@revealui/ai 0.1.0

package/dist/skills/loader/github-loader.js

@@ -0,0 +1,176 @@
+/**
+ * GitHub Skill Loader
+ *
+ * Install skills from GitHub repositories.
+ */
+import { exec } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { parseSkillMd } from '../parser/index.js';
+const execAsync = promisify(exec);
+/**
+ * Parse a GitHub source string into components.
+ *
+ * @example
+ * parseGitHubSource("vercel-labs/agent-skills")
+ * // { owner: "vercel-labs", repo: "agent-skills" }
+ *
+ * parseGitHubSource("vercel-labs/agent-skills/skills/react-best-practices")
+ * // { owner: "vercel-labs", repo: "agent-skills", path: "skills/react-best-practices" }
+ */
+export function parseGitHubSource(source) {
+    // Handle @ref suffix for specific branch/tag
+    let ref;
+    let sourcePath = source;
+    if (source.includes('@')) {
+        const atIndex = source.lastIndexOf('@');
+        ref = source.slice(atIndex + 1);
+        sourcePath = source.slice(0, atIndex);
+    }
+    const parts = sourcePath.split('/');
+    if (parts.length < 2) {
+        throw new Error(`Invalid GitHub source: ${source}. Expected format: owner/repo[/path][@ref]`);
+    }
+    const owner = parts[0];
+    const repo = parts[1];
+    const pathParts = parts.slice(2);
+    if (!(owner && repo)) {
+        throw new Error(`Invalid GitHub source: ${source}. Expected format: owner/repo[/path][@ref]`);
+    }
+    return {
+        owner,
+        repo,
+        path: pathParts.length > 0 ? pathParts.join('/') : undefined,
+        ref,
+    };
+}
+/**
+ * Load a skill from a GitHub repository.
+ *
+ * Uses git sparse checkout for efficiency when loading from a subdirectory.
+ */
+export async function loadFromGitHub(source, options) {
+    const parsed = parseGitHubSource(source);
+    const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+    // Determine skill name from path or repo name
+    const skillName = parsed.path ? path.basename(parsed.path) : parsed.repo;
+    const targetPath = path.join(options.targetDir, skillName);
+    // Check if already exists
+    if (fs.existsSync(targetPath)) {
+        if (options.force) {
+            fs.rmSync(targetPath, { recursive: true });
+        }
+        else {
+            throw new Error(`Skill "${skillName}" already exists. Use --force to overwrite.`);
+        }
+    }
+    // Ensure target directory exists
+    if (!fs.existsSync(options.targetDir)) {
+        fs.mkdirSync(options.targetDir, { recursive: true });
+    }
+    if (parsed.path) {
+        // Use sparse checkout for subdirectory
+        await sparseClone(repoUrl, targetPath, parsed.path, parsed.ref);
+    }
+    else {
+        // Clone entire repo
+        await fullClone(repoUrl, targetPath, parsed.ref);
+    }
+    // Find and validate SKILL.md
+    const skillMdPath = path.join(targetPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+        // Clean up failed install
+        fs.rmSync(targetPath, { recursive: true });
+        throw new Error(`No SKILL.md found in ${source}`);
+    }
+    // Parse and validate
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    const parsedSkill = parseSkillMd(content);
+    // Create skill object
+    const skill = {
+        metadata: parsedSkill.metadata,
+        instructions: parsedSkill.instructions,
+        sourcePath: targetPath,
+        scope: options.scope,
+        source: 'github',
+        sourceIdentifier: source,
+        installedAt: new Date().toISOString(),
+    };
+    // Register with registry
+    if (options.registry.has(skill.metadata.name)) {
+        options.registry.unregister(skill.metadata.name);
+    }
+    options.registry.register(skill);
+    // Load fully (with resources and optionally embedding)
+    return (await options.registry.loadSkill(skill.metadata.name, options.generateEmbedding)) ?? skill;
+}
+/**
+ * Perform a sparse checkout for a specific path.
+ */
+async function sparseClone(repoUrl, targetPath, subPath, ref) {
+    // Create a temp directory for the sparse checkout
+    const tempDir = `${targetPath}.tmp`;
+    try {
+        // Initialize sparse checkout
+        await execAsync(`git clone --depth 1 --filter=blob:none --sparse ${repoUrl} ${tempDir}`);
+        // Configure sparse checkout
+        await execAsync(`git -C ${tempDir} sparse-checkout set ${subPath}`);
+        // Checkout specific ref if provided
+        if (ref) {
+            await execAsync(`git -C ${tempDir} fetch --depth 1 origin ${ref}`);
+            await execAsync(`git -C ${tempDir} checkout ${ref}`);
+        }
+        // Move the skill directory to target
+        const sourcePath = path.join(tempDir, subPath);
+        if (!fs.existsSync(sourcePath)) {
+            throw new Error(`Path "${subPath}" not found in repository`);
+        }
+        fs.renameSync(sourcePath, targetPath);
+    }
+    finally {
+        // Clean up temp directory
+        if (fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true });
+        }
+    }
+}
+/**
+ * Perform a full shallow clone.
+ */
+async function fullClone(repoUrl, targetPath, ref) {
+    const refArg = ref ? `--branch ${ref}` : '';
+    await execAsync(`git clone --depth 1 ${refArg} ${repoUrl} ${targetPath}`);
+    // Remove .git directory to save space
+    const gitDir = path.join(targetPath, '.git');
+    if (fs.existsSync(gitDir)) {
+        fs.rmSync(gitDir, { recursive: true });
+    }
+}
+/**
+ * Update an installed skill from GitHub.
+ */
+export async function updateFromGitHub(skillName, registry) {
+    const skill = registry.get(skillName);
+    if (!skill) {
+        throw new Error(`Skill "${skillName}" is not installed`);
+    }
+    // For now, we don't track the original source URL
+    // This would require storing metadata about where the skill came from
+    throw new Error('Update not yet implemented. Please reinstall with --force.');
+}
+/**
+ * Check if a GitHub source is valid and accessible.
+ */
+export async function validateGitHubSource(source) {
+    try {
+        const parsed = parseGitHubSource(source);
+        const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+        // Use git ls-remote to check if repo exists
+        await execAsync(`git ls-remote --exit-code ${repoUrl} HEAD`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/skills/loader/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Skill Loaders
+ *
+ * Load skills from various sources (GitHub, local directories, Vercel Skills ecosystem).
+ */
+export { type GitHubLoadOptions, type GitHubSource, loadFromGitHub, parseGitHubSource, updateFromGitHub, validateGitHubSource, } from './github-loader.js';
+export { createSkill, type LocalLoadOptions, loadAllFromDirectory, loadFromLocal, removeSkill, type SkillTemplate, } from './local-loader.js';
+export { checkVercelSkillUpdates, isVercelCliAvailable, loadFromVercelSkills, updateVercelSkill, type VercelLoadOptions, } from './vercel-loader.js';
+export { parseVercelSource, type UpdateInfo, type VercelSource } from './vercel-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skills/loader/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/skills/loader/index.js

@@ -0,0 +1,9 @@
+/**
+ * Skill Loaders
+ *
+ * Load skills from various sources (GitHub, local directories, Vercel Skills ecosystem).
+ */
+export { loadFromGitHub, parseGitHubSource, updateFromGitHub, validateGitHubSource, } from './github-loader.js';
+export { createSkill, loadAllFromDirectory, loadFromLocal, removeSkill, } from './local-loader.js';
+export { checkVercelSkillUpdates, isVercelCliAvailable, loadFromVercelSkills, updateVercelSkill, } from './vercel-loader.js';
+export { parseVercelSource } from './vercel-types.js';

package/dist/skills/loader/local-loader.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Local Skill Loader
+ *
+ * Load skills from local directories.
+ */
+import type { SkillRegistry } from '../registry/index.js';
+import type { Skill } from '../types.js';
+/**
+ * Options for loading from local directory.
+ */
+export interface LocalLoadOptions {
+    /** Target directory for installation (if copying) */
+    targetDir?: string;
+    /** Scope: local (project) or global */
+    scope: 'local' | 'global';
+    /** Registry to register skill with */
+    registry: SkillRegistry;
+    /** Generate embedding for semantic search */
+    generateEmbedding?: boolean;
+    /** Copy files instead of referencing in place */
+    copy?: boolean;
+    /** Force reinstall if already exists */
+    force?: boolean;
+}
+/**
+ * Load a skill from a local directory.
+ *
+ * @param sourcePath - Path to skill directory containing SKILL.md
+ * @param options - Load options
+ */
+export declare function loadFromLocal(sourcePath: string, options: LocalLoadOptions): Promise<Skill>;
+/**
+ * Load all skills from a directory.
+ *
+ * @param dir - Directory containing skill subdirectories
+ * @param options - Load options
+ */
+export declare function loadAllFromDirectory(dir: string, options: Omit<LocalLoadOptions, 'copy'>): Promise<Skill[]>;
+/**
+ * Create a new skill from a template.
+ */
+export declare function createSkill(name: string, targetDir: string, template?: SkillTemplate): Promise<string>;
+/**
+ * Template for creating new skills.
+ */
+export interface SkillTemplate {
+    skillMd?: string;
+    createScripts?: boolean;
+    createReferences?: boolean;
+    createAssets?: boolean;
+}
+/**
+ * Remove an installed skill.
+ */
+export declare function removeSkill(name: string, registry: SkillRegistry): boolean;
+//# sourceMappingURL=local-loader.d.ts.map

package/dist/skills/loader/local-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-loader.d.ts","sourceRoot":"","sources":["../../../src/skills/loader/local-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,uCAAuC;IACvC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAA;IAEzB,sCAAsC;IACtC,QAAQ,EAAE,aAAa,CAAA;IAEvB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CA+DjG;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACtC,OAAO,CAAC,KAAK,EAAE,CAAC,CA8BlB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAkDD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAe1E"}

package/dist/skills/loader/local-loader.js

@@ -0,0 +1,186 @@
+/**
+ * Local Skill Loader
+ *
+ * Load skills from local directories.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseSkillMd } from '../parser/index.js';
+/**
+ * Load a skill from a local directory.
+ *
+ * @param sourcePath - Path to skill directory containing SKILL.md
+ * @param options - Load options
+ */
+export async function loadFromLocal(sourcePath, options) {
+    const resolvedSource = path.resolve(sourcePath);
+    // Validate source exists
+    if (!fs.existsSync(resolvedSource)) {
+        throw new Error(`Source directory does not exist: ${resolvedSource}`);
+    }
+    // Check for SKILL.md
+    const skillMdPath = path.join(resolvedSource, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+        throw new Error(`No SKILL.md found in ${resolvedSource}`);
+    }
+    // Parse skill
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    const parsed = parseSkillMd(content);
+    const skillName = parsed.metadata.name;
+    let finalPath = resolvedSource;
+    // Copy files if requested
+    if (options.copy && options.targetDir) {
+        const targetPath = path.join(options.targetDir, skillName);
+        // Check if already exists
+        if (fs.existsSync(targetPath)) {
+            if (options.force) {
+                fs.rmSync(targetPath, { recursive: true });
+            }
+            else {
+                throw new Error(`Skill "${skillName}" already exists. Use --force to overwrite.`);
+            }
+        }
+        // Ensure target directory exists
+        if (!fs.existsSync(options.targetDir)) {
+            fs.mkdirSync(options.targetDir, { recursive: true });
+        }
+        // Copy directory
+        copyDirectory(resolvedSource, targetPath);
+        finalPath = targetPath;
+    }
+    // Create skill object
+    const skill = {
+        metadata: parsed.metadata,
+        instructions: parsed.instructions,
+        sourcePath: finalPath,
+        scope: options.scope,
+        source: 'local',
+        sourceIdentifier: sourcePath,
+        installedAt: new Date().toISOString(),
+    };
+    // Register with registry
+    if (options.registry.has(skillName)) {
+        options.registry.unregister(skillName);
+    }
+    options.registry.register(skill);
+    // Load fully (with resources and optionally embedding)
+    return (await options.registry.loadSkill(skillName, options.generateEmbedding)) ?? skill;
+}
+/**
+ * Load all skills from a directory.
+ *
+ * @param dir - Directory containing skill subdirectories
+ * @param options - Load options
+ */
+export async function loadAllFromDirectory(dir, options) {
+    const resolvedDir = path.resolve(dir);
+    if (!fs.existsSync(resolvedDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillPath = path.join(resolvedDir, entry.name);
+        const skillMdPath = path.join(skillPath, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath))
+            continue;
+        try {
+            const skill = await loadFromLocal(skillPath, {
+                ...options,
+                copy: false, // Don't copy when loading from installed directory
+            });
+            skills.push(skill);
+        }
+        catch {
+            // Skip malformed or unreadable skill files — partial load is better than a hard crash
+        }
+    }
+    return skills;
+}
+/**
+ * Create a new skill from a template.
+ */
+export async function createSkill(name, targetDir, template) {
+    const skillDir = path.join(targetDir, name);
+    if (fs.existsSync(skillDir)) {
+        throw new Error(`Directory already exists: ${skillDir}`);
+    }
+    fs.mkdirSync(skillDir, { recursive: true });
+    // Create SKILL.md
+    const skillMd = template?.skillMd ?? generateDefaultSkillMd(name);
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillMd);
+    // Create optional directories
+    if (template?.createScripts) {
+        fs.mkdirSync(path.join(skillDir, 'scripts'));
+    }
+    if (template?.createReferences) {
+        fs.mkdirSync(path.join(skillDir, 'references'));
+    }
+    if (template?.createAssets) {
+        fs.mkdirSync(path.join(skillDir, 'assets'));
+    }
+    return skillDir;
+}
+/**
+ * Generate a default SKILL.md file.
+ */
+function generateDefaultSkillMd(name) {
+    return `---
+name: ${name}
+description: A new skill for agents
+version: "0.1.0"
+compatibility:
+  - universal
+---
+
+# ${name}
+
+Instructions for the agent go here.
+
+## Overview
+
+Describe what this skill does.
+
+## Usage
+
+Explain how to use this skill.
+`;
+}
+/**
+ * Copy a directory recursively.
+ */
+function copyDirectory(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            // Skip .git directory
+            if (entry.name === '.git')
+                continue;
+            copyDirectory(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Remove an installed skill.
+ */
+export function removeSkill(name, registry) {
+    const skill = registry.get(name);
+    if (!skill) {
+        return false;
+    }
+    // Remove from filesystem
+    if (fs.existsSync(skill.sourcePath)) {
+        fs.rmSync(skill.sourcePath, { recursive: true });
+    }
+    // Unregister
+    registry.unregister(name);
+    return true;
+}

package/dist/skills/loader/vercel-loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Vercel Skills Loader
+ *
+ * Bridge layer to load skills from the Vercel Skills ecosystem (skills.sh)
+ * and convert them to RevealUI's format.
+ */
+import type { SkillRegistry } from '../registry/index.js';
+import type { Skill } from '../types.js';
+import type { UpdateInfo } from './vercel-types.js';
+/**
+ * Options for loading from Vercel Skills ecosystem.
+ */
+export interface VercelLoadOptions {
+    /** Target directory for installation */
+    targetDir: string;
+    /** Scope: local (project) or global */
+    scope: 'local' | 'global';
+    /** Registry to register skill with */
+    registry: SkillRegistry;
+    /** Generate embedding for semantic search */
+    generateEmbedding?: boolean;
+    /** Force reinstall if already exists */
+    force?: boolean;
+    /** Specific ref/version to install */
+    ref?: string;
+}
+/**
+ * Load a skill from the Vercel Skills ecosystem.
+ *
+ * This function:
+ * 1. Executes `npx skills add <source>` to install the skill
+ * 2. Detects the installation location
+ * 3. Parses the installed SKILL.md
+ * 4. Registers with RevealUI's SkillRegistry
+ * 5. Optionally generates embeddings for semantic search
+ *
+ * @param source - Vercel skill source (e.g., "vercel-labs/agent-skills/react-best-practices")
+ * @param options - Load options
+ * @returns Fully loaded Skill object
+ */
+export declare function loadFromVercelSkills(source: string, options: VercelLoadOptions): Promise<Skill>;
+/**
+ * Check for updates to an installed Vercel skill.
+ *
+ * @param skillName - Name of the installed skill
+ * @param registry - Skill registry
+ * @returns Update information
+ */
+export declare function checkVercelSkillUpdates(skillName: string, registry: SkillRegistry): Promise<UpdateInfo>;
+/**
+ * Update an installed Vercel skill to the latest version.
+ *
+ * @param skillName - Name of the skill to update
+ * @param registry - Skill registry
+ * @returns Updated skill object
+ */
+export declare function updateVercelSkill(skillName: string, registry: SkillRegistry): Promise<Skill>;
+/**
+ * Check if npx skills CLI is available.
+ *
+ * @returns True if available, false otherwise
+ */
+export declare function isVercelCliAvailable(): Promise<boolean>;
+//# sourceMappingURL=vercel-loader.d.ts.map

package/dist/skills/loader/vercel-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-loader.d.ts","sourceRoot":"","sources":["../../../src/skills/loader/vercel-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,KAAK,EACV,UAAU,EAIX,MAAM,mBAAmB,CAAA;AAK1B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;IAEjB,uCAAuC;IACvC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAA;IAEzB,sCAAsC;IACtC,QAAQ,EAAE,aAAa,CAAA;IAEvB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,KAAK,CAAC,CA8EhB;AAsKD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,UAAU,CAAC,CAyCrB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,KAAK,CAAC,CAwBhB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO7D"}