@matimo/core 0.1.0-alpha.10

package/tools/read/definition.yaml

@@ -0,0 +1,106 @@
+name: read
+version: '1.0.0'
+description: Read file contents with support for line ranges, encoding detection, and large file handling.
+requires_approval: true
+
+parameters:
+  filePath:
+    type: string
+    description: Absolute or relative path to file to read (supports ~ for home directory)
+    required: true
+    example: './src/config.ts'
+
+  startLine:
+    type: number
+    description: Starting line number (1-based, inclusive). If not provided, reads from beginning.
+    required: false
+    example: 10
+
+  endLine:
+    type: number
+    description: Ending line number (1-based, inclusive). If not provided, reads to end of file.
+    required: false
+    example: 50
+
+  encoding:
+    type: string
+    description: File encoding (utf8, utf16, ascii, latin1). Defaults to utf8.
+    required: false
+    default: 'utf8'
+    example: 'utf8'
+
+  maxLines:
+    type: number
+    description: Maximum lines to read (default 10000, useful for large files). Returns error if exceeded.
+    required: false
+    example: 5000
+
+execution:
+  type: function
+  code: './read.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether file read was successful
+    filePath:
+      type: string
+      description: Path to the file that was read
+    content:
+      type: string
+      description: File content (or file excerpt if line range specified)
+    encoding:
+      type: string
+      description: Encoding used for file read
+    lineCount:
+      type: number
+      description: Total number of lines in file (if known)
+    readLines:
+      type: number
+      description: Number of lines actually read
+    linesRequested:
+      type: object
+      properties:
+        start:
+          type: number
+        end:
+          type: number
+    size:
+      type: number
+      description: File size in bytes
+    mtime:
+      type: string
+      description: Last modified time (ISO format)
+  required: [success, filePath, content, encoding, readLines]
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 300
+
+examples:
+  - name: 'Read entire file'
+    description: 'Read complete file contents'
+    params:
+      filePath: './config.json'
+  - name: 'Read specific line range'
+    description: 'Read lines 10-50 from file'
+    params:
+      filePath: './src/app.ts'
+      startLine: 10
+      endLine: 50
+  - name: 'Read single line'
+    description: 'Read exactly line 42'
+    params:
+      filePath: './package.json'
+      startLine: 42
+      endLine: 42
+  - name: 'Read with encoding'
+    description: 'Read file with specific encoding'
+    params:
+      filePath: './data/records.csv'
+      encoding: 'latin1'
+
+tags: [file-io, read, filesystem, text, content]

package/tools/read/read.ts

