matimo 0.1.0-alpha.8 → 0.1.1

package/packages/core/dist/core/skill-loader.js

@@ -0,0 +1,310 @@
+/**
+ * Skill Loader — loads and validates skills from multiple sources
+ *
+ * Implements agentskills.io specification with proper YAML parsing and Zod validation.
+ *
+ * @see https://agentskills.io/specification
+ */
+import fs from 'fs';
+import path from 'path';
+import YAML from 'js-yaml';
+import { z } from 'zod';
+import { parseSkillSections } from './skill-content-parser';
+import { getGlobalMatimoLogger } from '../logging';
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+// ─── Name Validation ─────────────────────────────────────────────────────────
+const VALID_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const CONSECUTIVE_HYPHENS = /--/;
+const MAX_NAME_LENGTH = 64;
+function validateSkillName(name) {
+    if (!name || name.trim().length === 0) {
+        return { valid: false, error: 'Skill name is required' };
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        return {
+            valid: false,
+            error: `Skill name must be at most ${MAX_NAME_LENGTH} characters`,
+        };
+    }
+    if (!VALID_NAME_PATTERN.test(name)) {
+        return {
+            valid: false,
+            error: 'Skill name must contain only lowercase letters, numbers, and hyphens, and must not start or end with a hyphen',
+        };
+    }
+    if (CONSECUTIVE_HYPHENS.test(name)) {
+        return { valid: false, error: 'Skill name must not contain consecutive hyphens' };
+    }
+    return { valid: true };
+}
+// ─── YAML Parser & Validation ──────────────────────────────────────────────
+/**
+ * Parser schema for skill frontmatter (using Zod for runtime validation)
+ */
+const FrontmatterSchema = z.object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().min(1, 'description is required').max(1024),
+    version: z.string().optional(),
+    license: z.string().optional(),
+    compatibility: z.string().max(500).optional(),
+    'allowed-tools': z.union([z.string(), z.array(z.string())]).optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+});
+/**
+ * Helper: Extract and validate YAML frontmatter
+ * @returns { frontmatter, body, error }
+ */
+function extractFrontmatter(content) {
+    if (!content?.startsWith('---')) {
+        return { error: 'Skill content must start with YAML frontmatter (---)' };
+    }
+    const endIndex = content.indexOf('---', 3);
+    if (endIndex === -1) {
+        return { error: 'Skill content must have closing YAML frontmatter (---)' };
+    }
+    const frontmatterBlock = content.substring(3, endIndex).trim();
+    const body = content.substring(endIndex + 3).trim();
+    let parsed;
+    try {
+        parsed = YAML.load(frontmatterBlock) || {};
+    }
+    catch (e) {
+        return { error: `Failed to parse YAML frontmatter: ${e.message}` };
+    }
+    // Normalize allowed-tools: convert space-delimited string to array
+    if (parsed['allowed-tools'] && typeof parsed['allowed-tools'] === 'string') {
+        parsed['allowed-tools'] = parsed['allowed-tools'].split(/\s+/);
+    }
+    // Validate with Zod
+    const validationResult = FrontmatterSchema.safeParse(parsed);
+    if (!validationResult.success) {
+        const errors = validationResult.error.issues
+            .map((e) => `${e.path.join('.')}: ${e.message}`)
+            .join('; ');
+        return { error: `Frontmatter validation failed: ${errors}` };
+    }
+    const frontmatter = {
+        name: validationResult.data.name,
+        description: validationResult.data.description,
+        version: validationResult.data.version,
+        license: validationResult.data.license,
+        compatibility: validationResult.data.compatibility,
+        'allowed-tools': validationResult.data['allowed-tools'],
+        metadata: validationResult.data.metadata,
+    };
+    return { frontmatter, body };
+}
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ */
+export function parseSkillContent(content) {
+    const { frontmatter, body, error } = extractFrontmatter(content);
+    if (error) {
+        return {
+            error,
+            frontmatter: { name: '', description: '' },
+            body: content.substring(content.indexOf('---', 3) + 3).trim() || '',
+            raw: content,
+        };
+    }
+    // Parse body into structured sections for selective context loading
+    const parsedContent = parseSkillSections(body);
+    return {
+        frontmatter: frontmatter,
+        body: body,
+        raw: content,
+        sections: parsedContent.sections,
+        totalTokens: parsedContent.totalTokens,
+    };
+}
+/**
+ * Extract ONLY metadata from SKILL.md without parsing body/sections.
+ *
+ * Optimized for matimo_list_skills — reads YAML frontmatter only.
+ * This avoids the overhead of parsing sections and body content.
+ *
+ * Returns SkillSummary: name, description, version, license, metadata, source.
+ */
+export function extractSkillMetadata(content, source = 'user') {
+    const { frontmatter, error } = extractFrontmatter(content);
+    if (error) {
+        return { success: false, error };
+    }
+    // Return only metadata fields (no body, sections, or body content)
+    return {
+        success: true,
+        metadata: {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            version: frontmatter.version,
+            license: frontmatter.license,
+            metadata: frontmatter.metadata,
+            source,
+        },
+    };
+}
+// ─── Bundled Resources Discovery ───────────────────────────────────────────
+function listBundledResources(skillDir) {
+    const resources = {
+        scripts: [],
+        references: [],
+        assets: [],
+        other: [],
+    };
+    if (!fs.existsSync(skillDir))
+        return resources;
+    const KNOWN_DIRS = {
+        scripts: 'scripts',
+        references: 'references',
+        assets: 'assets',
+    };
+    const entries = fs.readdirSync(skillDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === 'SKILL.md')
+            continue;
+        if (entry.isDirectory()) {
+            const category = KNOWN_DIRS[entry.name];
+            if (category) {
+                const subDir = path.join(skillDir, entry.name);
+                const subEntries = fs.readdirSync(subDir);
+                for (const sub of subEntries) {
+                    resources[category].push(`${entry.name}/${sub}`);
+                }
+            }
+            else {
+                const subDir = path.join(skillDir, entry.name);
+                const subEntries = fs.readdirSync(subDir);
+                for (const sub of subEntries) {
+                    resources.other.push(`${entry.name}/${sub}`);
+                }
+            }
+        }
+        else {
+            resources.other.push(entry.name);
+        }
+    }
+    return resources;
+}
+// ─── SkillLoader ──────────────────────────────────────────────────────────
+/**
+ * SkillLoader reads and validates skills from directories
+ */
+export class SkillLoader {
+    constructor() {
+        this.logger = getGlobalMatimoLogger();
+    }
+    /**
+     * Load all skills from a directory
+     */
+    loadSkillsFromDirectory(skillsDir, source = 'user') {
+        const skills = [];
+        if (!fs.existsSync(skillsDir)) {
+            return skills;
+        }
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillPath = path.join(skillsDir, entry.name, 'SKILL.md');
+            if (!fs.existsSync(skillPath))
+                continue;
+            try {
+                this.logger.debug('SkillLoader: attempting to load skill', {
+                    name: entry.name,
+                    skillPath,
+                });
+                const skill = this.loadSkill(entry.name, skillsDir, source);
+                if (skill) {
+                    skills.push(skill);
+                    this.logger.debug('SkillLoader: successfully loaded skill', {
+                        name: skill.name,
+                    });
+                }
+                else {
+                    this.logger.warn('SkillLoader: loadSkill returned null', {
+                        name: entry.name,
+                    });
+                }
+            }
+            catch (err) {
+                this.logger.error('SkillLoader: failed to load skill', {
+                    dir: entry.name,
+                    error: err.message,
+                    stack: err.stack,
+                    skillsDir,
+                });
+            }
+        }
+        return skills;
+    }
+    /**
+     * Load a single skill by name
+     */
+    loadSkill(name, skillsDir, source = 'user') {
+        // Validate name
+        const nameValidation = validateSkillName(name);
+        if (!nameValidation.valid) {
+            throw new MatimoError(`Invalid skill name: ${nameValidation.error}`, ErrorCode.INVALID_SCHEMA);
+        }
+        const skillDir = path.join(skillsDir, name);
+        const skillPath = path.join(skillDir, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) {
+            throw new MatimoError(`Skill not found: ${skillPath}`, ErrorCode.TOOL_NOT_FOUND);
+        }
+        const content = fs.readFileSync(skillPath, 'utf-8');
+        const parsed = parseSkillContent(content);
+        if (parsed.error) {
+            throw new MatimoError(`Failed to parse skill: ${parsed.error}`, ErrorCode.INVALID_SCHEMA);
+        }
+        const { frontmatter } = parsed;
+        // Verify frontmatter name matches directory name
+        if (frontmatter.name !== name) {
+            throw new MatimoError(`Skill name "${frontmatter.name}" must match directory name "${name}"`, ErrorCode.INVALID_SCHEMA);
+        }
+        const resources = listBundledResources(skillDir);
+        const skill = {
+            name: frontmatter.name,
+            description: frontmatter.description,
+            version: frontmatter.version,
+            license: frontmatter.license,
+            compatibility: frontmatter.compatibility,
+            allowedTools: frontmatter['allowed-tools'],
+            metadata: frontmatter.metadata,
+            body: parsed.body,
+            sections: parsed.sections,
+            totalTokens: parsed.totalTokens,
+            resources,
+            source,
+            _path: skillDir,
+        };
+        return skill;
+    }
+    /**
+     * Load a skill resource file (scripts/, references/, assets/)
+     */
+    loadSkillResource(skillName, skillsDir, resourcePath) {
+        // Validate resource path (prevent traversal)
+        if (/\.\.|\\/u.test(resourcePath) || /[\x00-\x1f]/.test(resourcePath)) {
+            throw new MatimoError('Resource path contains invalid characters', ErrorCode.INVALID_SCHEMA);
+        }
+        const skillDir = path.join(skillsDir, skillName);
+        const resourceFullPath = path.join(skillDir, resourcePath);
+        // Verify path stays within skill directory
+        const resolvedPath = path.resolve(resourceFullPath);
+        const resolvedSkillDir = path.resolve(skillDir);
+        if (!resolvedPath.startsWith(resolvedSkillDir + path.sep) &&
+            resolvedPath !== resolvedSkillDir) {
+            throw new MatimoError('Resource path escapes the skill directory', ErrorCode.INVALID_SCHEMA);
+        }
+        if (!fs.existsSync(resourceFullPath)) {
+            throw new MatimoError(`Resource file not found: ${resourcePath}`, ErrorCode.TOOL_NOT_FOUND);
+        }
+        try {
+            return fs.readFileSync(resourceFullPath, 'utf-8');
+        }
+        catch (err) {
+            throw new MatimoError(`Failed to read resource file: ${err.message}`, ErrorCode.EXECUTION_FAILED);
+        }
+    }
+}
+//# sourceMappingURL=skill-loader.js.map

