@matimo/core 0.1.2 → 0.1.3

package/dist/runtime/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runtime-safe public surface for built-in tool files.
+ *
+ * Keep this entrypoint intentionally narrow to avoid coupling tools to the
+ * full package barrel and to reduce circular dependency risk.
+ */
+export { MatimoError, ErrorCode } from '../errors/matimo-error.js';
+export { getGlobalMatimoLogger } from '../logging/index.js';
+export { getGlobalApprovalHandler } from '../approval/approval-handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,10 @@
+/**
+ * Runtime-safe public surface for built-in tool files.
+ *
+ * Keep this entrypoint intentionally narrow to avoid coupling tools to the
+ * full package barrel and to reduce circular dependency risk.
+ */
+export { MatimoError, ErrorCode } from '../errors/matimo-error.js';
+export { getGlobalMatimoLogger } from '../logging/index.js';
+export { getGlobalApprovalHandler } from '../approval/approval-handler.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matimo/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Core SDK for Matimo: Framework-agnostic YAML-driven tool ecosystem for AI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "default": "./dist/mcp/index.js"

package/tools/calculator/calculator.ts

@@ -3,8 +3,7 @@
  * Pattern: Function-based tool (same as execute)
  */
 
-import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
-import { getGlobalMatimoLogger } from '../../src/logging/logger';
+import { MatimoError, ErrorCode, getGlobalMatimoLogger } from '@matimo/core/runtime';
 
 interface CalculatorParams {
   operation: string;

package/tools/execute/execute.ts

@@ -6,9 +6,12 @@
 
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
-import { getGlobalMatimoLogger } from '../../src/logging/logger';
-import { getGlobalApprovalHandler } from '../../src/approval/approval-handler';
+import {
+  MatimoError,
+  ErrorCode,
+  getGlobalMatimoLogger,
+  getGlobalApprovalHandler,
+} from '@matimo/core/runtime';
 
 const execAsync = promisify(exec);
 

package/tools/matimo_create_skill/matimo_create_skill.ts

@@ -5,7 +5,7 @@ import {
   validateSkillName,
   parseSkillContent,
   validateFrontmatter,
-} from '../shared/skill-validation';
+} from '../shared/skill-validation.js';
 
 interface CreateSkillParams {
   name: string;

package/tools/matimo_get_skill/matimo_get_skill.ts

@@ -1,7 +1,14 @@
 import fs from 'fs';
 import path from 'path';
 import { getGlobalMatimoLogger, getGlobalMatimoInstance, ToolLoader, SkillSummary } from '@matimo/core';
-import { parseSkillContent, listBundledResources, type BundledResources } from '../shared/skill-validation';
+import { parseSkillContent, listBundledResources } from '../shared/skill-validation.js';
+
+interface BundledResources {
+  scripts: string[];
+  references: string[];
+  assets: string[];
+  other: string[];
+}
 
 interface GetSkillParams {
   name: string;

package/tools/matimo_validate_skill/matimo_validate_skill.ts

@@ -5,9 +5,20 @@ import {
   parseSkillContent,
   validateFrontmatter,
   listBundledResources,
-  type ValidationIssue,
-  type BundledResources,
-} from '../shared/skill-validation';
+} from '../shared/skill-validation.js';
+
+interface ValidationIssue {
+  field: string;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+interface BundledResources {
+  scripts: string[];
+  references: string[];
+  assets: string[];
+  other: string[];
+}
 
 interface ValidateSkillParams {
   /** Name of the skill directory to validate. */

package/tools/search/search.ts

@@ -53,9 +53,10 @@ export default async function searchTool(params: SearchParams): Promise<SearchRe
     caseSensitive = false,
     maxResults = 50,
     contextLines = 2,
-    excludePatterns = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
   } = params;
 
+  const excludePatterns = params.excludePatterns;
+
   const startTime = Date.now();
 
   logger.debug('Search tool invoked', {
@@ -116,11 +117,20 @@ export default async function searchTool(params: SearchParams): Promise<SearchRe
   let files: string[] = [];
 
   try {
-    files = await glob(globPattern, {
+    const globOptions: {
+      nodir: true;
+      absolute: true;
+      ignore?: string[];
+    } = {
       nodir: true,
       absolute: true,
-      ignore: excludePatterns,
-    });
+    };
+
+    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,

package/tools/shared/skill-validation.js

@@ -0,0 +1,240 @@
+/**
+ * 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
+const VALID_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const CONSECUTIVE_HYPHENS = /--/;
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_COMPATIBILITY_LENGTH = 500;
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+
+export function validateSkillName(name) {
+  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 };
+}
+
+export function parseSkillContent(content) {
+  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();
+
+  const fields = {};
+  let currentMetadata = null;
+  let currentArray = null;
+  let currentArrayKey = null;
+
+  for (const line of frontmatterBlock.split('\n')) {
+    if (currentArray !== null && /^\s*- /.test(line)) {
+      const item = line.trim().substring(2).trim();
+      if (item) {
+        currentArray.push(item.replace(/^["']|["']$/g, ''));
+      }
+      continue;
+    }
+
+    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;
+    }
+
+    if (currentArray !== null && currentArrayKey) {
+      fields[currentArrayKey] = currentArray;
+    }
+    if (currentMetadata !== null) {
+      fields.metadata = currentMetadata;
+    }
+    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) {
+      currentMetadata = {};
+      fields.metadata = currentMetadata;
+      continue;
+    }
+
+    if (key === 'allowed-tools' && !value) {
+      currentArray = [];
+      currentArrayKey = 'allowed-tools';
+      continue;
+    }
+
+    if (key && value) {
+      fields[key] = value.replace(/^["']|["']$/g, '');
+    }
+  }
+
+  if (currentArray !== null && currentArrayKey) {
+    fields[currentArrayKey] = currentArray;
+  }
+
+  const frontmatter = {
+    name: fields.name || '',
+    description: fields.description || '',
+  };
+
+  if (fields.license) frontmatter.license = fields.license;
+  if (fields.compatibility) frontmatter.compatibility = fields.compatibility;
+  if (fields['allowed-tools']) {
+    frontmatter['allowed-tools'] = Array.isArray(fields['allowed-tools'])
+      ? fields['allowed-tools']
+      : fields['allowed-tools'];
+  }
+  if (currentMetadata && Object.keys(currentMetadata).length > 0) {
+    frontmatter.metadata = currentMetadata;
+  }
+
+  return {
+    success: true,
+    parsed: { frontmatter, body, raw: content },
+  };
+}
+
+export function validateFrontmatter(frontmatter, directoryName) {
+  const issues = [];
+
+  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' });
+    }
+  }
+
+  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',
+    });
+  }
+
+  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',
+    });
+  }
+
+  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,
+  };
+}
+
+export 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;
+}

package/tools/web/web.ts

@@ -5,7 +5,7 @@
  */
 
 import axios, { AxiosRequestConfig, AxiosError } from 'axios';
-import { MatimoError, ErrorCode } from '../../src/errors/matimo-error';
+import { MatimoError, ErrorCode } from '@matimo/core/runtime';
 
 interface WebParams {
   url: string;
@@ -74,7 +74,7 @@ export default async function webTool(params: WebParams): Promise<WebResult> {
     headers: {
       'User-Agent': 'Matimo/1.0 (AI Agent Tool SDK)',
       Accept: 'application/json, text/plain, text/html, */*',
-      ...headers,
+      ...(headers || {}),
     },
     validateStatus: () => true, // Don't throw on any status code
   };