prepia 1.0.0

package/src/tools/file-ops.mjs

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview File system operations tool.
+ * @module tools/file-ops
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Read a file's contents.
+ * @param {string} filepath - Path to file
+ * @param {Object} [options]
+ * @param {string} [options.encoding='utf-8'] - File encoding
+ * @returns {Promise<string>}
+ */
+export async function readFile(filepath, options = {}) {
+  const { encoding = 'utf-8' } = options;
+  return fs.readFile(filepath, encoding);
+}
+
+/**
+ * Write content to a file.
+ * @param {string} filepath - Path to file
+ * @param {string} content - Content to write
+ * @param {Object} [options]
+ * @param {boolean} [options.createDirs=true] - Create parent directories
+ * @returns {Promise<void>}
+ */
+export async function writeFile(filepath, content, options = {}) {
+  const { createDirs = true } = options;
+  if (createDirs) {
+    await fs.mkdir(path.dirname(filepath), { recursive: true });
+  }
+  await fs.writeFile(filepath, content, 'utf-8');
+}
+
+/**
+ * Append content to a file.
+ * @param {string} filepath - Path to file
+ * @param {string} content - Content to append
+ * @returns {Promise<void>}
+ */
+export async function appendFile(filepath, content) {
+  await fs.appendFile(filepath, content, 'utf-8');
+}
+
+/**
+ * Check if a file exists.
+ * @param {string} filepath - Path to file
+ * @returns {Promise<boolean>}
+ */
+export async function exists(filepath) {
+  try {
+    await fs.access(filepath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get file stats.
+ * @param {string} filepath - Path to file
+ * @returns {Promise<Object>}
+ */
+export async function stat(filepath) {
+  const s = await fs.stat(filepath);
+  return {
+    size: s.size,
+    isFile: s.isFile(),
+    isDirectory: s.isDirectory(),
+    created: s.birthtime.toISOString(),
+    modified: s.mtime.toISOString(),
+  };
+}
+
+/**
+ * List directory contents.
+ * @param {string} dirpath - Path to directory
+ * @param {Object} [options]
+ * @param {boolean} [options.recursive=false] - List recursively
+ * @returns {Promise<string[]>}
+ */
+export async function listDir(dirpath, options = {}) {
+  const { recursive = false } = options;
+  if (!recursive) {
+    return fs.readdir(dirpath);
+  }
+  const results = [];
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      results.push(fullPath);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      }
+    }
+  }
+  await walk(dirpath);
+  return results;
+}
+
+/**
+ * Delete a file.
+ * @param {string} filepath - Path to file
+ * @returns {Promise<boolean>}
+ */
+export async function deleteFile(filepath) {
+  try {
+    await fs.unlink(filepath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a directory.
+ * @param {string} dirpath - Path to directory
+ * @returns {Promise<void>}
+ */
+export async function mkdir(dirpath) {
+  await fs.mkdir(dirpath, { recursive: true });
+}
+
+/**
+ * Copy a file.
+ * @param {string} src - Source path
+ * @param {string} dest - Destination path
+ * @returns {Promise<void>}
+ */
+export async function copyFile(src, dest) {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+}
+
+export default { readFile, writeFile, appendFile, exists, stat, listDir, deleteFile, mkdir, copyFile };

package/src/tools/http-client.mjs

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview HTTP client with retries, timeouts, and error handling.
+ * Uses Node 22 global fetch.
+ * @module tools/http-client
+ */
+
+/**
+ * Make an HTTP request with retries and timeout.
+ * @param {string} url - Request URL
+ * @param {Object} [options]
+ * @param {string} [options.method='GET'] - HTTP method
+ * @param {Object} [options.headers] - Request headers
+ * @param {*} [options.body] - Request body
+ * @param {number} [options.timeout=30000] - Timeout in ms
+ * @param {number} [options.retries=3] - Max retries
+ * @param {number} [options.retryDelay=1000] - Delay between retries in ms
+ * @returns {Promise<Object>} Response with status, headers, body
+ */
+export async function request(url, options = {}) {
+  const {
+    method = 'GET',
+    headers = {},
+    body,
+    timeout = 30000,
+    retries = 3,
+    retryDelay = 1000,
+  } = options;
+
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+
+      const fetchOptions = {
+        method,
+        headers: { 'User-Agent': 'Prepia/1.0', ...headers },
+        signal: controller.signal,
+      };
+
+      if (body && method !== 'GET' && method !== 'HEAD') {
+        fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+        if (!headers['Content-Type'] && !headers['content-type']) {
+          fetchOptions.headers['Content-Type'] = 'application/json';
+        }
+      }
+
+      const response = await fetch(url, fetchOptions);
+      clearTimeout(timer);
+
+      const responseBody = await response.text();
+      let parsedBody;
+      try {
+        parsedBody = JSON.parse(responseBody);
+      } catch {
+        parsedBody = responseBody;
+      }
+
+      return {
+        status: response.status,
+        statusText: response.statusText,
+        headers: Object.fromEntries(response.headers.entries()),
+        body: parsedBody,
+        ok: response.ok,
+      };
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries) {
+        await sleep(retryDelay * Math.pow(2, attempt));
+      }
+    }
+  }
+  throw new Error(`HTTP request failed after ${retries + 1} attempts: ${lastError?.message}`);
+}
+
+/**
+ * Make a GET request.
+ * @param {string} url
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+export function get(url, options = {}) {
+  return request(url, { ...options, method: 'GET' });
+}
+
+/**
+ * Make a POST request.
+ * @param {string} url
+ * @param {*} body
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+export function post(url, body, options = {}) {
+  return request(url, { ...options, method: 'POST', body });
+}
+
+/**
+ * Make a PUT request.
+ * @param {string} url
+ * @param {*} body
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+export function put(url, body, options = {}) {
+  return request(url, { ...options, method: 'PUT', body });
+}
+
+/**
+ * Make a DELETE request.
+ * @param {string} url
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+export function del(url, options = {}) {
+  return request(url, { ...options, method: 'DELETE' });
+}
+
+/**
+ * Sleep for a given duration.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export default { request, get, post, put, del };

package/src/tools/orchestrator.mjs

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Tool routing and execution orchestrator.
+ * @module tools/orchestrator
+ */
+
+import { EventEmitter } from 'node:events';
+import * as webSearch from './web-search.mjs';
+import * as webScraper from './web-scraper.mjs';
+import * as fileOps from './file-ops.mjs';
+import { evaluate } from './calculator.mjs';
+import * as httpClient from './http-client.mjs';
+
+/**
+ * @typedef {Object} ToolCall
+ * @property {string} tool - Tool name
+ * @property {Object} params - Tool parameters
+ * @property {string} [id] - Call ID for tracking
+ */
+
+/**
+ * @typedef {Object} ToolResult
+ * @property {string} id - Call ID
+ * @property {string} tool - Tool name
+ * @property {*} result - Tool result
+ * @property {string|null} error - Error message if failed
+ * @property {number} duration - Execution time in ms
+ */
+
+/** Built-in tool registry */
+const BUILTIN_TOOLS = {
+  'web-search': {
+    name: 'web-search',
+    description: 'Search the web for information',
+    execute: async (params) => webSearch.search(params.query, params),
+  },
+  'web-scrape': {
+    name: 'web-scrape',
+    description: 'Extract content from a web page',
+    execute: async (params) => webScraper.scrape(params.url, params),
+  },
+  'file-read': {
+    name: 'file-read',
+    description: 'Read file contents',
+    execute: async (params) => fileOps.readFile(params.path),
+  },
+  'file-write': {
+    name: 'file-write',
+    description: 'Write content to a file',
+    execute: async (params) => fileOps.writeFile(params.path, params.content),
+  },
+  'calculator': {
+    name: 'calculator',
+    description: 'Evaluate math expressions',
+    execute: async (params) => evaluate(params.expression),
+  },
+  'http-get': {
+    name: 'http-get',
+    description: 'Make an HTTP GET request',
+    execute: async (params) => httpClient.get(params.url, params),
+  },
+  'http-post': {
+    name: 'http-post',
+    description: 'Make an HTTP POST request',
+    execute: async (params) => httpClient.post(params.url, params.body, params),
+  },
+};
+
+export class Orchestrator extends EventEmitter {
+  /**
+   * Create a new Orchestrator.
+   * @param {Object} [options]
+   * @param {Object} [options.tools] - Additional tools to register
+   * @param {number} [options.maxConcurrency=5] - Max parallel tool executions
+   */
+  constructor(options = {}) {
+    super();
+    this._tools = new Map(Object.entries(BUILTIN_TOOLS));
+    if (options.tools) {
+      for (const [name, tool] of Object.entries(options.tools)) {
+        this._tools.set(name, tool);
+      }
+    }
+    this._maxConcurrency = options.maxConcurrency ?? 5;
+  }
+
+  /**
+   * Register a tool.
+   * @param {string} name - Tool name
+   * @param {Object} tool - Tool definition
+   * @param {string} tool.description - Tool description
+   * @param {Function} tool.execute - Async execution function
+   */
+  register(name, tool) {
+    this._tools.set(name, tool);
+  }
+
+  /**
+   * Unregister a tool.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  unregister(name) {
+    return this._tools.delete(name);
+  }
+
+  /**
+   * Get all registered tool names.
+   * @returns {string[]}
+   */
+  listTools() {
+    return Array.from(this._tools.keys());
+  }
+
+  /**
+   * Get tool definitions for LLM context.
+   * @returns {Object[]}
+   */
+  getToolDefinitions() {
+    return Array.from(this._tools.entries()).map(([name, tool]) => ({
+      name,
+      description: tool.description,
+      parameters: tool.parameters || {},
+    }));
+  }
+
+  /**
+   * Execute a single tool call.
+   * @param {ToolCall} call
+   * @returns {Promise<ToolResult>}
+   */
+  async executeOne(call) {
+    const tool = this._tools.get(call.tool);
+    const id = call.id || `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const start = Date.now();
+
+    if (!tool) {
+      return { id, tool: call.tool, result: null, error: `Unknown tool: ${call.tool}`, duration: 0 };
+    }
+
+    try {
+      this.emit('tool:start', { id, tool: call.tool });
+      const result = await tool.execute(call.params || {});
+      const duration = Date.now() - start;
+      this.emit('tool:complete', { id, tool: call.tool, duration });
+      return { id, tool: call.tool, result, error: null, duration };
+    } catch (err) {
+      const duration = Date.now() - start;
+      this.emit('tool:error', { id, tool: call.tool, error: err.message, duration });
+      return { id, tool: call.tool, result: null, error: err.message, duration };
+    }
+  }
+
+  /**
+   * Execute multiple tool calls in parallel with concurrency limit.
+   * @param {ToolCall[]} calls
+   * @returns {Promise<ToolResult[]>}
+   */
+  async executeMany(calls) {
+    const results = [];
+    const executing = new Set();
+
+    for (const call of calls) {
+      const promise = this.executeOne(call).then(result => {
+        executing.delete(promise);
+        return result;
+      });
+      executing.add(promise);
+      results.push(promise);
+
+      if (executing.size >= this._maxConcurrency) {
+        await Promise.race(executing);
+      }
+    }
+
+    return Promise.all(results);
+  }
+
+  /**
+   * Route a task to the appropriate tool based on intent.
+   * @param {string} intent - Task intent
+   * @param {Object} context - Task context
+   * @returns {ToolCall[]}
+   */
+  route(intent, context = {}) {
+    const calls = [];
+    const lower = intent.toLowerCase();
+
+    if (lower.includes('search') || lower.includes('find') || lower.includes('look up')) {
+      calls.push({ tool: 'web-search', params: { query: context.query || intent } });
+    }
+    if (lower.includes('scrape') || lower.includes('extract') || lower.includes('read page')) {
+      calls.push({ tool: 'web-scrape', params: { url: context.url } });
+    }
+    if (lower.includes('calculate') || lower.includes('compute') || lower.includes('math')) {
+      calls.push({ tool: 'calculator', params: { expression: context.expression } });
+    }
+    if (lower.includes('read file') || lower.includes('load file')) {
+      calls.push({ tool: 'file-read', params: { path: context.path } });
+    }
+
+    return calls;
+  }
+}
+
+export default Orchestrator;

package/src/tools/web-scraper.mjs

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Web content extraction - fetch and extract readable content from URLs.
+ * @module tools/web-scraper
+ */
+
+/**
+ * Fetch and extract readable content from a URL.
+ * @param {string} url - URL to scrape
+ * @param {Object} [options]
+ * @param {number} [options.timeout=15000] - Request timeout in ms
+ * @param {number} [options.maxLength=50000] - Max content length
+ * @returns {Promise<Object>} Extracted content
+ */
+export async function scrape(url, options = {}) {
+  if (!url || typeof url !== 'string') {
+    throw new Error('URL must be a non-empty string');
+  }
+
+  const { timeout = 15000, maxLength = 50000 } = options;
+
+  try {
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (compatible; Prepia/1.0)',
+        'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+      },
+      signal: AbortSignal.timeout(timeout),
+      redirect: 'follow',
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    const html = await response.text();
+
+    const extracted = extractContent(html, contentType);
+    const title = extractTitle(html);
+    const description = extractMeta(html, 'description');
+
+    return {
+      url,
+      title,
+      description,
+      text: extracted.text.substring(0, maxLength),
+      links: extracted.links,
+      headings: extracted.headings,
+    };
+  } catch (err) {
+    throw new Error(`Failed to scrape ${url}: ${err.message}`);
+  }
+}
+
+/**
+ * Extract readable content from HTML.
+ * @param {string} html
+ * @param {string} contentType
+ * @returns {Object}
+ */
+function extractContent(html, contentType) {
+  // Remove scripts, styles, nav, footer, header, aside
+  let cleaned = html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, '')
+    .replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, '')
+    .replace(/<header[^>]*>[\s\S]*?<\/header>/gi, '')
+    .replace(/<aside[^>]*>[\s\S]*?<\/aside>/gi, '')
+    .replace(/<form[^>]*>[\s\S]*?<\/form>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '');
+
+  // Extract links
+  const links = [];
+  const linkPattern = /<a[^>]+href="([^"]*)"[^>]*>(.*?)<\/a>/gs;
+  let match;
+  while ((match = linkPattern.exec(cleaned)) !== null) {
+    const href = match[1];
+    const text = match[2].replace(/<[^>]*>/g, '').trim();
+    if (href && text && !href.startsWith('#') && !href.startsWith('javascript:')) {
+      links.push({ href, text });
+    }
+  }
+
+  // Extract headings
+  const headings = [];
+  const headingPattern = /<h([1-6])[^>]*>(.*?)<\/h\1>/gs;
+  while ((match = headingPattern.exec(cleaned)) !== null) {
+    headings.push({
+      level: parseInt(match[1]),
+      text: match[2].replace(/<[^>]*>/g, '').trim(),
+    });
+  }
+
+  // Extract main content - try article/main first, fall back to body
+  let mainContent = cleaned;
+  const articleMatch = cleaned.match(/<(article|main)[^>]*>([\s\S]*?)<\/\1>/i);
+  if (articleMatch) {
+    mainContent = articleMatch[2];
+  }
+
+  // Strip remaining HTML tags
+  let text = mainContent
+    .replace(/<br[^>]*>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<\/div>/gi, '\n')
+    .replace(/<\/li>/gi, '\n')
+    .replace(/<\/tr>/gi, '\n')
+    .replace(/<[^>]*>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \t]+/g, ' ')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .join('\n')
+    .trim();
+
+  return { text, links: links.slice(0, 50), headings };
+}
+
+/**
+ * Extract the page title.
+ * @param {string} html
+ * @returns {string}
+ */
+function extractTitle(html) {
+  const match = html.match(/<title[^>]*>(.*?)<\/title>/i);
+  return match ? match[1].replace(/<[^>]*>/g, '').trim() : '';
+}
+
+/**
+ * Extract a meta tag content.
+ * @param {string} html
+ * @param {string} name
+ * @returns {string}
+ */
+function extractMeta(html, name) {
+  const match = html.match(new RegExp(`<meta[^>]*(?:name|property)=["']${name}["'][^>]*content=["']([^"']*)["']`, 'i'))
+    || html.match(new RegExp(`<meta[^>]*content=["']([^"']*)["'][^>]*(?:name|property)=["']${name}["']`, 'i'));
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Extract all text content from a URL (simple version).
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+export async function getText(url) {
+  const result = await scrape(url);
+  return result.text;
+}
+
+export default { scrape, getText };