@matimo/core 0.1.3 → 0.1.4

package/tools/matimo_validate_skill/matimo_validate_skill.js

@@ -0,0 +1,94 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger } from '@matimo/core';
+import { parseSkillContent, validateFrontmatter, listBundledResources, } from '../shared/skill-validation.js';
+/**
+ * Validate an existing skill against the Agent Skills specification.
+ *
+ * Checks:
+ * - SKILL.md exists
+ * - YAML frontmatter is present and valid
+ * - Name follows spec rules (lowercase, hyphens, max 64 chars)
+ * - Name matches directory name
+ * - Description is present and within limits
+ * - Optional fields follow constraints
+ * - Lists bundled resources for review
+ *
+ * @see https://agentskills.io/specification
+ */
+export default async function matimoValidateSkill(params) {
+    const logger = getGlobalMatimoLogger();
+    const skillsDir = params.skills_dir || './matimo-tools/skills';
+    const failResult = (message, issues = []) => ({
+        valid: false,
+        name: params.name || '',
+        issues,
+        structure: { has_skill_md: false, resources: { scripts: [], references: [], assets: [], other: [] } },
+        message,
+    });
+    if (!params.name || params.name.trim().length === 0) {
+        return failResult('Skill name is required');
+    }
+    const skillDir = path.join(skillsDir, params.name);
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    // Check directory exists
+    if (!fs.existsSync(skillDir)) {
+        return failResult(`Skill directory not found: ${skillDir}`);
+    }
+    // Check SKILL.md exists
+    if (!fs.existsSync(skillPath)) {
+        return failResult(`SKILL.md not found in ${skillDir}`, [
+            { field: 'SKILL.md', message: 'Required SKILL.md file is missing', severity: 'error' },
+        ]);
+    }
+    // Parse content
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const parseResult = parseSkillContent(content);
+    if (!parseResult.success) {
+        return failResult(parseResult.error, [
+            { field: 'frontmatter', message: parseResult.error, severity: 'error' },
+        ]);
+    }
+    const { frontmatter, body } = parseResult.parsed;
+    // Validate frontmatter (with directory name matching)
+    const fmResult = validateFrontmatter(frontmatter, params.name);
+    // Add warnings for best practices
+    const allIssues = [...fmResult.issues];
+    // Warn if body is empty
+    if (!body || body.trim().length === 0) {
+        allIssues.push({
+            field: 'body',
+            message: 'SKILL.md has no instructions body — add content after the frontmatter',
+            severity: 'warning',
+        });
+    }
+    // Warn if body is too long (spec recommends < 5000 tokens ≈ < 500 lines)
+    const lineCount = body.split('\n').length;
+    if (lineCount > 500) {
+        allIssues.push({
+            field: 'body',
+            message: `SKILL.md body has ${lineCount} lines — spec recommends < 500 lines. Consider splitting into referenced files.`,
+            severity: 'warning',
+        });
+    }
+    // List bundled resources
+    const resources = listBundledResources(skillDir);
+    const valid = allIssues.filter(i => i.severity === 'error').length === 0;
+    logger.info('matimo_validate_skill: validation complete', {
+        name: params.name,
+        valid,
+        issueCount: allIssues.length,
+    });
+    return {
+        valid,
+        name: params.name,
+        issues: allIssues,
+        structure: {
+            has_skill_md: true,
+            resources,
+        },
+        message: valid
+            ? `Skill "${params.name}" is valid per the Agent Skills specification.`
+            : `Skill "${params.name}" has ${allIssues.filter(i => i.severity === 'error').length} error(s).`,
+    };
+}

package/tools/matimo_validate_tool/definition.yaml

@@ -15,7 +15,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_validate_tool.ts'
+  code: './matimo_validate_tool.js'
 
 output_schema:
   type: object

package/tools/matimo_validate_tool/matimo_validate_tool.js

