prepia 1.0.0

package/src/persona/detector.mjs

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Context-aware persona selection.
+ * @module persona/detector
+ */
+
+/**
+ * @typedef {Object} Persona
+ * @property {string} name - Persona name
+ * @property {string} type - Task type
+ * @property {string} style - Processing style
+ * @property {string} outputFormat - Preferred output format
+ */
+
+/** Available personas */
+const PERSONAS = {
+  data: {
+    name: 'Analyst',
+    type: 'data',
+    style: 'precise',
+    outputFormat: 'structured',
+    systemPrompt: 'You are a data analyst. Provide precise, structured answers with numbers and evidence. Use tables and lists.',
+  },
+  writing: {
+    name: 'Writer',
+    type: 'writing',
+    style: 'creative',
+    outputFormat: 'narrative',
+    systemPrompt: 'You are a skilled writer. Produce clear, engaging, well-structured prose. Focus on clarity and readability.',
+  },
+  research: {
+    name: 'Researcher',
+    type: 'research',
+    style: 'thorough',
+    outputFormat: 'cited',
+    systemPrompt: 'You are a thorough researcher. Provide comprehensive answers with sources and citations. Cover multiple perspectives.',
+  },
+  automation: {
+    name: 'Engineer',
+    type: 'automation',
+    style: 'efficient',
+    outputFormat: 'procedural',
+    systemPrompt: 'You are a technical engineer. Provide clear, step-by-step instructions. Focus on efficiency and correctness.',
+  },
+  casual: {
+    name: 'Assistant',
+    type: 'casual',
+    style: 'friendly',
+    outputFormat: 'conversational',
+    systemPrompt: 'You are a helpful assistant. Provide clear, friendly answers. Keep it concise but thorough.',
+  },
+};
+
+/**
+ * Detect the appropriate persona for a task.
+ * @param {string} query - User query
+ * @param {Object} [context] - Additional context
+ * @returns {Persona}
+ */
+export function detectPersona(query, context = {}) {
+  if (!query || typeof query !== 'string') {
+    return PERSONAS.casual;
+  }
+
+  const lower = query.toLowerCase();
+
+  // Data analysis patterns
+  if (
+    /\b(analyze|data|statistics|numbers|metrics|compare|trend|calculate|measure|percent|average|median)\b/i.test(lower) ||
+    /\b(chart|graph|table|report|dashboard)\b/i.test(lower)
+  ) {
+    return PERSONAS.data;
+  }
+
+  // Writing patterns
+  if (
+    /\b(write|draft|compose|essay|article|story|blog|email|letter|creative|poem|narrative)\b/i.test(lower) ||
+    /\b(summarize|rewrite|edit|proofread|paraphrase)\b/i.test(lower)
+  ) {
+    return PERSONAS.writing;
+  }
+
+  // Research patterns
+  if (
+    /\b(research|investigate|find|search|learn|explain|understand|what is|who is|history of|background)\b/i.test(lower) ||
+    /\b(compare|versus|pros and cons|differences)\b/i.test(lower)
+  ) {
+    return PERSONAS.research;
+  }
+
+  // Automation patterns
+  if (
+    /\b(automate|script|code|program|build|create|implement|deploy|configure|setup|install)\b/i.test(lower) ||
+    /\b(api|database|server|function|class|method)\b/i.test(lower)
+  ) {
+    return PERSONAS.automation;
+  }
+
+  return PERSONAS.casual;
+}
+
+/**
+ * Get all available personas.
+ * @returns {Object[]}
+ */
+export function getPersonas() {
+  return Object.values(PERSONAS);
+}
+
+/**
+ * Get a specific persona by type.
+ * @param {string} type
+ * @returns {Persona|undefined}
+ */
+export function getPersona(type) {
+  return PERSONAS[type];
+}
+
+export default { detectPersona, getPersonas, getPersona };

package/src/plugins/loader.mjs