@@ -0,0 +1,118 @@
+#!/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';
+
+interface ReadParams {
+  filePath: string;
+  startLine?: number;
+  endLine?: number;
+  encoding?: string;
+  maxLines?: number;
+}
+
+interface ReadResult {
+  success: boolean;
+  filePath: string;
+  content: string;
+  encoding: string;
+  readLines: number;
+  lineCount?: number;
+  linesRequested?: {
+    start?: number;
+    end?: number;
+  };
+  size: number;
+  mtime: string;
+}
+
+/**
+ * Read file contents with optional line range
+ */
+export default async function readTool(params: ReadParams): Promise<ReadResult> {
+  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 as BufferEncoding);
+  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: { start?: number; end?: number } = {};
+
+  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: ReadResult = {
+    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

@@ -0,0 +1,148 @@
+name: search
+version: '1.0.0'
+description: Search files by name or content using patterns and regex
+requires_approval: true
+
+parameters:
+  query:
+    type: string
+    description: Search query (file pattern or text to find)
+    required: true
+    example: 'MatimoInstance'
+
+  directory:
+    type: string
+    description: Directory to search (default current directory)
+    required: false
+    example: './src'
+
+  filePattern:
+    type: string
+    description: File glob pattern (e.g. '*.ts', '**/*.test.ts')
+    required: false
+    example: '*.ts'
+
+  isRegex:
+    type: boolean
+    description: Treat query as regex (default false)
+    required: false
+    default: false
+
+  caseSensitive:
+    type: boolean
+    description: Case-sensitive search (default false)
+    required: false
+    default: false
+
+  excludePatterns:
+    type: array
+    description: Glob patterns to exclude
+    required: false
+    example: ['node_modules/**', 'dist/**']
+
+  maxResults:
+    type: number
+    description: Maximum results to return (default 50)
+    required: false
+    default: 50
+
+  contextLines:
+    type: number
+    description: Context lines around matches (default 2)
+    required: false
+    default: 2
+
+execution:
+  type: function
+  code: './search.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether search completed successfully
+    query:
+      type: string
+      description: Search query that was used
+    directory:
+      type: string
+      description: Directory that was searched
+    pattern:
+      type: string
+      description: File pattern used for filtering
+    matches:
+      type: array
+      description: Array of matching files and content
+      items:
+        type: object
+        properties:
+          filePath:
+            type: string
+            description: Path to file containing match
+          lineNumber:
+            type: number
+            description: Line number of match (1-based)
+          lineContent:
+            type: string
+            description: Content of matched line
+          matchIndex:
+            type: number
+            description: Character position of match in line
+          context:
+            type: array
+            description: Context lines before and after match
+            items:
+              type: string
+    totalMatches:
+      type: number
+      description: Total number of matches found
+    filesSearched:
+      type: number
+      description: Number of files searched
+    duration:
+      type: number
+      description: Search duration in milliseconds
+    truncated:
+      type: boolean
+      description: Whether results were truncated due to maxResults
+  required: [success, query, matches, totalMatches, filesSearched, duration]
+
+error_handling:
+  retry: 1
+  backoff_type: exponential
+  initial_delay_ms: 300
+
+examples:
+  - name: 'Search for function definition'
+    description: 'Search for function definitions in TypeScript files'
+    params:
+      query: 'function'
+      directory: './src'
+      filePattern: '*.ts'
+      maxResults: 20
+  - name: 'Regex search in codebase'
+    description: 'Search using regex pattern'
+    params:
+      query: 'const\s+[a-zA-Z_]\w*\s*=\s*{' 
+      directory: '.'
+      filePattern: '**/*.ts'
+      isRegex: true
+      excludePatterns: ['node_modules/**', 'dist/**']
+  - name: 'Case-sensitive search'
+    description: 'Find exact case matches'
+    params:
+      query: 'MatimoInstance'
+      directory: './src'
+      caseSensitive: true
+      maxResults: 100
+  - name: 'Search with context'
+    description: 'Search with surrounding context lines'
+    params:
+      query: 'export class'
+      directory: './src/core'
+      filePattern: '*.ts'
+      contextLines: 3
+      maxResults: 30
+
+tags: [search, filesystem, grep, pattern-matching, text-search]

package/tools/search/search.ts

@@ -0,0 +1,192 @@
+#!/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';
+
+interface SearchMatch {
+  filePath: string;
+  lineNumber: number;
+  lineContent: string;
+  matchIndex: number;
+  context: string[];
+}
+
+interface SearchParams {
+  query: string;
+  directory?: string;
+  filePattern?: string;
+  isRegex?: boolean;
+  caseSensitive?: boolean;
+  maxResults?: number;
+  contextLines?: number;
+  excludePatterns?: string[];
+}
+
+interface SearchResult {
+  success: boolean;
+  query: string;
+  directory: string;
+  pattern: string;
+  matches: SearchMatch[];
+  totalMatches: number;
+  filesSearched: number;
+  duration: number;
+  truncated: boolean;
+}
+
+/**
+ * Search files for pattern matches
+ */
+export default async function searchTool(params: SearchParams): Promise<SearchResult> {
+  const logger = getGlobalMatimoLogger();
+  const {
+    query,
+    directory = '.',
+    filePattern = '**/*',
+    isRegex = false,
+    caseSensitive = false,
+    maxResults = 50,
+    contextLines = 2,
+    excludePatterns = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+  } = params;
+
+  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: RegExp;
+  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: string[] = [];
+
+  try {
+    files = await glob(globPattern, {
+      nodir: true,
+      absolute: true,
+      ignore: excludePatterns,
+    });
+  } catch {
+    throw new MatimoError('Invalid glob pattern', ErrorCode.INVALID_PARAMETER, {
+      pattern: filePattern,
+      baseDirectory: resolvedDir,
+    });
+  }
+
+  const matches: SearchMatch[] = [];
+  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: SearchResult = {
+    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;
+}

package/tools/web/definition.yaml

@@ -0,0 +1,132 @@
+name: web
+version: '1.0.0'
+description: Fetch and parse web content from URLs. Supports redirects, headers, timeouts, and content extraction.
+
+parameters:
+  url:
+    type: string
+    description: URL to fetch (http or https)
+    required: true
+    example: 'https://api.github.com/users/octocat'
+
+  method:
+    type: string
+    description: 'HTTP method: GET, POST, PUT, PATCH, DELETE (default GET)'
+    required: false
+    default: 'GET'
+    example: 'GET'
+
+  headers:
+    type: object
+    description: Additional HTTP headers as key-value pairs (optional)
+    required: false
+    example: '{"Authorization": "Bearer token123", "Accept": "application/json"}'
+
+  body:
+    type: string
+    description: Request body for POST/PUT/PATCH (JSON string or plain text)
+    required: false
+    example: '{"key": "value"}'
+
+  timeout:
+    type: number
+    description: Request timeout in milliseconds (default 30000)
+    required: false
+    default: 30000
+    example: 60000
+
+  followRedirects:
+    type: boolean
+    description: Follow HTTP redirects (default true, max 5 redirects)
+    required: false
+    default: true
+
+  parseJson:
+    type: boolean
+    description: Automatically parse response as JSON if content-type is application/json (default true)
+    required: false
+    default: true
+
+  maxSize:
+    type: number
+    description: Maximum response size in bytes (default 10485760 = 10MB). Prevents memory exhaustion.
+    required: false
+    default: 10485760
+
+execution:
+  type: function
+  code: './web.ts'
+
+output_schema:
+  type: object
+  properties:
+    success:
+      type: boolean
+      description: Whether request succeeded
+    url:
+      type: string
+      description: URL that was fetched
+    statusCode:
+      type: number
+      description: HTTP status code (200, 404, 500, etc.)
+    statusText:
+      type: string
+      description: HTTP status text
+    contentType:
+      type: string
+      description: Content-Type header from response
+    content:
+      oneOf:
+        - type: object
+          description: Parsed JSON object (if parseJson=true and content-type is json)
+        - type: string
+          description: Response body as string
+    headers:
+      type: object
+      description: Response headers as key-value pairs
+    size:
+      type: number
+      description: Response body size in bytes
+    duration:
+      type: number
+      description: Request duration in milliseconds
+    redirects:
+      type: array
+      description: Array of redirect URLs if followed
+      items:
+        type: string
+  required: [success, url, statusCode, statusText, content, duration]
+
+error_handling:
+  retry: 2
+  backoff_type: exponential
+  initial_delay_ms: 1000
+
+examples:
+  - name: 'Fetch JSON API'
+    description: 'Get JSON data from REST API'
+    params:
+      url: 'https://api.github.com/users/octocat'
+      method: 'GET'
+  - name: 'Fetch HTML webpage'
+    description: 'Get HTML content from website'
+    params:
+      url: 'https://example.com'
+      method: 'GET'
+      parseJson: false
+  - name: 'POST with JSON body'
+    description: 'Send POST request with JSON payload'
+    params:
+      url: 'https://api.example.com/data'
+      method: 'POST'
+      headers: '{"Content-Type": "application/json"}'
+      body: '{"name": "Matimo", "version": "1.0.0"}'
+  - name: 'Fetch with authentication'
+    description: 'Request with bearer token'
+    params:
+      url: 'https://api.github.com/user'
+      method: 'GET'
+      headers: '{"Authorization": "Bearer ghp_xxxxxxxxxxxx"}'
+      timeout: 15000
+
+tags: [web, http, fetch, api, network, rest]