@@ -0,0 +1,134 @@
+import yaml from 'js-yaml';
+import { validateToolDefinition, validateToolContent, classifyRisk, getGlobalMatimoLogger, } from '@matimo/core';
+const EXECUTION_TYPE_OPTIONS = ['command', 'http', 'function'];
+const PARAMETER_TYPE_OPTIONS = ['string', 'number', 'boolean', 'array', 'object'];
+const HTTP_METHOD_OPTIONS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+const AUTH_TYPE_OPTIONS = ['api_key', 'basic', 'bearer', 'oauth2', 'custom'];
+const STATUS_OPTIONS = ['draft', 'approved', 'deprecated'];
+/**
+ * Map known field paths to valid option sets so agents get actionable errors.
+ */
+const VALID_OPTIONS_BY_PATH = {
+    'execution.type': EXECUTION_TYPE_OPTIONS,
+    'execution.method': HTTP_METHOD_OPTIONS,
+    'authentication.type': AUTH_TYPE_OPTIONS,
+    status: STATUS_OPTIONS,
+};
+const PARAMETER_TYPE_PATTERN = /^parameters\.[^.]+\.type$/;
+const PARAMETER_ENCODING_BACKOFF = /^error_handling\.backoff_type$/;
+function getValidOptions(fieldPath) {
+    if (VALID_OPTIONS_BY_PATH[fieldPath])
+        return VALID_OPTIONS_BY_PATH[fieldPath];
+    if (PARAMETER_TYPE_PATTERN.test(fieldPath))
+        return PARAMETER_TYPE_OPTIONS;
+    if (PARAMETER_ENCODING_BACKOFF.test(fieldPath))
+        return ['linear', 'exponential'];
+    return undefined;
+}
+/**
+ * Convert a raw Zod issue into a human-readable SchemaError.
+ * Handles the most common patterns: missing fields, invalid enums,
+ * invalid discriminated union (execution.type).
+ */
+function formatZodIssue(issue) {
+    const fieldPath = issue.path.length > 0 ? issue.path.join('.') : 'root';
+    const validOptions = getValidOptions(fieldPath);
+    let message;
+    switch (issue.code) {
+        case 'invalid_type':
+            if (issue.received === 'undefined') {
+                message = `Missing required field: \`${fieldPath}\``;
+                if (validOptions) {
+                    message += ` — must be one of: ${validOptions.map((v) => `'${v}'`).join(', ')}`;
+                }
+            }
+            else {
+                message = `Invalid type for \`${fieldPath}\`: expected ${issue.expected ?? 'unknown'}, got ${issue.received ?? 'unknown'}`;
+            }
+            break;
+        case 'invalid_literal':
+        case 'invalid_enum_value':
+            message = `Invalid value for \`${fieldPath}\``;
+            if (validOptions) {
+                message += ` — must be one of: ${validOptions.map((v) => `'${v}'`).join(', ')}`;
+            }
+            else {
+                message += ` (${issue.message})`;
+            }
+            break;
+        case 'invalid_union':
+            // Discriminated union failure — most commonly execution.type
+            message = `Invalid value for \`${fieldPath}\``;
+            if (fieldPath === 'execution' || fieldPath === 'root') {
+                message = `Missing or invalid \`execution.type\` — must be one of: ${EXECUTION_TYPE_OPTIONS.map((v) => `'${v}'`).join(', ')}`;
+                return { field: 'execution.type', message, validOptions: EXECUTION_TYPE_OPTIONS };
+            }
+            if (validOptions) {
+                message += ` — must be one of: ${validOptions.map((v) => `'${v}'`).join(', ')}`;
+            }
+            else {
+                message += ` (${issue.message})`;
+            }
+            break;
+        default:
+            message = `\`${fieldPath}\`: ${issue.message}`;
+    }
+    return { field: fieldPath, message, ...(validOptions ? { validOptions } : {}) };
+}
+export default async function matimoValidateTool(params) {
+    const logger = getGlobalMatimoLogger();
+    const result = {
+        valid: true,
+        schemaErrors: [],
+        policyViolations: [],
+        riskLevel: 'low',
+    };
+    // Step 1: Parse YAML
+    let parsed;
+    try {
+        parsed = yaml.load(params.yaml_content);
+    }
+    catch (err) {
+        result.valid = false;
+        result.schemaErrors.push({
+            field: 'root',
+            message: `YAML parse error: ${err.message}`,
+        });
+        logger.warn('matimo_validate_tool: YAML parse failed', { error: err.message });
+        return result;
+    }
+    // Step 2: Validate against ToolDefinition schema
+    let tool;
+    try {
+        tool = validateToolDefinition(parsed);
+    }
+    catch (err) {
+        result.valid = false;
+        // MatimoError carries raw Zod issues in details.issues — use them for structured output
+        const matimoErr = err;
+        const rawIssues = matimoErr.details?.issues;
+        if (Array.isArray(rawIssues) && rawIssues.length > 0) {
+            result.schemaErrors = rawIssues.map(formatZodIssue);
+        }
+        else {
+            result.schemaErrors.push({ field: 'root', message: err.message });
+        }
+        logger.warn('matimo_validate_tool: schema validation failed', {
+            errorCount: result.schemaErrors.length,
+        });
+        return result;
+    }
+    // Step 3: Run content validator (as untrusted source)
+    const validation = validateToolContent(tool, { source: 'untrusted' });
+    if (!validation.valid) {
+        result.valid = false;
+        result.policyViolations = validation.violations.map((v) => ({
+            rule: v.rule,
+            severity: v.severity,
+            message: v.message,
+        }));
+    }
+    // Step 4: Classify risk
+    result.riskLevel = classifyRisk(tool);
+    return result;
+}

