@matimo/core 0.1.0-alpha.8 → 0.1.0

package/tools/matimo_get_tool_status/matimo_get_tool_status.ts

@@ -0,0 +1,101 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import {
+  validateToolDefinition,
+  classifyRisk,
+  getTierForTool,
+  ApprovalManifest,
+  getGlobalMatimoLogger,
+} from '@matimo/core';
+
+interface StatusParams {
+  name: string;
+  tool_dir?: string;
+}
+
+interface StatusResult {
+  found: boolean;
+  name?: string;
+  status?: string;
+  riskLevel?: string;
+  approvalState?: 'pending' | 'auto-approved' | 'approved' | 'rejected';
+  approvedAt?: string;
+  approvedBy?: string;
+  message: string;
+}
+
+export default async function matimoGetToolStatus(
+  params: StatusParams,
+  context?: { credentials?: Record<string, string> },
+): Promise<StatusResult> {
+  const logger = getGlobalMatimoLogger();
+  const toolDir = params.tool_dir || './matimo-tools';
+
+  const defPath = path.join(toolDir, params.name, 'definition.yaml');
+  if (!fs.existsSync(defPath)) {
+    logger.warn('matimo_get_tool_status: tool not found', { name: params.name, path: defPath });
+    return { found: false, message: `Tool "${params.name}" not found at ${defPath}` };
+  }
+
+  const yamlContent = fs.readFileSync(defPath, 'utf-8');
+
+  let tool;
+  try {
+    const parsed = yaml.load(yamlContent);
+    tool = validateToolDefinition(parsed);
+  } catch (err) {
+    return {
+      found: true,
+      name: params.name,
+      message: `Tool YAML is invalid: ${(err as Error).message}`,
+    };
+  }
+
+  const riskLevel = classifyRisk(tool);
+  const tier = getTierForTool(tool);
+
+  // Determine approval state from manifest
+  const approvalDir = path.resolve(toolDir);
+  const manifest = new ApprovalManifest(
+    approvalDir,
+    context?.credentials?.MATIMO_APPROVAL_SECRET,
+  );
+
+  const hash = manifest.computeHash(yamlContent);
+  const approvalRecord = manifest.getApproval(params.name);
+  const isApproved = approvalRecord ? manifest.isApproved(params.name, hash) : false;
+  const pendingTools = manifest.getPendingTools();
+
+  let approvalState: StatusResult['approvalState'];
+  if (tool.status === 'deprecated') {
+    approvalState = 'rejected';
+  } else if (isApproved) {
+    approvalState = 'approved';
+  } else if (tier === 'auto') {
+    approvalState = 'auto-approved';
+  } else if (pendingTools.includes(params.name)) {
+    approvalState = 'pending';
+  } else {
+    // Tool exists on disk but no pending record and not approved — treat as pending
+    approvalState = 'pending';
+  }
+
+  logger.debug('matimo_get_tool_status: status retrieved', {
+    name: params.name,
+    status: tool.status,
+    riskLevel,
+    approvalState,
+  });
+
+  return {
+    found: true,
+    name: params.name,
+    status: tool.status ?? 'draft',
+    riskLevel,
+    approvalState,
+    approvedAt: approvalRecord?.approvedAt,
+    approvedBy: approvalRecord?.approvedBy,
+    message: `Tool "${params.name}" is ${approvalState} (${riskLevel} risk)`,
+  };
+}

package/tools/matimo_list_skills/definition.yaml

@@ -0,0 +1,52 @@
+name: matimo_list_skills
+version: '1.0.0'
+description: >-
+  Level 1 metadata discovery — list all skills available to the system.
+  
+  Skills are auto-discovered in this order (priority):
+  1. From global Matimo instance (if initialized)
+  2. From @matimo/* packages in node_modules (auto-discovery like tools)
+  3. From core skills bundled with @matimo/core
+  4. From optional explicit skills_dir (if provided)
+  
+  Returns each skill's name, description, and optional frontmatter fields
+  (license, compatibility, metadata) per the Agent Skills specification.
+
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - skill
+  - discovery
+
+parameters:
+  skills_dir:
+    type: string
+    required: false
+    description: >-
+      Optional directory to scan for skills. If provided, loads skills directly
+      from this path (each skill is a subdirectory containing a SKILL.md file
+      with YAML frontmatter).
+      
+      Paths are resolved relative to the current working directory where the tool
+      is executed. For reliability, use absolute paths or verify relative paths
+      are correct from the execution context.
+      
+      If not provided, returns skills from the global Matimo instance with
+      auto-discovered @matimo/*/skills and user-created skills.
+
+execution:
+  type: function
+  code: './matimo_list_skills.ts'
+
+output_schema:
+  type: object
+  properties:
+    skills:
+      type: array
+      description: >-
+        List of discovered skills with name, description, path, and optional
+        fields (license, compatibility, metadata)
+    total:
+      type: number
+      description: Total number of skills found

