@revealui/ai 0.1.0

package/dist/skills/registry/skill-registry.js

@@ -0,0 +1,373 @@
+/**
+ * Skill Registry
+ *
+ * Central registry for managing installed skills.
+ * Follows the pattern from tools/registry.ts.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { generateEmbedding } from '../../embeddings/index.js';
+import { parseSkillMd, parseSkillMetadataOnly } from '../parser/index.js';
+/**
+ * Cosine similarity between two vectors.
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have same length');
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const aVal = a[i] ?? 0;
+        const bVal = b[i] ?? 0;
+        dotProduct += aVal * bVal;
+        normA += aVal * aVal;
+        normB += bVal * bVal;
+    }
+    const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+    return magnitude === 0 ? 0 : dotProduct / magnitude;
+}
+/**
+ * Skill registry for managing installed skills.
+ */
+export class SkillRegistry {
+    skills = new Map();
+    metadataCache = new Map();
+    /** Maps skill name (metadata or directory) to directory path */
+    nameToPath = new Map();
+    globalDir;
+    localDir;
+    projectRoot;
+    constructor(config = {}) {
+        this.globalDir = config.globalDir ?? path.join(os.homedir(), '.revealui', 'skills');
+        this.localDir = config.localDir ?? '.revealui/skills';
+        this.projectRoot = config.projectRoot ?? process.cwd();
+    }
+    /**
+     * Get the resolved local directory path.
+     */
+    getLocalDirPath() {
+        return path.resolve(this.projectRoot, this.localDir);
+    }
+    /**
+     * Register a skill.
+     *
+     * @throws Error if skill name already registered
+     */
+    register(skill) {
+        if (this.skills.has(skill.metadata.name)) {
+            throw new Error(`Skill with name "${skill.metadata.name}" is already registered`);
+        }
+        this.skills.set(skill.metadata.name, skill);
+        this.metadataCache.set(skill.metadata.name, skill.metadata);
+    }
+    /**
+     * Unregister a skill by name.
+     */
+    unregister(name) {
+        this.skills.delete(name);
+        this.metadataCache.delete(name);
+    }
+    /**
+     * Get a skill by name.
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Check if a skill exists.
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * Get all registered skills.
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Get all skill names.
+     */
+    getNames() {
+        return Array.from(this.skills.keys());
+    }
+    /**
+     * Load all skill metadata from disk (lightweight).
+     * Only loads frontmatter, not full instructions.
+     */
+    async loadAllMetadata() {
+        this.metadataCache.clear();
+        this.nameToPath.clear();
+        // Load from both global and local directories
+        await this.loadMetadataFromDirectory(this.globalDir, 'global');
+        await this.loadMetadataFromDirectory(this.getLocalDirPath(), 'local');
+    }
+    /**
+     * Load metadata from a specific directory.
+     */
+    async loadMetadataFromDirectory(dir, scope) {
+        if (!fs.existsSync(dir)) {
+            return;
+        }
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillDirPath = path.join(dir, entry.name);
+            const skillMdPath = path.join(skillDirPath, 'SKILL.md');
+            if (!fs.existsSync(skillMdPath))
+                continue;
+            try {
+                const content = fs.readFileSync(skillMdPath, 'utf-8');
+                const metadata = parseSkillMetadataOnly(content);
+                // Local skills override global ones
+                if (scope === 'local' || !this.metadataCache.has(metadata.name)) {
+                    this.metadataCache.set(metadata.name, metadata);
+                    // Map both directory name and metadata name to the path
+                    this.nameToPath.set(entry.name, skillDirPath);
+                    this.nameToPath.set(metadata.name, skillDirPath);
+                }
+            }
+            catch {
+                // Skip directories with missing or invalid skill.json — registry remains partial
+            }
+        }
+    }
+    /**
+     * Get all loaded metadata (lightweight listing).
+     */
+    getAllMetadata() {
+        return Array.from(this.metadataCache.values());
+    }
+    /**
+     * Get metadata for a specific skill.
+     */
+    getMetadata(name) {
+        return this.metadataCache.get(name);
+    }
+    /**
+     * Load a full skill from disk (including instructions and resources).
+     *
+     * @param name - Skill name (metadata name or directory name)
+     * @param generateEmbed - Whether to generate embedding for the skill
+     */
+    async loadSkill(name, generateEmbed = false) {
+        // Check if already loaded by metadata name
+        if (this.skills.has(name)) {
+            return this.skills.get(name);
+        }
+        // Try to find the skill path using the name mapping
+        let skillPath = this.nameToPath.get(name);
+        let scope = 'local';
+        if (skillPath) {
+            // Determine scope from path
+            scope = skillPath.startsWith(this.globalDir) ? 'global' : 'local';
+        }
+        else {
+            // Fallback: try directory name directly (for skills not yet in cache)
+            skillPath = path.join(this.getLocalDirPath(), name);
+            if (!fs.existsSync(path.join(skillPath, 'SKILL.md'))) {
+                skillPath = path.join(this.globalDir, name);
+                scope = 'global';
+                if (!fs.existsSync(path.join(skillPath, 'SKILL.md'))) {
+                    return undefined;
+                }
+            }
+        }
+        const skillMdPath = path.join(skillPath, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath)) {
+            return undefined;
+        }
+        const content = fs.readFileSync(skillMdPath, 'utf-8');
+        const parsed = parseSkillMd(content);
+        // Check if already loaded by the actual metadata name
+        if (this.skills.has(parsed.metadata.name)) {
+            return this.skills.get(parsed.metadata.name);
+        }
+        // Load resources
+        const resources = await this.loadResources(skillPath);
+        // Generate embedding if requested
+        let embedding;
+        if (generateEmbed) {
+            const textForEmbedding = `${parsed.metadata.name}: ${parsed.metadata.description}\n${parsed.instructions.slice(0, 500)}`;
+            const result = await generateEmbedding(textForEmbedding);
+            embedding = result.vector;
+        }
+        const skill = {
+            metadata: parsed.metadata,
+            instructions: parsed.instructions,
+            sourcePath: skillPath,
+            scope,
+            resources,
+            embedding,
+            installedAt: this.getInstallDate(skillPath),
+        };
+        this.register(skill);
+        // Update name mapping with both names
+        this.nameToPath.set(parsed.metadata.name, skillPath);
+        this.nameToPath.set(path.basename(skillPath), skillPath);
+        return skill;
+    }
+    /**
+     * Load all skills from disk (full loading).
+     */
+    async loadAllSkills(generateEmbeddings = false) {
+        // First ensure metadata is loaded
+        if (this.metadataCache.size === 0) {
+            await this.loadAllMetadata();
+        }
+        // Load each skill fully using metadata names
+        for (const name of this.metadataCache.keys()) {
+            // Skip if already loaded
+            if (!this.skills.has(name)) {
+                await this.loadSkill(name, generateEmbeddings);
+            }
+        }
+    }
+    /**
+     * Load resources from a skill directory.
+     */
+    async loadResources(skillPath) {
+        const resources = [];
+        const resourceDirs = [
+            { dir: 'scripts', type: 'script' },
+            { dir: 'references', type: 'reference' },
+            { dir: 'assets', type: 'asset' },
+            { dir: 'templates', type: 'template' },
+            { dir: 'schemas', type: 'schema' },
+        ];
+        for (const { dir, type } of resourceDirs) {
+            const dirPath = path.join(skillPath, dir);
+            if (!fs.existsSync(dirPath))
+                continue;
+            const files = this.walkDirectory(dirPath);
+            for (const file of files) {
+                resources.push({
+                    path: path.relative(skillPath, file),
+                    type,
+                    // Content loaded on demand
+                });
+            }
+        }
+        return resources;
+    }
+    /**
+     * Recursively walk a directory.
+     */
+    walkDirectory(dir) {
+        const files = [];
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...this.walkDirectory(fullPath));
+            }
+            else {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    /**
+     * Get install date from directory stats.
+     */
+    getInstallDate(skillPath) {
+        try {
+            const stats = fs.statSync(skillPath);
+            return stats.birthtime.toISOString();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Search skills by embedding similarity.
+     *
+     * @param query - Search query text
+     * @param threshold - Minimum similarity score (default 0.7)
+     * @param limit - Maximum results to return
+     */
+    async searchByEmbedding(query, threshold = 0.7, limit = 10) {
+        // Generate query embedding
+        const queryEmbedding = await generateEmbedding(query);
+        // Load all skills with embeddings if not already loaded
+        const skills = this.getAll();
+        const results = [];
+        for (const skill of skills) {
+            // Generate embedding if missing
+            if (!skill.embedding) {
+                const textForEmbedding = `${skill.metadata.name}: ${skill.metadata.description}\n${skill.instructions.slice(0, 500)}`;
+                const result = await generateEmbedding(textForEmbedding);
+                skill.embedding = result.vector;
+            }
+            const score = cosineSimilarity(queryEmbedding.vector, skill.embedding);
+            if (score >= threshold) {
+                results.push({ skill, score });
+            }
+        }
+        // Sort by score descending and limit
+        return results.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /**
+     * Search skills by keyword matching.
+     */
+    searchByKeyword(query) {
+        const queryLower = query.toLowerCase();
+        const results = [];
+        for (const skill of this.skills.values()) {
+            let relevance = 0;
+            // Check name
+            if (skill.metadata.name.toLowerCase().includes(queryLower)) {
+                relevance += 10;
+            }
+            // Check description
+            if (skill.metadata.description.toLowerCase().includes(queryLower)) {
+                relevance += 5;
+            }
+            // Check tags
+            if (skill.metadata.tags?.some((tag) => tag.toLowerCase().includes(queryLower))) {
+                relevance += 3;
+            }
+            // Check instructions
+            if (skill.instructions.toLowerCase().includes(queryLower)) {
+                relevance += 1;
+            }
+            if (relevance > 0) {
+                results.push({ skill, relevance });
+            }
+        }
+        return results.sort((a, b) => b.relevance - a.relevance).map((r) => r.skill);
+    }
+    /**
+     * Get the installation directory for a skill.
+     */
+    getSkillDirectory(name, scope = 'local') {
+        if (scope === 'local') {
+            return path.join(this.getLocalDirPath(), name);
+        }
+        return path.join(this.globalDir, name);
+    }
+    /**
+     * Ensure a directory exists.
+     */
+    ensureDirectory(dir) {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    /**
+     * Clear the registry (for testing).
+     */
+    clear() {
+        this.skills.clear();
+        this.metadataCache.clear();
+        this.nameToPath.clear();
+    }
+}
+/**
+ * Global skill registry instance.
+ */
+export const globalSkillRegistry = new SkillRegistry();

package/dist/skills/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Skill Types
+ *
+ * Zod schemas and types for Agent Skills (skills.sh ecosystem).
+ * Skills are instruction packages that agents can discover and use.
+ */
+import { z } from 'zod/v4';
+/**
+ * Allowed tools specification.
+ * Format: "ToolName" or "ToolName(pattern:*)" for filtered access.
+ */
+export declare const AllowedToolSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    name: z.ZodString;
+    filter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type AllowedTool = z.infer<typeof AllowedToolSchema>;
+/**
+ * Skill metadata from SKILL.md frontmatter.
+ * This is the lightweight representation loaded at startup (~100 tokens).
+ */
+export declare const SkillMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    compatibility: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        openai: "openai";
+        anthropic: "anthropic";
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        windsurf: "windsurf";
+        cline: "cline";
+        copilot: "copilot";
+        universal: "universal";
+    }>>>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    minContextWindow: z.ZodOptional<z.ZodNumber>;
+    requiresApproval: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SkillMetadata = z.infer<typeof SkillMetadataSchema>;
+/**
+ * Resource file within a skill package.
+ */
+export declare const SkillResourceSchema: z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        template: "template";
+        schema: "schema";
+        script: "script";
+        reference: "reference";
+        asset: "asset";
+    }>;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SkillResource = z.infer<typeof SkillResourceSchema>;
+/**
+ * Source of a skill - where it was loaded from.
+ */
+export declare const SkillSourceSchema: z.ZodEnum<{
+    github: "github";
+    local: "local";
+    vercel: "vercel";
+}>;
+export type SkillSource = z.infer<typeof SkillSourceSchema>;
+/**
+ * Full skill object with instructions and resources.
+ */
+export declare const SkillSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+        license: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        repository: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        compatibility: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            openai: "openai";
+            anthropic: "anthropic";
+            "claude-code": "claude-code";
+            cursor: "cursor";
+            windsurf: "windsurf";
+            cline: "cline";
+            copilot: "copilot";
+            universal: "universal";
+        }>>>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        minContextWindow: z.ZodOptional<z.ZodNumber>;
+        requiresApproval: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    instructions: z.ZodString;
+    sourcePath: z.ZodString;
+    scope: z.ZodEnum<{
+        global: "global";
+        local: "local";
+    }>;
+    source: z.ZodOptional<z.ZodEnum<{
+        github: "github";
+        local: "local";
+        vercel: "vercel";
+    }>>;
+    sourceIdentifier: z.ZodOptional<z.ZodString>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<{
+            template: "template";
+            schema: "schema";
+            script: "script";
+            reference: "reference";
+            asset: "asset";
+        }>;
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    embedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    installedAt: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Skill = z.infer<typeof SkillSchema>;
+/**
+ * Skill activation context - information needed to determine which skills to activate.
+ */
+export declare const SkillActivationContextSchema: z.ZodObject<{
+    taskDescription: z.ZodOptional<z.ZodString>;
+    explicitSkills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    currentFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    projectType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SkillActivationContext = z.infer<typeof SkillActivationContextSchema>;
+/**
+ * Result of skill activation.
+ */
+export declare const SkillActivationResultSchema: z.ZodObject<{
+    activatedSkills: z.ZodArray<z.ZodObject<{
+        metadata: z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            license: z.ZodOptional<z.ZodString>;
+            author: z.ZodOptional<z.ZodString>;
+            repository: z.ZodOptional<z.ZodString>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            compatibility: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                openai: "openai";
+                anthropic: "anthropic";
+                "claude-code": "claude-code";
+                cursor: "cursor";
+                windsurf: "windsurf";
+                cline: "cline";
+                copilot: "copilot";
+                universal: "universal";
+            }>>>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            minContextWindow: z.ZodOptional<z.ZodNumber>;
+            requiresApproval: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>;
+        instructions: z.ZodString;
+        sourcePath: z.ZodString;
+        scope: z.ZodEnum<{
+            global: "global";
+            local: "local";
+        }>;
+        source: z.ZodOptional<z.ZodEnum<{
+            github: "github";
+            local: "local";
+            vercel: "vercel";
+        }>>;
+        sourceIdentifier: z.ZodOptional<z.ZodString>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            type: z.ZodEnum<{
+                template: "template";
+                schema: "schema";
+                script: "script";
+                reference: "reference";
+                asset: "asset";
+            }>;
+            content: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        embedding: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        installedAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    activationReasons: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            semantic: "semantic";
+            explicit: "explicit";
+            "file-match": "file-match";
+            "project-type": "project-type";
+        }>;
+        score: z.ZodOptional<z.ZodNumber>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SkillActivationResult = z.infer<typeof SkillActivationResultSchema>;
+/**
+ * Parsed allowed-tools specification.
+ */
+export interface ParsedAllowedTool {
+    name: string;
+    filter?: {
+        pattern: string;
+        type: 'prefix' | 'glob' | 'exact';
+    };
+}
+/**
+ * Parse an allowed-tools string like "Bash(git:*)" into structured form.
+ */
+export declare function parseAllowedTool(spec: string): ParsedAllowedTool;
+/**
+ * Check if a command matches an allowed-tool filter.
+ */
+export declare function matchesAllowedTool(toolName: string, command: string, allowed: ParsedAllowedTool): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/skills/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE1B;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;mBAM5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;iBA8C9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAS9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;EAAwC,CAAA;AACtE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BtB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,4BAA4B;;;;;iBAYvC,CAAA;AACF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEjF;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAatC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE/E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,MAAM,CAAA;QACf,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAA;KAClC,CAAA;CACF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA6BhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAwBT"}