package/packages/core/dist/core/skill-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.js","sourceRoot":"","sources":["../../src/core/skill-loader.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/skill-registry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Skill Registry — in-memory store and search for skills
+ *
+ * Mirrors ToolRegistry but for skills. Provides discovery, search, and filtering.
+ * Supports both substring matching (default) and semantic search via pluggable embeddings.
+ */
+import { SkillDefinition, SkillSummary, SearchSkillsOptions, EmbeddingProvider, SkillContentOptions } from './types';
+/**
+ * Semantic search result with relevance score.
+ */
+export interface SemanticSearchResult {
+    skill: SkillSummary;
+    /** Cosine similarity score (0–1, higher = more relevant) */
+    score: number;
+}
+export declare class SkillRegistry {
+    private logger;
+    private skills;
+    /** Pluggable embedding provider for semantic search */
+    private embeddingProvider;
+    /** Cached embeddings: skill name → vector */
+    private embeddings;
+    /** Whether embeddings need rebuilding */
+    private embeddingsDirty;
+    /** Cached parsed content for selective loading */
+    private parsedContent;
+    /**
+     * Set a custom embedding provider (OpenAI, Cohere, etc.).
+     * If not set, a built-in TF-IDF provider is used as fallback.
+     */
+    setEmbeddingProvider(provider: EmbeddingProvider): void;
+    /**
+     * Register a single skill
+     */
+    register(skill: SkillDefinition): void;
+    /**
+     * Register multiple skills
+     */
+    registerAll(skills: SkillDefinition[]): void;
+    /**
+     * Get a single skill by name
+     */
+    get(name: string): SkillDefinition | undefined;
+    /**
+     * Get a single skill by name (throws if not found)
+     */
+    getRequired(name: string): SkillDefinition;
+    /**
+     * Get selective skill content — only the sections an agent needs.
+     * This prevents dumping entire SKILL.md files into the LLM context.
+     *
+     * @example
+     * // Get only the error handling section, max 500 tokens
+     * registry.getSkillContent('postgres-query-operations', {
+     *   sections: ['Error Handling'],
+     *   maxTokens: 500,
+     * })
+     */
+    getSkillContent(name: string, options?: SkillContentOptions): string | null;
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load.
+     */
+    getSkillSections(name: string): Array<{
+        path: string;
+        level: number;
+        tokenEstimate: number;
+    }> | null;
+    /**
+     * List all skills (Level 1 discovery — minimal context)
+     */
+    list(): SkillSummary[];
+    /**
+     * Search skills by keyword, category, difficulty, etc.
+     *
+     * When `options.semantic` is true, uses embedding-based similarity ranking
+     * instead of substring matching. Falls back to built-in TF-IDF if no
+     * external embedding provider is configured.
+     */
+    search(options?: SearchSkillsOptions): SkillSummary[];
+    /**
+     * Semantic search with relevance scores.
+     * Returns ranked results with cosine similarity scores.
+     *
+     * @example
+     * const results = await registry.semanticSearch('How do I handle Postgres connection pooling?');
+     * // → [{ skill: { name: 'postgres-query-operations', ... }, score: 0.82 }]
+     */
+    semanticSearch(query: string, options?: {
+        limit?: number;
+        minScore?: number;
+    }): Promise<SemanticSearchResult[]>;
+    /**
+     * Get all skills (full definitions)
+     */
+    getAll(): SkillDefinition[];
+    /**
+     * Check if a skill exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get the count of registered skills
+     */
+    count(): number;
+    /**
+     * Clear all skills
+     */
+    clear(): void;
+    /**
+     * Remove a skill
+     */
+    remove(name: string): boolean;
+    /**
+     * Ensure embeddings are computed and up-to-date.
+     */
+    private ensureEmbeddings;
+    /**
+     * Synchronous ranking using TF-IDF (for the non-async search() method).
+     */
+    private rankBySimilarity;
+    /**
+     * Get or create the default TF-IDF provider.
+     */
+    private defaultProvider;
+    private getDefaultProvider;
+    /**
+     * Convert a skill into a searchable text string for embedding.
+     */
+    private skillToText;
+}
+//# sourceMappingURL=skill-registry.d.ts.map

package/packages/core/dist/core/skill-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.d.ts","sourceRoot":"","sources":["../../src/core/skill-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAOjB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,MAAM,CAAsC;IAEpD,uDAAuD;IACvD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,6CAA6C;IAC7C,OAAO,CAAC,UAAU,CAA+B;IACjD,yCAAyC;IACzC,OAAO,CAAC,eAAe,CAAQ;IAC/B,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAyC;IAE9D;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAMvD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAetC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAM5C;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI9C;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAQ1C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI;IAM3E;;;OAGG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAMvE;;OAEG;IACH,IAAI,IAAI,YAAY,EAAE;IAWtB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,EAAE;IAmEzD;;;;;;;OAOG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAClD,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAgClC;;OAEG;IACH,MAAM,IAAI,eAAe,EAAE;IAI3B;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAS7B;;OAEG;YACW,gBAAgB;IAwB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;OAEG;IACH,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,WAAW;CAOpB"}