package/tools/matimo_list_skills/matimo_list_skills.ts

@@ -0,0 +1,138 @@
+import path from 'path';
+import fs from 'fs';
+import { getGlobalMatimoLogger, getGlobalMatimoInstance, extractSkillMetadata, ToolLoader } from '@matimo/core';
+
+interface ListSkillsParams {
+  skills_dir?: string;
+}
+
+interface SkillSummary {
+  name: string;
+  description: string;
+  version?: string;
+  license?: string;
+  metadata?: Record<string, string>;
+  source: 'builtin' | 'user' | 'catalog';
+}
+
+interface ListSkillsResult {
+  skills: SkillSummary[];
+  total: number;
+}
+
+/**
+ * Helper: Load SKILL.md files from a directory and extract metadata.
+ */
+function loadSkillsFromPath(
+  skillsPath: string,
+  source: 'builtin' | 'user',
+  logger: ReturnType<typeof getGlobalMatimoLogger>,
+): SkillSummary[] {
+  const skills: SkillSummary[] = [];
+
+  if (!fs.existsSync(skillsPath)) return skills;
+
+  try {
+    const entries = fs.readdirSync(skillsPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillFilePath = path.join(skillsPath, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillFilePath)) continue;
+
+      try {
+        const content = fs.readFileSync(skillFilePath, 'utf-8');
+        const result = extractSkillMetadata(content, source);
+        if (result.success && result.metadata) {
+          skills.push(result.metadata);
+        }
+      } catch (err) {
+        logger.debug('matimo_list_skills: failed to extract metadata', {
+          skill: entry.name,
+          error: (err as Error).message,
+        });
+      }
+    }
+  } catch (err) {
+    logger.debug('matimo_list_skills: failed to read directory', {
+      path: skillsPath,
+      error: (err as Error).message,
+    });
+  }
+
+  return skills;
+}
+
+
+
+/**
+ * List all skills available in the current Matimo instance.
+ *
+ * Skills are discovered in this order (priority):
+ * 1. Global MatimoInstance (if initialized) — includes auto-discovered @matimo/* skills
+ * 2. Auto-discover from @matimo/* packages in node_modules (like tools do)
+ * 3. Explicit skills_dir if provided
+ *
+ * Returns METADATA ONLY: name, description, license, version, metadata, source.
+ * Full body content is available via matimo_get_skill when explicitly requested.
+ *
+ * Uses lightweight YAML-only extraction (no body/sections parsing) for efficiency.
+ * This avoids the overhead of parsing skill markdown sections and keeps responses small.
+ */
+export default async function matimoListSkills(
+  params: ListSkillsParams,
+): Promise<ListSkillsResult> {
+  const logger = getGlobalMatimoLogger();
+  const allSkills = new Map<string, SkillSummary>();
+
+  try {
+    // Try global MatimoInstance first
+    try {
+      const matimo = getGlobalMatimoInstance();
+      if (matimo) {
+        const matimoSkills = matimo.listSkills();
+        if (matimoSkills?.length > 0) {
+          logger.debug('matimo_list_skills: from MatimoInstance', { count: matimoSkills.length });
+          matimoSkills.forEach((s) => allSkills.set(s.name, s));
+          return { skills: Array.from(allSkills.values()), total: allSkills.size };
+        }
+      }
+    } catch (err) {
+      logger.debug('matimo_list_skills: MatimoInstance unavailable', {
+        error: (err as Error).message,
+      });
+    }
+
+    // Auto-discover from @matimo/* packages
+    try {
+      const toolLoader = new ToolLoader();
+      const discoveredPaths = toolLoader.autoDiscoverPackages();
+
+      for (const toolPath of discoveredPaths) {
+        const pkgDir = path.dirname(toolPath);
+        const skillsPath = path.join(pkgDir, 'skills');
+        const discovered = loadSkillsFromPath(skillsPath, 'builtin', logger);
+        discovered.forEach((s) => allSkills.set(s.name, s));
+      }
+    } catch (err) {
+      logger.debug('matimo_list_skills: auto-discovery failed', {
+        error: (err as Error).message,
+      });
+    }
+
+    // Load from explicit skills_dir if provided
+    if (params.skills_dir) {
+      const skillsDir = path.resolve(params.skills_dir);
+      const discovered = loadSkillsFromPath(skillsDir, 'user', logger);
+      discovered.forEach((s) => allSkills.set(s.name, s));
+    }
+
+    const results = Array.from(allSkills.values());
+    logger.debug('matimo_list_skills: complete', { total: results.length });
+    return { skills: results, total: results.length };
+  } catch (err) {
+    logger.error('matimo_list_skills: failed', {
+      error: (err as Error).message,
+    });
+    return { skills: [], total: 0 };
+  }
+}