@@ -0,0 +1,120 @@
+/**
+ * @fileoverview Plugin discovery and loading.
+ * @module plugins/loader
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export class PluginLoader {
+  /**
+   * @param {Object} [options]
+   * @param {string[]} [options.directories=['.prepia/plugins']] - Plugin directories
+   */
+  constructor(options = {}) {
+    this._directories = options.directories ?? ['.prepia/plugins'];
+    this._watchers = [];
+  }
+
+  /**
+   * Discover plugins from configured directories.
+   * @returns {Promise<Object[]>} Array of plugin manifests
+   */
+  async discover() {
+    const plugins = [];
+    for (const dir of this._directories) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          const manifestPath = path.join(dir, entry.name, 'manifest.json');
+          try {
+            const data = await fs.readFile(manifestPath, 'utf-8');
+            const manifest = JSON.parse(data);
+            manifest._path = path.join(dir, entry.name);
+            manifest._entryPath = path.join(dir, entry.name, manifest.main || 'index.mjs');
+            plugins.push(manifest);
+          } catch {
+            // Skip directories without manifest
+          }
+        }
+      } catch {
+        // Directory may not exist
+      }
+    }
+    return plugins;
+  }
+
+  /**
+   * Load a plugin from its manifest.
+   * @param {Object} manifest - Plugin manifest
+   * @returns {Promise<Object>} Loaded plugin
+   */
+  async load(manifest) {
+    if (!manifest._entryPath) {
+      throw new Error('Plugin manifest missing entry path');
+    }
+
+    try {
+      const plugin = await import(manifest._entryPath);
+      return {
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description || '',
+        manifest,
+        module: plugin,
+        loadedAt: Date.now(),
+      };
+    } catch (err) {
+      throw new Error(`Failed to load plugin ${manifest.name}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Discover and load all plugins.
+   * @returns {Promise<Object[]>}
+   */
+  async loadAll() {
+    const manifests = await this.discover();
+    const plugins = [];
+    for (const manifest of manifests) {
+      try {
+        const plugin = await this.load(manifest);
+        plugins.push(plugin);
+      } catch (err) {
+        // Log but don't fail on individual plugin errors
+        plugins.push({ name: manifest.name, error: err.message, loadedAt: Date.now() });
+      }
+    }
+    return plugins;
+  }
+
+  /**
+   * Validate a plugin manifest.
+   * @param {Object} manifest
+   * @returns {{ valid: boolean, errors: string[] }}
+   */
+  validate(manifest) {
+    const errors = [];
+    if (!manifest.name || typeof manifest.name !== 'string') {
+      errors.push('Missing or invalid "name" field');
+    }
+    if (!manifest.version || typeof manifest.version !== 'string') {
+      errors.push('Missing or invalid "version" field');
+    }
+    if (!manifest.main || typeof manifest.main !== 'string') {
+      errors.push('Missing or invalid "main" field');
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  /**
+   * Get the list of configured plugin directories.
+   * @returns {string[]}
+   */
+  get directories() {
+    return [...this._directories];
+  }
+}
+
+export default PluginLoader;

package/src/plugins/registry.mjs

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Plugin registry and lifecycle management.
+ * @module plugins/registry
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class PluginRegistry extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, Object>} */
+    this._plugins = new Map();
+    /** @type {Map<string, string[]>} Plugin dependencies */
+    this._dependencies = new Map();
+  }
+
+  /**
+   * Register a plugin.
+   * @param {Object} plugin - Loaded plugin object
+   * @param {Object} plugin.name - Plugin name
+   * @param {Object} plugin.module - Plugin module
+   * @param {Object} [plugin.manifest] - Plugin manifest
+   */
+  register(plugin) {
+    if (!plugin.name) throw new Error('Plugin must have a name');
+    if (this._plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+
+    // Check dependencies
+    const deps = plugin.manifest?.dependencies || [];
+    for (const dep of deps) {
+      if (!this._plugins.has(dep)) {
+        throw new Error(`Plugin "${plugin.name}" depends on "${dep}" which is not registered`);
+      }
+    }
+
+    this._plugins.set(plugin.name, {
+      ...plugin,
+      status: 'registered',
+      registeredAt: Date.now(),
+    });
+    this._dependencies.set(plugin.name, deps);
+    this.emit('plugin:registered', { name: plugin.name });
+  }
+
+  /**
+   * Unregister a plugin.
+   * @param {string} name - Plugin name
+   */
+  unregister(name) {
+    // Check if other plugins depend on this one
+    for (const [pluginName, deps] of this._dependencies) {
+      if (deps.includes(name)) {
+        throw new Error(`Cannot unregister "${name}": plugin "${pluginName}" depends on it`);
+      }
+    }
+
+    this._plugins.delete(name);
+    this._dependencies.delete(name);
+    this.emit('plugin:unregistered', { name });
+  }
+
+  /**
+   * Initialize a plugin (call its init lifecycle method).
+   * @param {string} name
+   * @param {Object} [context] - Init context
+   */
+  async init(name, context = {}) {
+    const plugin = this._plugins.get(name);
+    if (!plugin) throw new Error(`Plugin "${name}" not found`);
+
+    if (plugin.module.init) {
+      await plugin.module.init(context);
+    }
+    plugin.status = 'initialized';
+    this.emit('plugin:initialized', { name });
+  }
+
+  /**
+   * Execute a plugin's main function.
+   * @param {string} name
+   * @param {Object} params
+   * @returns {Promise<*>}
+   */
+  async execute(name, params = {}) {
+    const plugin = this._plugins.get(name);
+    if (!plugin) throw new Error(`Plugin "${name}" not found`);
+    if (plugin.status !== 'initialized') {
+      throw new Error(`Plugin "${name}" is not initialized`);
+    }
+
+    if (!plugin.module.execute) {
+      throw new Error(`Plugin "${name}" has no execute function`);
+    }
+
+    this.emit('plugin:execute:start', { name });
+    try {
+      const result = await plugin.module.execute(params);
+      this.emit('plugin:execute:complete', { name });
+      return result;
+    } catch (err) {
+      this.emit('plugin:execute:error', { name, error: err.message });
+      throw err;
+    }
+  }
+
+  /**
+   * Cleanup a plugin (call its cleanup lifecycle method).
+   * @param {string} name
+   */
+  async cleanup(name) {
+    const plugin = this._plugins.get(name);
+    if (!plugin) throw new Error(`Plugin "${name}" not found`);
+
+    if (plugin.module.cleanup) {
+      await plugin.module.cleanup();
+    }
+    plugin.status = 'cleaned';
+    this.emit('plugin:cleaned', { name });
+  }
+
+  /**
+   * Get a plugin by name.
+   * @param {string} name
+   * @returns {Object|undefined}
+   */
+  get(name) {
+    return this._plugins.get(name);
+  }
+
+  /**
+   * Get all registered plugins.
+   * @returns {Object[]}
+   */
+  getAll() {
+    return Array.from(this._plugins.values()).map(p => ({
+      name: p.name,
+      version: p.version,
+      description: p.description,
+      status: p.status,
+      registeredAt: p.registeredAt,
+    }));
+  }
+
+  /**
+   * Check if a plugin is registered.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._plugins.has(name);
+  }
+
+  /**
+   * Get the number of registered plugins.
+   * @returns {number}
+   */
+  get size() {
+    return this._plugins.size;
+  }
+}
+
+export default PluginRegistry;

package/src/plugins/sandbox.mjs

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Plugin execution sandbox with resource limits.
+ * @module plugins/sandbox
+ */
+
+export class Sandbox {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.timeout=10000] - Execution timeout in ms
+   * @param {number} [options.maxMemory=50*1024*1024] - Max memory (50MB)
+   */
+  constructor(options = {}) {
+    this._timeout = options.timeout ?? 10000;
+    this._maxMemory = options.maxMemory ?? 50 * 1024 * 1024;
+  }
+
+  /**
+   * Execute a function in a sandboxed context.
+   * @param {Function} fn - Async function to execute
+   * @param {Object} [context] - Context to pass to the function
+   * @returns {Promise<*>}
+   */
+  async execute(fn, context = {}) {
+    const start = Date.now();
+    let result;
+
+    try {
+      result = await Promise.race([
+        fn(context),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('Sandbox execution timeout')), this._timeout)
+        ),
+      ]);
+    } catch (err) {
+      return {
+        success: false,
+        error: err.message,
+        duration: Date.now() - start,
+      };
+    }
+
+    return {
+      success: true,
+      result,
+      duration: Date.now() - start,
+    };
+  }
+
+  /**
+   * Execute a plugin module function with validation.
+   * @param {Object} plugin - Plugin with module.execute
+   * @param {Object} params - Execution parameters
+   * @returns {Promise<Object>}
+   */
+  async executePlugin(plugin, params = {}) {
+    if (!plugin?.module?.execute) {
+      return { success: false, error: 'Plugin has no execute function' };
+    }
+    return this.execute(plugin.module.execute, params);
+  }
+
+  /**
+   * Create a restricted context object for plugin execution.
+   * @param {Object} [allowedAPIs] - APIs to expose
+   * @returns {Object}
+   */
+  createContext(allowedAPIs = {}) {
+    return {
+      console: {
+        log: (...args) => console.log(`[plugin]`, ...args),
+        warn: (...args) => console.warn(`[plugin]`, ...args),
+        error: (...args) => console.error(`[plugin]`, ...args),
+      },
+      ...allowedAPIs,
+    };
+  }
+}
+
+export default Sandbox;

package/src/rate/limiter.mjs

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Rate limiter - token bucket and sliding window algorithms.
+ * @module rate/limiter
+ */
+
+/**
+ * Token bucket rate limiter.
+ */
+export class TokenBucket {
+  /**
+   * @param {Object} options
+   * @param {number} options.capacity - Max tokens
+   * @param {number} options.refillRate - Tokens per second
+   */
+  constructor(options = {}) {
+    this._capacity = options.capacity ?? 100;
+    this._refillRate = options.refillRate ?? 10;
+    this._tokens = this._capacity;
+    this._lastRefill = Date.now();
+  }
+
+  /**
+   * Try to consume tokens.
+   * @param {number} [count=1] - Tokens to consume
+   * @returns {boolean} Whether tokens were available
+   */
+  consume(count = 1) {
+    this._refill();
+    if (this._tokens >= count) {
+      this._tokens -= count;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get current token count.
+   * @returns {number}
+   */
+  get tokens() {
+    this._refill();
+    return this._tokens;
+  }
+
+  /**
+   * Get time until next token is available.
+   * @param {number} [count=1] - Tokens needed
+   * @returns {number} Milliseconds until available, 0 if available now
+   */
+  waitFor(count = 1) {
+    this._refill();
+    if (this._tokens >= count) return 0;
+    const deficit = count - this._tokens;
+    return Math.ceil((deficit / this._refillRate) * 1000);
+  }
+
+  /**
+   * Refill tokens based on elapsed time.
+   * @private
+   */
+  _refill() {
+    const now = Date.now();
+    const elapsed = (now - this._lastRefill) / 1000;
+    this._tokens = Math.min(this._capacity, this._tokens + elapsed * this._refillRate);
+    this._lastRefill = now;
+  }
+
+  /**
+   * Reset to full capacity.
+   */
+  reset() {
+    this._tokens = this._capacity;
+    this._lastRefill = Date.now();
+  }
+}
+
+/**
+ * Sliding window rate limiter.
+ */
+export class SlidingWindow {
+  /**
+   * @param {Object} options
+   * @param {number} options.maxRequests - Max requests per window
+   * @param {number} options.windowMs - Window duration in ms
+   */
+  constructor(options = {}) {
+    this._maxRequests = options.maxRequests ?? 100;
+    this._windowMs = options.windowMs ?? 60000;
+    /** @type {number[]} */
+    this._timestamps = [];
+  }
+
+  /**
+   * Try to make a request.
+   * @returns {boolean} Whether request is allowed
+   */
+  consume() {
+    this._cleanup();
+    if (this._timestamps.length < this._maxRequests) {
+      this._timestamps.push(Date.now());
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get remaining requests in current window.
+   * @returns {number}
+   */
+  get remaining() {
+    this._cleanup();
+    return this._maxRequests - this._timestamps.length;
+  }
+
+  /**
+   * Get time until next request is allowed.
+   * @returns {number} ms until available, 0 if available now
+   */
+  waitFor() {
+    this._cleanup();
+    if (this._timestamps.length < this._maxRequests) return 0;
+    const oldest = this._timestamps[0];
+    return Math.max(0, oldest + this._windowMs - Date.now());
+  }
+
+  /**
+   * Remove expired timestamps.
+   * @private
+   */
+  _cleanup() {
+    const cutoff = Date.now() - this._windowMs;
+    while (this._timestamps.length > 0 && this._timestamps[0] <= cutoff) {
+      this._timestamps.shift();
+    }
+  }
+
+  /**
+   * Reset the window.
+   */
+  reset() {
+    this._timestamps = [];
+  }
+}
+
+export default { TokenBucket, SlidingWindow };