@matimo/core 0.1.0-alpha.9 → 0.1.0

package/tools/matimo_validate_skill/matimo_validate_skill.ts

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger } from '@matimo/core';
+import {
+  parseSkillContent,
+  validateFrontmatter,
+  listBundledResources,
+  type ValidationIssue,
+  type BundledResources,
+} from '../shared/skill-validation';
+
+interface ValidateSkillParams {
+  /** Name of the skill directory to validate. */
+  name: string;
+  /** Directory containing skills (default ./matimo-tools/skills). */
+  skills_dir?: string;
+}
+
+interface ValidateSkillResult {
+  valid: boolean;
+  name: string;
+  issues: ValidationIssue[];
+  structure: {
+    has_skill_md: boolean;
+    resources: BundledResources;
+  };
+  message: string;
+}
+
+/**
+ * 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: ValidateSkillParams,
+): Promise<ValidateSkillResult> {
+  const logger = getGlobalMatimoLogger();
+  const skillsDir = params.skills_dir || './matimo-tools/skills';
+
+  const failResult = (message: string, issues: ValidationIssue[] = []): ValidateSkillResult => ({
+    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

@@ -0,0 +1,34 @@
+name: matimo_validate_tool
+version: '1.0.0'
+description: Validate a tool definition YAML string against the Matimo schema and policy rules. Returns schema errors, policy violations, and risk classification.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - validation
+
+parameters:
+  yaml_content:
+    type: string
+    required: true
+    description: The YAML content of the tool definition to validate
+
+execution:
+  type: function
+  code: './matimo_validate_tool.ts'
+
+output_schema:
+  type: object
+  properties:
+    valid:
+      type: boolean
+      description: Whether the tool definition is valid
+    schemaErrors:
+      type: array
+      description: Schema validation errors (if any)
+    policyViolations:
+      type: array
+      description: Policy violations found by content validator
+    riskLevel:
+      type: string
+      description: Risk classification (low, medium, high, critical)

package/tools/matimo_validate_tool/matimo_validate_tool.ts

@@ -0,0 +1,168 @@
+import yaml from 'js-yaml';
+import {
+  validateToolDefinition,
+  validateToolContent,
+  classifyRisk,
+  getGlobalMatimoLogger,
+} from '@matimo/core';
+import type { Violation } from '@matimo/core';
+
+interface ValidateParams {
+  yaml_content: string;
+}
+
+/** Structured schema error with field path and optional valid values. */
+interface SchemaError {
+  field: string;
+  message: string;
+  validOptions?: string[];
+}
+
+interface ValidateResult {
+  valid: boolean;
+  schemaErrors: SchemaError[];
+  policyViolations: Array<{ rule: string; severity: string; message: string }>;
+  riskLevel: string;
+}
+
+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: Record<string, string[]> = {
+  '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: string): string[] | undefined {
+  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: { path: (string | number)[]; message: string; code: string; expected?: string; received?: string }): SchemaError {
+  const fieldPath = issue.path.length > 0 ? issue.path.join('.') : 'root';
+  const validOptions = getValidOptions(fieldPath);
+
+  let message: string;
+
+  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: ValidateParams,
+): Promise<ValidateResult> {
+  const logger = getGlobalMatimoLogger();
+  const result: ValidateResult = {
+    valid: true,
+    schemaErrors: [],
+    policyViolations: [],
+    riskLevel: 'low',
+  };
+
+  // Step 1: Parse YAML
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(params.yaml_content);
+  } catch (err) {
+    result.valid = false;
+    result.schemaErrors.push({
+      field: 'root',
+      message: `YAML parse error: ${(err as Error).message}`,
+    });
+    logger.warn('matimo_validate_tool: YAML parse failed', { error: (err as Error).message });
+    return result;
+  }
+
+  // Step 2: Validate against ToolDefinition schema
+  let tool: ReturnType<typeof validateToolDefinition>;
+  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 as { details?: { issues?: unknown[] }; message?: string };
+    const rawIssues = matimoErr.details?.issues;
+    if (Array.isArray(rawIssues) && rawIssues.length > 0) {
+      result.schemaErrors = (rawIssues as { path: (string | number)[]; message: string; code: string; expected?: string; received?: string }[]).map(formatZodIssue);
+    } else {
+      result.schemaErrors.push({ field: 'root', message: (err as Error).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: Violation) => ({
+      rule: v.rule,
+      severity: v.severity,
+      message: v.message,
+    }));
+  }
+
+  // Step 4: Classify risk
+  result.riskLevel = classifyRisk(tool);
+
+  return result;
+}

package/tools/shared/skill-validation.ts