package/tools/matimo_list_user_tools/definition.yaml

@@ -0,0 +1,32 @@
+name: matimo_list_user_tools
+version: '1.0.0'
+description: List all user-created tools in a directory with risk classification, approval status, and metadata.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - discovery
+
+parameters:
+  tool_dir:
+    type: string
+    required: false
+    description: Directory to scan for tools (default ./matimo-tools)
+  include_drafts:
+    type: boolean
+    required: false
+    description: Whether to include draft tools in the listing (default true)
+
+execution:
+  type: function
+  code: './matimo_list_user_tools.ts'
+
+output_schema:
+  type: object
+  properties:
+    tools:
+      type: array
+      description: List of discovered tools
+    total:
+      type: number
+      description: Total number of tools found

package/tools/matimo_list_user_tools/matimo_list_user_tools.ts

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import {
+  validateToolDefinition,
+  classifyRisk,
+  getGlobalMatimoLogger,
+} from '@matimo/core';
+
+interface ListParams {
+  tool_dir?: string;
+  include_drafts?: boolean;
+}
+
+interface ToolSummary {
+  name: string;
+  description: string;
+  version: string;
+  status: string;
+  riskLevel: string;
+  tags: string[];
+}
+
+interface ListResult {
+  tools: ToolSummary[];
+  total: number;
+}
+
+export default async function matimoListUserTools(
+  params: ListParams,
+): Promise<ListResult> {
+  const logger = getGlobalMatimoLogger();
+  const toolDir = params.tool_dir || './matimo-tools';
+  const includeDrafts = params.include_drafts !== false;
+
+  const tools: ToolSummary[] = [];
+
+  if (!fs.existsSync(toolDir)) {
+    return { tools: [], total: 0 };
+  }
+
+  const entries = fs.readdirSync(toolDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const defPath = path.join(toolDir, entry.name, 'definition.yaml');
+    if (!fs.existsSync(defPath)) continue;
+
+    try {
+      const content = fs.readFileSync(defPath, 'utf-8');
+      const parsed = yaml.load(content);
+      const tool = validateToolDefinition(parsed);
+
+      const status = tool.status || 'approved';
+      if (!includeDrafts && status === 'draft') continue;
+
+      tools.push({
+        name: tool.name,
+        description: tool.description,
+        version: tool.version,
+        status,
+        riskLevel: classifyRisk(tool),
+        tags: tool.tags || [],
+      });
+    } catch (err) {
+      logger.warn('matimo_list_user_tools: failed to parse tool', {
+        dir: entry.name,
+        error: (err as Error).message,
+      });
+    }
+  }
+
+  return { tools, total: tools.length };
+}

package/tools/matimo_reload_tools/definition.yaml

@@ -0,0 +1,35 @@
+name: matimo_reload_tools
+version: '1.0.0'
+description: >-
+  Hot-reload all tools from configured toolPaths. Clears the registry, re-reads
+  YAML definitions from disk, re-validates untrusted tools against the active
+  policy, and returns a summary of loaded, removed, revalidated, and rejected
+  tools. Use after matimo_create_tool + matimo_approve_tool to bring new tools
+  into the live registry without restarting the process.
+requires_approval: true
+tags:
+  - matimo
+  - meta
+  - lifecycle
+
+parameters: {}
+
+execution:
+  type: function
+  code: './matimo_reload_tools.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+    loaded:
+      type: number
+    removed:
+      type: number
+    revalidated:
+      type: number
+    rejected:
+      type: array
+    message:
+      type: string

package/tools/matimo_reload_tools/matimo_reload_tools.ts

@@ -0,0 +1,29 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+
+/**
+ * matimo_reload_tools — Hot-reload all tools from configured toolPaths.
+ *
+ * NOTE: This function is a placeholder. The actual reload logic is intercepted
+ * and handled directly by MatimoInstance.execute() because reloadTools() is a
+ * method on the instance itself (it clears the registry, re-reads YAML from
+ * disk, re-validates untrusted tools, etc.). The function executor cannot do
+ * this because it doesn't have a reference to the MatimoInstance.
+ *
+ * If this file is ever reached (e.g., in tests without the interception),
+ * it returns an error instructing the caller to use matimo.reloadTools() directly.
+ */
+export default async function matimoReloadTools(): Promise<{
+  success: boolean;
+  message: string;
+}> {
+  const logger = getGlobalMatimoLogger();
+  logger.warn(
+    'matimo_reload_tools: reached fallback implementation — this should be intercepted by MatimoInstance.execute()',
+  );
+
+  return {
+    success: false,
+    message:
+      'Reload must be handled by MatimoInstance. If you see this, the interception in execute() is not active.',
+  };
+}

