@revealui/ai 0.1.0

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

@@ -0,0 +1,313 @@
+/**
+ * Vercel Skills Loader
+ *
+ * Bridge layer to load skills from the Vercel Skills ecosystem (skills.sh)
+ * and convert them to RevealUI's format.
+ */
+import { exec } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { logger } from '@revealui/core/observability/logger';
+import { parseSkillMd } from '../parser/index.js';
+import { parseVercelSource } from './vercel-types.js';
+const execAsync = promisify(exec);
+/**
+ * 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 async function loadFromVercelSkills(source, options) {
+    const parsed = parseVercelSource(source);
+    // 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 });
+    }
+    // Try npx skills first, fallback to direct git clone
+    let installPath;
+    try {
+        const result = await installViaVercelCli(source, {
+            dir: options.targetDir,
+            force: options.force,
+            ref: options.ref ?? parsed.ref,
+            global: options.scope === 'global',
+        });
+        if (result.success && result.installPath) {
+            installPath = result.installPath;
+        }
+    }
+    catch (error) {
+        logger.warn('Vercel CLI installation failed, falling back to git clone', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Fallback to direct git clone if npx skills failed
+    if (!installPath) {
+        installPath = await fallbackGitClone(parsed, targetPath);
+    }
+    // Find and validate SKILL.md
+    const skillMdPath = path.join(installPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+        // Clean up failed install
+        fs.rmSync(installPath, { 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 with Vercel source tracking
+    const skill = {
+        metadata: parsedSkill.metadata,
+        instructions: parsedSkill.instructions,
+        sourcePath: installPath,
+        scope: options.scope,
+        source: 'vercel',
+        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;
+}
+/**
+ * Install a skill using the Vercel Skills CLI (npx skills).
+ *
+ * @param source - Skill source identifier
+ * @param options - CLI options
+ * @returns Command execution result
+ */
+async function installViaVercelCli(source, options) {
+    const args = ['skills', 'add', source];
+    if (options.global) {
+        args.push('--global');
+    }
+    if (options.dir) {
+        args.push('--dir', options.dir);
+    }
+    if (options.force) {
+        args.push('--force');
+    }
+    if (options.ref) {
+        args.push('--ref', options.ref);
+    }
+    const command = `npx ${args.join(' ')}`;
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd: options.dir,
+            timeout: 60000, // 60 second timeout
+        });
+        // Parse output to detect installation path
+        const installPath = extractInstallPath(stdout, options.dir ?? process.cwd(), source);
+        return {
+            success: true,
+            stdout,
+            stderr,
+            installPath,
+        };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            success: false,
+            stdout: err.stdout ?? '',
+            stderr: err.stderr ?? err.message ?? 'Unknown error',
+        };
+    }
+}
+/**
+ * Extract the installation path from npx skills output.
+ *
+ * @param output - Command stdout
+ * @param baseDir - Base directory where skill was installed
+ * @param source - Original source string
+ * @returns Detected installation path
+ */
+function extractInstallPath(output, baseDir, source) {
+    // Try to parse the output to find installation location
+    // Common patterns:
+    // - "Installed skill to: /path/to/skill"
+    // - "✓ Installed skill-name"
+    const installMatch = output.match(/(?:Installed|installed).*?(?:to:?\s+)?([^\n]+)/i);
+    if (installMatch?.[1]) {
+        const detectedPath = installMatch[1].trim();
+        if (fs.existsSync(detectedPath)) {
+            return detectedPath;
+        }
+    }
+    // Fallback: try to construct path from source
+    const parsed = parseVercelSource(source);
+    const skillName = parsed.path ? path.basename(parsed.path) : parsed.repo;
+    const constructedPath = path.join(baseDir, skillName);
+    if (fs.existsSync(constructedPath)) {
+        return constructedPath;
+    }
+    return undefined;
+}
+/**
+ * Fallback: Clone directly from GitHub if npx skills fails.
+ *
+ * @param source - Parsed Vercel source
+ * @param targetPath - Target installation path
+ * @returns Installation path
+ */
+async function fallbackGitClone(source, targetPath) {
+    const repoUrl = `https://github.com/${source.owner}/${source.repo}.git`;
+    if (source.path) {
+        // Use sparse checkout for subdirectory
+        await sparseClone(repoUrl, targetPath, source.path, source.ref);
+    }
+    else {
+        // Clone entire repo
+        await fullClone(repoUrl, targetPath, source.ref);
+    }
+    return targetPath;
+}
+/**
+ * Perform a sparse checkout for a specific path.
+ */
+async function sparseClone(repoUrl, targetPath, subPath, ref) {
+    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 });
+    }
+}
+/**
+ * Check for updates to an installed Vercel skill.
+ *
+ * @param skillName - Name of the installed skill
+ * @param registry - Skill registry
+ * @returns Update information
+ */
+export async function checkVercelSkillUpdates(skillName, registry) {
+    const skill = registry.get(skillName);
+    if (!skill) {
+        throw new Error(`Skill "${skillName}" is not installed`);
+    }
+    if (skill.source !== 'vercel') {
+        throw new Error(`Skill "${skillName}" is not a Vercel skill`);
+    }
+    if (!skill.sourceIdentifier) {
+        throw new Error(`Skill "${skillName}" does not have source identifier`);
+    }
+    // For now, we'll use a simple approach:
+    // 1. Check if the GitHub repo has newer commits
+    // 2. Compare version in SKILL.md if available
+    try {
+        const parsed = parseVercelSource(skill.sourceIdentifier);
+        const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+        const currentVersion = skill.metadata.version ?? 'unknown';
+        // Version comparison requires fetching and parsing the remote SKILL.md,
+        // which is not yet implemented. Return false to avoid misleading prompts.
+        return {
+            available: false,
+            currentVersion,
+            changelog: `Check ${repoUrl} for changes`,
+        };
+    }
+    catch (error) {
+        logger.error('Error checking for updates', error instanceof Error ? error : new Error(String(error)));
+        return {
+            available: false,
+            currentVersion: skill.metadata.version,
+        };
+    }
+}
+/**
+ * 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 async function updateVercelSkill(skillName, registry) {
+    const skill = registry.get(skillName);
+    if (!skill) {
+        throw new Error(`Skill "${skillName}" is not installed`);
+    }
+    if (skill.source !== 'vercel') {
+        throw new Error(`Skill "${skillName}" is not a Vercel skill`);
+    }
+    if (!skill.sourceIdentifier) {
+        throw new Error(`Skill "${skillName}" does not have source identifier`);
+    }
+    // Reinstall with force flag
+    const options = {
+        targetDir: path.dirname(skill.sourcePath),
+        scope: skill.scope,
+        registry,
+        generateEmbedding: !!skill.embedding,
+        force: true,
+    };
+    return loadFromVercelSkills(skill.sourceIdentifier, options);
+}
+/**
+ * Check if npx skills CLI is available.
+ *
+ * @returns True if available, false otherwise
+ */
+export async function isVercelCliAvailable() {
+    try {
+        await execAsync('npx skills --version', { timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Vercel Skills Types
+ *
+ * Type definitions for interacting with the Vercel Skills ecosystem (skills.sh).
+ */
+import { z } from 'zod/v4';
+/**
+ * Vercel skill source specification.
+ *
+ * Formats supported:
+ * - owner/repo - Install from GitHub via Vercel Skills
+ * - owner/repo/path/to/skill - Install specific skill from monorepo
+ * - @scope/package - Install from npm (future)
+ */
+export interface VercelSource {
+    owner: string;
+    repo: string;
+    path?: string;
+    ref?: string;
+}
+/**
+ * Parse a Vercel source string into components.
+ *
+ * @example
+ * parseVercelSource("vercel-labs/agent-skills")
+ * // { owner: "vercel-labs", repo: "agent-skills" }
+ *
+ * parseVercelSource("vercel-labs/agent-skills/skills/react-best-practices")
+ * // { owner: "vercel-labs", repo: "agent-skills", path: "skills/react-best-practices" }
+ */
+export declare function parseVercelSource(source: string): VercelSource;
+/**
+ * Vercel Skills CLI installation options.
+ */
+export interface VercelCliOptions {
+    /** Install globally or locally */
+    global?: boolean;
+    /** Target directory override */
+    dir?: string;
+    /** Force reinstall */
+    force?: boolean;
+    /** Specific version/ref to install */
+    ref?: string;
+}
+/**
+ * Result of npx skills command execution.
+ */
+export interface VercelCommandResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    installPath?: string;
+}
+/**
+ * Update information for a Vercel skill.
+ */
+export declare const UpdateInfoSchema: z.ZodObject<{
+    available: z.ZodBoolean;
+    currentVersion: z.ZodOptional<z.ZodString>;
+    latestVersion: z.ZodOptional<z.ZodString>;
+    changelog: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UpdateInfo = z.infer<typeof UpdateInfoSchema>;
+//# sourceMappingURL=vercel-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-types.d.ts","sourceRoot":"","sources":["../../../src/skills/loader/vercel-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CA+B9D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAY3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

package/dist/skills/loader/vercel-types.js

@@ -0,0 +1,55 @@
+/**
+ * Vercel Skills Types
+ *
+ * Type definitions for interacting with the Vercel Skills ecosystem (skills.sh).
+ */
+import { z } from 'zod/v4';
+/**
+ * Parse a Vercel source string into components.
+ *
+ * @example
+ * parseVercelSource("vercel-labs/agent-skills")
+ * // { owner: "vercel-labs", repo: "agent-skills" }
+ *
+ * parseVercelSource("vercel-labs/agent-skills/skills/react-best-practices")
+ * // { owner: "vercel-labs", repo: "agent-skills", path: "skills/react-best-practices" }
+ */
+export function parseVercelSource(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 Vercel 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 Vercel source: ${source}. Expected format: owner/repo[/path][@ref]`);
+    }
+    return {
+        owner,
+        repo,
+        path: pathParts.length > 0 ? pathParts.join('/') : undefined,
+        ref,
+    };
+}
+/**
+ * Update information for a Vercel skill.
+ */
+export const UpdateInfoSchema = z.object({
+    /** Whether an update is available */
+    available: z.boolean(),
+    /** Current installed version */
+    currentVersion: z.string().optional(),
+    /** Latest available version */
+    latestVersion: z.string().optional(),
+    /** Changes in the update */
+    changelog: z.string().optional(),
+});

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

@@ -0,0 +1,7 @@
+/**
+ * SKILL.md Parser
+ *
+ * Utilities for parsing and validating SKILL.md files.
+ */
+export { generateSkillMd, type ParsedSkillMd, parseAllowedToolsString, parseSkillMd, parseSkillMetadataOnly, validateSkillMd, } from './skill-md-parser.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skills/parser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,uBAAuB,EACvB,YAAY,EACZ,sBAAsB,EACtB,eAAe,GAChB,MAAM,sBAAsB,CAAA"}

package/dist/skills/parser/index.js

@@ -0,0 +1,6 @@
+/**
+ * SKILL.md Parser
+ *
+ * Utilities for parsing and validating SKILL.md files.
+ */
+export { generateSkillMd, parseAllowedToolsString, parseSkillMd, parseSkillMetadataOnly, validateSkillMd, } from './skill-md-parser.js';

package/dist/skills/parser/skill-md-parser.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SKILL.md Parser
+ *
+ * Parses SKILL.md files to extract YAML frontmatter and markdown instructions.
+ */
+import { type SkillMetadata } from '../types.js';
+/**
+ * Result of parsing a SKILL.md file.
+ */
+export interface ParsedSkillMd {
+    metadata: SkillMetadata;
+    instructions: string;
+    rawFrontmatter: string;
+}
+/**
+ * Parse a SKILL.md file content into metadata and instructions.
+ *
+ * SKILL.md format:
+ * ```
+ * ---
+ * name: skill-name
+ * description: What this skill does
+ * ---
+ *
+ * # Instructions
+ *
+ * Markdown content here...
+ * ```
+ *
+ * @param content - Raw SKILL.md file content
+ * @returns Parsed skill metadata and instructions
+ * @throws Error if frontmatter is missing or invalid
+ */
+export declare function parseSkillMd(content: string): ParsedSkillMd;
+/**
+ * Parse allowed-tools string format into array.
+ *
+ * Example: "Bash(git:*) Read Write(*.ts)" -> ["Bash(git:*)", "Read", "Write(*.ts)"]
+ */
+export declare function parseAllowedToolsString(spec: string): string[];
+/**
+ * Extract only the metadata from a SKILL.md file (lightweight parsing).
+ * Used for loading skill listings without full content.
+ *
+ * @param content - Raw SKILL.md file content
+ * @returns Just the metadata portion
+ */
+export declare function parseSkillMetadataOnly(content: string): SkillMetadata;
+/**
+ * Validate that a string is valid SKILL.md format.
+ *
+ * @param content - Content to validate
+ * @returns true if valid, error message if invalid
+ */
+export declare function validateSkillMd(content: string): true | string;
+/**
+ * Generate a SKILL.md file from metadata and instructions.
+ *
+ * @param metadata - Skill metadata
+ * @param instructions - Markdown instructions
+ * @returns SKILL.md file content
+ */
+export declare function generateSkillMd(metadata: SkillMetadata, instructions: string): string;
+//# sourceMappingURL=skill-md-parser.d.ts.map

package/dist/skills/parser/skill-md-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md-parser.d.ts","sourceRoot":"","sources":["../../../src/skills/parser/skill-md-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,aAAa,CAAA;AAyGrE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA6C3D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA2B9D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAGrE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAO9D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGrF"}