@@ -0,0 +1,335 @@
+/**
+ * Shared validation utilities for Agent Skills — aligned with the official
+ * Agent Skills specification (https://agentskills.io/specification).
+ *
+ * Covers: name rules, description rules, frontmatter parsing/validation,
+ * and bundled resource discovery.
+ */
+import fs from 'fs';
+import path from 'path';
+
+// ── Name Validation ──────────────────────────────────────────────────────────
+
+/** Spec: lowercase letters, numbers, hyphens only. */
+const VALID_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/** Consecutive hyphens are not allowed. */
+const CONSECUTIVE_HYPHENS = /--/;
+
+/** Max length for skill name. */
+const MAX_NAME_LENGTH = 64;
+
+/** Max length for description. */
+const MAX_DESCRIPTION_LENGTH = 1024;
+
+/** Max length for compatibility field. */
+const MAX_COMPATIBILITY_LENGTH = 500;
+
+/** Path traversal detection — kept for defense-in-depth. */
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+
+export interface NameValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Validate a skill name against the Agent Skills spec.
+ *
+ * Rules:
+ * - 1–64 characters
+ * - Lowercase letters, numbers, hyphens only
+ * - Must not start or end with a hyphen
+ * - Must not contain consecutive hyphens (--)
+ * - Must not contain path traversal characters
+ */
+export function validateSkillName(name: string): NameValidationResult {
+  if (!name || name.trim().length === 0) {
+    return { valid: false, error: 'Skill name is required' };
+  }
+
+  if (UNSAFE_NAME_PATTERN.test(name)) {
+    return { valid: false, error: 'Skill name contains invalid characters' };
+  }
+
+  if (name.length > MAX_NAME_LENGTH) {
+    return { valid: false, error: `Skill name must be at most ${MAX_NAME_LENGTH} characters (got ${name.length})` };
+  }
+
+  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 };
+}
+
+// ── Frontmatter Parsing ──────────────────────────────────────────────────────
+
+export interface SkillFrontmatter {
+  name: string;
+  description: string;
+  license?: string;
+  compatibility?: string;
+  'allowed-tools'?: string | string[];
+  metadata?: Record<string, string>;
+}
+
+export interface ParsedSkill {
+  frontmatter: SkillFrontmatter;
+  body: string;
+  raw: string;
+}
+
+export interface ParseResult {
+  success: boolean;
+  error?: string;
+  parsed?: ParsedSkill;
+}
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ *
+ * Handles the spec's required fields (name, description) and optional fields
+ * (license, compatibility, metadata, allowed-tools).
+ */
+export function parseSkillContent(content: string): ParseResult {
+  if (!content || !content.startsWith('---')) {
+    return { success: false, error: 'Skill content must start with YAML frontmatter (---)' };
+  }
+
+  const endIndex = content.indexOf('---', 3);
+  if (endIndex === -1) {
+    return { success: false, error: 'Skill content must have closing YAML frontmatter (---)' };
+  }
+
+  const frontmatterBlock = content.substring(3, endIndex).trim();
+  const body = content.substring(endIndex + 3).trim();
+
+  // Parse frontmatter lines
+  const fields: Record<string, unknown> = {};
+  let currentMetadata: Record<string, string> | null = null;
+  let currentArray: string[] | null = null;
+  let currentArrayKey: string | null = null;
+
+  for (const line of frontmatterBlock.split('\n')) {
+    // Detect array elements (prefixed with "- ")
+    if (currentArray !== null && /^\s*- /.test(line)) {
+      const item = line.trim().substring(2).trim();
+      if (item) {
+        currentArray.push(item.replace(/^["']|["']$/g, ''));
+      }
+      continue;
+    }
+
+    // Detect metadata sub-keys (indented with spaces under "metadata:")
+    if (currentMetadata !== null && /^\s+\S/.test(line)) {
+      const colonIndex = line.indexOf(':');
+      if (colonIndex !== -1) {
+        const key = line.substring(0, colonIndex).trim();
+        const value = line.substring(colonIndex + 1).trim();
+        if (key && value) {
+          currentMetadata[key] = value.replace(/^["']|["']$/g, '');
+        }
+      }
+      continue;
+    }
+
+    // Top-level keys
+    currentMetadata = null;
+    currentArray = null;
+    currentArrayKey = null;
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    const value = line.substring(colonIndex + 1).trim();
+
+    if (key === 'metadata' && !value) {
+      // Start collecting metadata sub-keys
+      currentMetadata = {};
+      fields['__metadata__'] = 'MAP';
+      continue;
+    }
+
+    // Check for array start (value is empty, array items follow on next lines)
+    if (key === 'allowed-tools' && !value) {
+      currentArray = [];
+      currentArrayKey = 'allowed-tools';
+      continue;
+    }
+
+    if (key && value) {
+      // Strip surrounding quotes (YAML style)
+      fields[key] = value.replace(/^["']|["']$/g, '');
+    }
+  }
+
+  // Store any pending array
+  if (currentArray !== null && currentArrayKey) {
+    fields[currentArrayKey] = currentArray;
+  }
+
+  // Build frontmatter object
+  const frontmatter: SkillFrontmatter = {
+    name: fields.name as string || '',
+    description: fields.description as string || '',
+  };
+
+  if (fields.license) frontmatter.license = fields.license as string;
+  if (fields.compatibility) frontmatter.compatibility = fields.compatibility as string;
+  if (fields['allowed-tools']) {
+    frontmatter['allowed-tools'] = Array.isArray(fields['allowed-tools'])
+      ? (fields['allowed-tools'] as string[])
+      : (fields['allowed-tools'] as string);
+  }
+  if (currentMetadata && Object.keys(currentMetadata).length > 0) {
+    frontmatter.metadata = currentMetadata;
+  }
+
+  return {
+    success: true,
+    parsed: { frontmatter, body, raw: content },
+  };
+}
+
+// ── Frontmatter Validation ───────────────────────────────────────────────────
+
+export interface ValidationIssue {
+  field: string;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+/**
+ * Validate parsed frontmatter against the Agent Skills spec.
+ *
+ * Checks: name rules, description rules, optional field constraints,
+ * and name/directory consistency (if directoryName provided).
+ */
+export function validateFrontmatter(
+  frontmatter: SkillFrontmatter,
+  directoryName?: string,
+): ValidationResult {
+  const issues: ValidationIssue[] = [];
+
+  // Required: name
+  if (!frontmatter.name) {
+    issues.push({ field: 'name', message: 'YAML frontmatter must include a "name" field', severity: 'error' });
+  } else {
+    const nameResult = validateSkillName(frontmatter.name);
+    if (!nameResult.valid) {
+      issues.push({ field: 'name', message: nameResult.error!, severity: 'error' });
+    }
+  }
+
+  // Required: description
+  if (!frontmatter.description) {
+    issues.push({ field: 'description', message: 'YAML frontmatter must include a "description" field', severity: 'error' });
+  } else if (frontmatter.description.length > MAX_DESCRIPTION_LENGTH) {
+    issues.push({
+      field: 'description',
+      message: `Description must be at most ${MAX_DESCRIPTION_LENGTH} characters (got ${frontmatter.description.length})`,
+      severity: 'error',
+    });
+  }
+
+  // Optional: compatibility
+  if (frontmatter.compatibility && frontmatter.compatibility.length > MAX_COMPATIBILITY_LENGTH) {
+    issues.push({
+      field: 'compatibility',
+      message: `Compatibility must be at most ${MAX_COMPATIBILITY_LENGTH} characters (got ${frontmatter.compatibility.length})`,
+      severity: 'error',
+    });
+  }
+
+  // name must match directory name (if provided)
+  if (directoryName && frontmatter.name && frontmatter.name !== directoryName) {
+    issues.push({
+      field: 'name',
+      message: `Skill name "${frontmatter.name}" must match its directory name "${directoryName}"`,
+      severity: 'error',
+    });
+  }
+
+  return {
+    valid: issues.filter(i => i.severity === 'error').length === 0,
+    issues,
+  };
+}
+
+// ── Bundled Resources (Level 3) ──────────────────────────────────────────────
+
+export interface BundledResources {
+  scripts: string[];
+  references: string[];
+  assets: string[];
+  other: string[];
+}
+
+/**
+ * List bundled resources in a skill directory.
+ *
+ * The spec recognizes three standard subdirectories:
+ * - scripts/   — executable code
+ * - references/ — additional documentation
+ * - assets/    — templates, resources
+ *
+ * Any other files (besides SKILL.md) are listed under "other".
+ */
+export function listBundledResources(skillDir: string): BundledResources {
+  const resources: BundledResources = {
+    scripts: [],
+    references: [],
+    assets: [],
+    other: [],
+  };
+
+  if (!fs.existsSync(skillDir)) return resources;
+
+  const KNOWN_DIRS: Record<string, keyof Pick<BundledResources, 'scripts' | 'references' | 'assets'>> = {
+    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) {
+        // List files inside the known subdirectory
+        const subDir = path.join(skillDir, entry.name);
+        const subEntries = fs.readdirSync(subDir);
+        for (const sub of subEntries) {
+          resources[category].push(`${entry.name}/${sub}`);
+        }
+      } else {
+        // Unknown directory — list contents under "other"
+        const subDir = path.join(skillDir, entry.name);
+        const subEntries = fs.readdirSync(subDir);
+        for (const sub of subEntries) {
+          resources.other.push(`${entry.name}/${sub}`);
+        }
+      }
+    } else {
+      // Top-level file (not SKILL.md)
+      resources.other.push(entry.name);
+    }
+  }
+
+  return resources;
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 tallclub
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.