package/tools/matimo_search_tools/definition.yaml

@@ -0,0 +1,32 @@
+name: matimo_search_tools
+version: '1.0.0'
+description: Search the loaded tool registry by keyword. Returns matching tool names, descriptions, and tags. Use to discover available tools before calling them.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - discovery
+
+parameters:
+  query:
+    type: string
+    required: true
+    description: Search keyword — matched against tool names, descriptions, and tags
+  limit:
+    type: number
+    required: false
+    description: Maximum number of results to return (default 20)
+
+execution:
+  type: function
+  code: './matimo_search_tools.ts'
+
+output_schema:
+  type: object
+  properties:
+    results:
+      type: array
+    total:
+      type: number
+    query:
+      type: string

package/tools/matimo_search_tools/matimo_search_tools.ts

@@ -0,0 +1,82 @@
+import { getGlobalMatimoInstance, getGlobalMatimoLogger, validateToolDefinition, classifyRisk } from '@matimo/core';
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+
+interface SearchParams {
+  query: string;
+  limit?: number;
+}
+
+interface ToolSummary {
+  name: string;
+  description: string;
+  version: string;
+  tags: string[];
+  riskLevel: string;
+}
+
+interface SearchResult {
+  results: ToolSummary[];
+  total: number;
+  query: string;
+}
+
+export default async function matimoSearchTools(params: SearchParams): Promise<SearchResult> {
+  const logger = getGlobalMatimoLogger();
+  const query = params.query ?? '';
+  const limit = params.limit ?? 20;
+
+  const toSummary = (tool: { name: string; description: string; version: string; tags?: string[] }): ToolSummary => ({
+    name: tool.name,
+    description: tool.description,
+    version: tool.version,
+    tags: tool.tags ?? [],
+    riskLevel: classifyRisk(tool as Parameters<typeof classifyRisk>[0]),
+  });
+
+  // Prefer registry search via the global instance (has all loaded tools)
+  try {
+    const instance = getGlobalMatimoInstance();
+    const found = instance.searchTools(query).slice(0, limit);
+    logger.debug('matimo_search_tools: registry search', { query, count: found.length });
+    return {
+      results: found.map(toSummary),
+      total: found.length,
+      query,
+    };
+  } catch {
+    // Global instance not set — fall through to disk-based scan below
+    logger.debug('matimo_search_tools: no global instance, falling back to disk scan');
+  }
+
+  // Fallback: scan the default tools directory
+  const toolDir = './matimo-tools';
+  if (!fs.existsSync(toolDir)) {
+    return { results: [], total: 0, query };
+  }
+
+  const lowerQuery = query.toLowerCase();
+  const results: ToolSummary[] = [];
+
+  for (const entry of fs.readdirSync(toolDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const defPath = path.join(toolDir, entry.name, 'definition.yaml');
+    if (!fs.existsSync(defPath)) continue;
+
+    try {
+      const tool = validateToolDefinition(yaml.load(fs.readFileSync(defPath, 'utf-8')));
+      const matches =
+        tool.name.toLowerCase().includes(lowerQuery) ||
+        tool.description.toLowerCase().includes(lowerQuery) ||
+        (tool.tags ?? []).some((t) => t.toLowerCase().includes(lowerQuery));
+
+      if (matches) results.push(toSummary(tool));
+    } catch {
+      // Skip invalid definitions silently
+    }
+    if (results.length >= limit) break;
+  }
+
+  return { results, total: results.length, query };
+}

package/tools/matimo_validate_skill/definition.yaml

@@ -0,0 +1,43 @@
+name: matimo_validate_skill
+version: '1.0.0'
+description: >-
+  Validate an existing skill against the Agent Skills specification
+  (https://agentskills.io/specification). Checks SKILL.md frontmatter, naming
+  rules, directory structure, and best practices.
+requires_approval: false
+tags:
+  - matimo
+  - meta
+  - skill
+  - validation
+
+parameters:
+  name:
+    type: string
+    required: true
+    description: Name of the skill directory to validate
+  skills_dir:
+    type: string
+    required: false
+    description: Directory containing skills (default ./matimo-tools/skills)
+
+execution:
+  type: function
+  code: './matimo_validate_skill.ts'
+
+output_schema:
+  type: object
+  properties:
+    valid:
+      type: boolean
+      description: Whether the skill passes all validation checks
+    name:
+      type: string
+    issues:
+      type: array
+      description: List of validation issues (errors and warnings)
+    structure:
+      type: object
+      description: Skill directory structure analysis
+    message:
+      type: string