package/tools/read/definition.yaml

@@ -37,7 +37,7 @@ parameters:
 
 execution:
   type: function
-  code: './read.ts'
+  code: './read.js'
 
 output_schema:
   type: object

package/tools/read/read.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Read Tool - Read file contents with line range support
+ * Function-type tool: Exports default async function
+ */
+import fs from 'fs';
+import path from 'path';
+import { MatimoError, ErrorCode } from '@matimo/core';
+/**
+ * Read file contents with optional line range
+ */
+export default async function readTool(params) {
+    const { filePath, startLine, endLine, encoding = 'utf8', maxLines = 10000 } = params;
+    // Validate required parameter
+    if (!filePath) {
+        throw new MatimoError('Missing required parameter', ErrorCode.INVALID_PARAMETER, {
+            reason: 'filePath is required',
+        });
+    }
+    // Resolve path
+    const resolvedPath = filePath.startsWith('~')
+        ? path.join(process.env.HOME || '/', filePath.slice(1))
+        : path.isAbsolute(filePath)
+            ? filePath
+            : path.resolve(process.cwd(), filePath);
+    // Check file exists
+    if (!fs.existsSync(resolvedPath)) {
+        throw new MatimoError('File not found', ErrorCode.FILE_NOT_FOUND, {
+            filePath: resolvedPath,
+        });
+    }
+    // Get file stats
+    const stats = fs.statSync(resolvedPath);
+    if (!stats.isFile()) {
+        throw new MatimoError('Not a file', ErrorCode.EXECUTION_FAILED, {
+            filePath: resolvedPath,
+            reason: 'Path exists but is not a file',
+        });
+    }
+    if (stats.size > 50 * 1024 * 1024) {
+        throw new MatimoError('File too large', ErrorCode.EXECUTION_FAILED, {
+            filePath: resolvedPath,
+            size: stats.size,
+            maxSize: 50 * 1024 * 1024,
+        });
+    }
+    // Read file
+    const content = fs.readFileSync(resolvedPath, encoding);
+    const lines = content.split('\n');
+    // Check line count
+    if (lines.length > maxLines) {
+        throw new MatimoError('File exceeds maxLines limit', ErrorCode.EXECUTION_FAILED, {
+            filePath: resolvedPath,
+            lineCount: lines.length,
+            maxLines,
+        });
+    }
+    // Handle line range request
+    let readContent = content;
+    let readLines = lines.length;
+    const linesRequested = {};
+    if (startLine !== undefined || endLine !== undefined) {
+        const start = Math.max(0, (startLine || 1) - 1); // Convert to 0-based
+        const end = Math.min(lines.length, (endLine || lines.length)); // Convert to 0-based exclusive
+        readContent = lines.slice(start, end).join('\n');
+        readLines = end - start;
+        linesRequested.start = startLine;
+        linesRequested.end = endLine;
+    }
+    const result = {
+        success: true,
+        filePath: resolvedPath,
+        content: readContent,
+        encoding,
+        readLines,
+        lineCount: lines.length,
+        linesRequested: Object.keys(linesRequested).length > 0 ? linesRequested : undefined,
+        size: stats.size,
+        mtime: stats.mtime.toISOString(),
+    };
+    return result;
+}

package/tools/search/definition.yaml

@@ -54,7 +54,7 @@ parameters:
 
 execution:
   type: function
-  code: './search.ts'
+  code: './search.js'
 
 output_schema:
   type: object

package/tools/search/search.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Search Tool - Search files with native Node.js fs and regex
+ * Function-type tool: Exports default async function
+ */
+import fs from 'fs';
+import path from 'path';
+import { glob } from 'glob';
+import { MatimoError, ErrorCode, getGlobalMatimoLogger } from '@matimo/core';
+/**
+ * Search files for pattern matches
+ */
+export default async function searchTool(params) {
+    const logger = getGlobalMatimoLogger();
+    const { query, directory = '.', filePattern = '**/*', isRegex = false, caseSensitive = false, maxResults = 50, contextLines = 2, } = params;
+    const excludePatterns = params.excludePatterns;
+    const startTime = Date.now();
+    logger.debug('Search tool invoked', {
+        query: query.substring(0, 100),
+        directory,
+        isRegex,
+        caseSensitive,
+        maxResults,
+    });
+    // Validate required parameter
+    if (!query) {
+        logger.error('Search tool: Missing required parameter', {
+            reason: 'query is required',
+        });
+        throw new MatimoError('Missing required parameter', ErrorCode.INVALID_PARAMETER, {
+            reason: 'query is required',
+        });
+    }
+    // Resolve directory
+    const resolvedDir = directory.startsWith('~')
+        ? path.join(process.env.HOME || '/', directory.slice(1))
+        : path.isAbsolute(directory)
+            ? directory
+            : path.resolve(process.cwd(), directory);
+    if (!fs.existsSync(resolvedDir)) {
+        logger.error('Search tool: Directory not found', {
+            directory: resolvedDir,
+        });
+        throw new MatimoError('Directory not found', ErrorCode.FILE_NOT_FOUND, {
+            directory: resolvedDir,
+        });
+    }
+    // Build search pattern
+    let searchRegex;
+    try {
+        if (isRegex) {
+            searchRegex = new RegExp(query, caseSensitive ? 'g' : 'gi');
+        }
+        else {
+            const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            searchRegex = new RegExp(escapedQuery, caseSensitive ? 'g' : 'gi');
+        }
+    }
+    catch {
+        throw new MatimoError('Invalid regex pattern', ErrorCode.INVALID_PARAMETER, {
+            pattern: query,
+            isRegex,
+        });
+    }
+    // Enforce max results cap
+    const safeMaxResults = Math.min(maxResults, 1000);
+    // Find files matching pattern
+    const globPattern = path.join(resolvedDir, filePattern);
+    let files = [];
+    try {
+        const globOptions = {
+            nodir: true,
+            absolute: true,
+        };
+        if (excludePatterns && excludePatterns.length > 0) {
+            globOptions.ignore = excludePatterns;
+        }
+        files = await glob(globPattern, globOptions);
+    }
+    catch {
+        throw new MatimoError('Invalid glob pattern', ErrorCode.INVALID_PARAMETER, {
+            pattern: filePattern,
+            baseDirectory: resolvedDir,
+        });
+    }
+    const matches = [];
+    let filesSearched = 0;
+    // Search each file
+    for (const filePath of files) {
+        if (matches.length >= safeMaxResults)
+            break;
+        try {
+            // Skip binary files
+            const stats = fs.statSync(filePath);
+            if (stats.size > 5 * 1024 * 1024)
+                continue; // Skip files > 5MB
+            filesSearched++;
+            const content = fs.readFileSync(filePath, 'utf8');
+            const lines = content.split('\n');
+            for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+                if (matches.length >= safeMaxResults)
+                    break;
+                const line = lines[lineNum];
+                const lineContent = line.trim();
+                const match = searchRegex.exec(line);
+                if (match) {
+                    // Get context lines
+                    const contextStart = Math.max(0, lineNum - contextLines);
+                    const contextEnd = Math.min(lines.length, lineNum + contextLines + 1);
+                    const context = lines.slice(contextStart, contextEnd);
+                    matches.push({
+                        filePath,
+                        lineNumber: lineNum + 1,
+                        lineContent,
+                        matchIndex: match.index,
+                        context,
+                    });
+                    // Reset regex for next exec
+                    searchRegex.lastIndex = 0;
+                }
+            }
+        }
+        catch {
+            // Skip files that can't be read
+            continue;
+        }
+    }
+    const result = {
+        success: true,
+        query,
+        directory: resolvedDir,
+        pattern: filePattern,
+        matches,
+        totalMatches: matches.length,
+        filesSearched,
+        duration: Date.now() - startTime,
+        truncated: matches.length >= safeMaxResults && files.length > filesSearched,
+    };
+    return result;
+}