prepia 1.0.0

package/src/shadow/daemon.mjs

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Background task daemon for periodic operations.
+ * @module shadow/daemon
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class Daemon extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, Object>} */
+    this._jobs = new Map();
+    this._running = false;
+  }
+
+  /**
+   * Register a periodic job.
+   * @param {string} name - Job name
+   * @param {Function} fn - Async function to execute
+   * @param {number} intervalMs - Interval in ms
+   */
+  register(name, fn, intervalMs) {
+    if (this._jobs.has(name)) {
+      this.unregister(name);
+    }
+    this._jobs.set(name, {
+      name,
+      fn,
+      intervalMs,
+      intervalId: null,
+      lastRun: null,
+      lastError: null,
+      runCount: 0,
+    });
+  }
+
+  /**
+   * Unregister a job.
+   * @param {string} name
+   */
+  unregister(name) {
+    const job = this._jobs.get(name);
+    if (job?.intervalId) {
+      clearInterval(job.intervalId);
+    }
+    this._jobs.delete(name);
+  }
+
+  /**
+   * Start all registered jobs.
+   */
+  start() {
+    this._running = true;
+    for (const [name, job] of this._jobs) {
+      if (job.intervalId) continue;
+      job.intervalId = setInterval(async () => {
+        try {
+          this.emit('job:start', { name });
+          await job.fn();
+          job.lastRun = Date.now();
+          job.runCount++;
+          this.emit('job:complete', { name, runCount: job.runCount });
+        } catch (err) {
+          job.lastError = err.message;
+          this.emit('job:error', { name, error: err.message });
+        }
+      }, job.intervalMs);
+      // Run immediately on start
+      job.fn().then(() => {
+        job.lastRun = Date.now();
+        job.runCount++;
+      }).catch(err => {
+        job.lastError = err.message;
+      });
+    }
+  }
+
+  /**
+   * Stop all jobs.
+   */
+  stop() {
+    this._running = false;
+    for (const job of this._jobs.values()) {
+      if (job.intervalId) {
+        clearInterval(job.intervalId);
+        job.intervalId = null;
+      }
+    }
+  }
+
+  /**
+   * Get status of all jobs.
+   * @returns {Object[]}
+   */
+  status() {
+    return Array.from(this._jobs.values()).map(j => ({
+      name: j.name,
+      intervalMs: j.intervalMs,
+      lastRun: j.lastRun,
+      lastError: j.lastError,
+      runCount: j.runCount,
+      running: j.intervalId !== null,
+    }));
+  }
+
+  /**
+   * Run a specific job immediately.
+   * @param {string} name
+   * @returns {Promise<void>}
+   */
+  async runNow(name) {
+    const job = this._jobs.get(name);
+    if (!job) throw new Error(`Job "${name}" not found`);
+    await job.fn();
+    job.lastRun = Date.now();
+    job.runCount++;
+  }
+
+  /**
+   * Check if daemon is running.
+   * @returns {boolean}
+   */
+  get isRunning() {
+    return this._running;
+  }
+}
+
+export default Daemon;

package/src/stream/handler.mjs

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Real-time streaming progress handler.
+ * @module stream/handler
+ */
+
+import { EventEmitter } from 'node:events';
+
+/**
+ * @typedef {Object} ProgressUpdate
+ * @property {string} taskId - Task ID
+ * @property {string} phase - Current phase
+ * @property {number} progress - Progress (0-1)
+ * @property {string} message - Human-readable status
+ * @property {*} [data] - Phase-specific data
+ */
+
+/** Standard processing phases */
+export const Phases = {
+  RECEIVED: 'received',
+  ANALYZING: 'analyzing',
+  SEARCHING: 'searching',
+  EXTRACTING: 'extracting',
+  PROCESSING: 'processing',
+  SYNTHESIZING: 'synthesizing',
+  VERIFYING: 'verifying',
+  COMPLETE: 'complete',
+  ERROR: 'error',
+};
+
+/** Phase order for progress calculation */
+const PHASE_ORDER = [
+  Phases.RECEIVED,
+  Phases.ANALYZING,
+  Phases.SEARCHING,
+  Phases.EXTRACTING,
+  Phases.PROCESSING,
+  Phases.SYNTHESIZING,
+  Phases.VERIFYING,
+  Phases.COMPLETE,
+];
+
+export class StreamHandler extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, Object>} Active task states */
+    this._tasks = new Map();
+  }
+
+  /**
+   * Start tracking a task.
+   * @param {string} taskId
+   * @param {string} [description] - Task description
+   */
+  start(taskId, description = '') {
+    this._tasks.set(taskId, {
+      id: taskId,
+      description,
+      phase: Phases.RECEIVED,
+      progress: 0,
+      startTime: Date.now(),
+      cancelled: false,
+    });
+    this.emit('progress', {
+      taskId,
+      phase: Phases.RECEIVED,
+      progress: 0,
+      message: 'Task received',
+    });
+  }
+
+  /**
+   * Update the phase of a task.
+   * @param {string} taskId
+   * @param {string} phase
+   * @param {string} [message] - Status message
+   * @param {*} [data] - Phase-specific data
+   */
+  update(taskId, phase, message = '', data = undefined) {
+    const task = this._tasks.get(taskId);
+    if (!task || task.cancelled) return;
+
+    task.phase = phase;
+    const phaseIdx = PHASE_ORDER.indexOf(phase);
+    task.progress = phaseIdx >= 0 ? (phaseIdx + 1) / PHASE_ORDER.length : task.progress;
+
+    const update = {
+      taskId,
+      phase,
+      progress: task.progress,
+      message: message || phase,
+      data,
+    };
+
+    this.emit('progress', update);
+  }
+
+  /**
+   * Mark a task as complete.
+   * @param {string} taskId
+   * @param {*} result - Task result
+   */
+  complete(taskId, result = undefined) {
+    const task = this._tasks.get(taskId);
+    if (!task) return;
+
+    task.phase = Phases.COMPLETE;
+    task.progress = 1;
+    task.endTime = Date.now();
+
+    this.emit('progress', {
+      taskId,
+      phase: Phases.COMPLETE,
+      progress: 1,
+      message: 'Task complete',
+      data: { result, duration: task.endTime - task.startTime },
+    });
+
+    this.emit('complete', { taskId, result, duration: task.endTime - task.startTime });
+  }
+
+  /**
+   * Mark a task as errored.
+   * @param {string} taskId
+   * @param {string} error - Error message
+   */
+  error(taskId, error) {
+    const task = this._tasks.get(taskId);
+    if (!task) return;
+
+    task.phase = Phases.ERROR;
+    task.endTime = Date.now();
+
+    this.emit('progress', {
+      taskId,
+      phase: Phases.ERROR,
+      progress: task.progress,
+      message: `Error: ${error}`,
+    });
+
+    this.emit('error', { taskId, error, duration: task.endTime - task.startTime });
+  }
+
+  /**
+   * Cancel a task.
+   * @param {string} taskId
+   * @returns {boolean}
+   */
+  cancel(taskId) {
+    const task = this._tasks.get(taskId);
+    if (!task) return false;
+    task.cancelled = true;
+    task.endTime = Date.now();
+    this.emit('cancel', { taskId });
+    return true;
+  }
+
+  /**
+   * Check if a task is cancelled.
+   * @param {string} taskId
+   * @returns {boolean}
+   */
+  isCancelled(taskId) {
+    return this._tasks.get(taskId)?.cancelled ?? false;
+  }
+
+  /**
+   * Get the state of a task.
+   * @param {string} taskId
+   * @returns {Object|undefined}
+   */
+  getState(taskId) {
+    const task = this._tasks.get(taskId);
+    if (!task) return undefined;
+    return {
+      ...task,
+      elapsed: (task.endTime || Date.now()) - task.startTime,
+    };
+  }
+
+  /**
+   * Get all active tasks.
+   * @returns {Object[]}
+   */
+  getActive() {
+    return Array.from(this._tasks.values())
+      .filter(t => !t.cancelled && t.phase !== Phases.COMPLETE && t.phase !== Phases.ERROR)
+      .map(t => ({ ...t, elapsed: Date.now() - t.startTime }));
+  }
+
+  /**
+   * Clean up completed/errored tasks.
+   * @param {number} [maxAge=300000] - Max age in ms (5 min)
+   */
+  cleanup(maxAge = 300000) {
+    const now = Date.now();
+    for (const [id, task] of this._tasks) {
+      if (task.endTime && (now - task.endTime) > maxAge) {
+        this._tasks.delete(id);
+      }
+    }
+  }
+}
+
+export default StreamHandler;

package/src/tools/calculator.mjs

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview Safe math expression evaluator without eval().
+ * Supports arithmetic, percentages, unit conversions, and common math functions.
+ * @module tools/calculator
+ */
+
+/**
+ * Unit conversion factors (all relative to base unit).
+ */
+const UNIT_FACTORS = {
+  // Length (base: meters)
+  'mm': 0.001, 'cm': 0.01, 'm': 1, 'km': 1000,
+  'in': 0.0254, 'ft': 0.3048, 'yd': 0.9144, 'mi': 1609.344,
+  // Weight (base: grams)
+  'mg': 0.001, 'g': 1, 'kg': 1000,
+  'oz': 28.3495, 'lb': 453.592, 'ton': 907185,
+  // Volume (base: liters)
+  'ml': 0.001, 'l': 1, 'gal': 3.78541, 'qt': 0.946353, 'pt': 0.473176,
+  // Temperature handled separately
+  // Time (base: seconds)
+  'ms': 0.001, 's': 1, 'min': 60, 'hr': 3600, 'day': 86400,
+  // Data (base: bytes)
+  'b': 1, 'kb': 1024, 'mb': 1048576, 'gb': 1073741824, 'tb': 1099511627776,
+};
+
+/**
+ * Temperature conversion units.
+ */
+const TEMP_UNITS = ['c', 'f', 'k', 'celsius', 'fahrenheit', 'kelvin'];
+
+/**
+ * Evaluate a mathematical expression safely.
+ * @param {string} expression - Math expression to evaluate
+ * @returns {Object} Result with value and metadata
+ */
+export function evaluate(expression) {
+  if (!expression || typeof expression !== 'string') {
+    throw new Error('Expression must be a non-empty string');
+  }
+
+  const cleaned = expression.trim().toLowerCase();
+
+  // Check for unit conversion: "100 km to miles"
+  const convertMatch = cleaned.match(
+    /^([\d.]+)\s*([a-z]+)\s+(?:to|in|as)\s+([a-z]+)$/
+  );
+  if (convertMatch) {
+    return convertUnit(parseFloat(convertMatch[1]), convertMatch[2], convertMatch[3]);
+  }
+
+  // Check for percentage: "20% of 150"
+  const pctMatch = cleaned.match(/^([\d.]+)\s*%\s*(?:of|off)?\s*([\d.]+)$/);
+  if (pctMatch) {
+    const value = (parseFloat(pctMatch[1]) / 100) * parseFloat(pctMatch[2]);
+    return { value, expression: cleaned, type: 'percentage' };
+  }
+
+  // Parse and evaluate arithmetic expression
+  const value = parseExpression(cleaned);
+  return { value, expression: cleaned, type: 'arithmetic' };
+}
+
+/**
+ * Convert between units.
+ * @param {number} value
+ * @param {string} fromUnit
+ * @param {string} toUnit
+ * @returns {Object}
+ */
+function convertUnit(value, fromUnit, toUnit) {
+  // Temperature special cases
+  if (isTempUnit(fromUnit) && isTempUnit(toUnit)) {
+    const result = convertTemperature(value, normalizeTempUnit(fromUnit), normalizeTempUnit(toUnit));
+    return { value: result, expression: `${value} ${fromUnit} to ${toUnit}`, type: 'temperature' };
+  }
+
+  const fromFactor = UNIT_FACTORS[fromUnit];
+  const toFactor = UNIT_FACTORS[toUnit];
+
+  if (!fromFactor) throw new Error(`Unknown unit: ${fromUnit}`);
+  if (!toFactor) throw new Error(`Unknown unit: ${toUnit}`);
+
+  // Check same category
+  if (!sameCategory(fromUnit, toUnit)) {
+    throw new Error(`Cannot convert ${fromUnit} to ${toUnit}: incompatible unit types`);
+  }
+
+  const result = (value * fromFactor) / toFactor;
+  return { value: result, expression: `${value} ${fromUnit} to ${toUnit}`, type: 'conversion' };
+}
+
+function isTempUnit(u) {
+  return TEMP_UNITS.includes(u);
+}
+
+function normalizeTempUnit(u) {
+  if (u === 'celsius' || u === 'c') return 'c';
+  if (u === 'fahrenheit' || u === 'f') return 'f';
+  if (u === 'kelvin' || u === 'k') return 'k';
+  return u;
+}
+
+function convertTemperature(value, from, to) {
+  // Convert to Celsius first
+  let celsius;
+  switch (from) {
+    case 'c': celsius = value; break;
+    case 'f': celsius = (value - 32) * 5 / 9; break;
+    case 'k': celsius = value - 273.15; break;
+    default: throw new Error(`Unknown temperature unit: ${from}`);
+  }
+  // Convert from Celsius to target
+  switch (to) {
+    case 'c': return celsius;
+    case 'f': return celsius * 9 / 5 + 32;
+    case 'k': return celsius + 273.15;
+    default: throw new Error(`Unknown temperature unit: ${to}`);
+  }
+}
+
+function sameCategory(a, b) {
+  const categories = [
+    ['mm', 'cm', 'm', 'km', 'in', 'ft', 'yd', 'mi'],
+    ['mg', 'g', 'kg', 'oz', 'lb', 'ton'],
+    ['ml', 'l', 'gal', 'qt', 'pt'],
+    ['ms', 's', 'min', 'hr', 'day'],
+    ['b', 'kb', 'mb', 'gb', 'tb'],
+  ];
+  for (const cat of categories) {
+    if (cat.includes(a) && cat.includes(b)) return true;
+  }
+  return false;
+}
+
+/**
+ * Recursive descent parser for arithmetic expressions.
+ * Supports: +, -, *, /, ^, (), unary minus, math functions
+ */
+function parseExpression(expr) {
+  const tokens = tokenize(expr);
+  let pos = 0;
+
+  function peek() { return tokens[pos]; }
+  function consume() { return tokens[pos++]; }
+
+  function parseExpr() {
+    let left = parseTerm();
+    while (peek() === '+' || peek() === '-') {
+      const op = consume();
+      const right = parseTerm();
+      left = op === '+' ? left + right : left - right;
+    }
+    return left;
+  }
+
+  function parseTerm() {
+    let left = parsePower();
+    while (peek() === '*' || peek() === '/') {
+      const op = consume();
+      const right = parsePower();
+      if (op === '/' && right === 0) throw new Error('Division by zero');
+      left = op === '*' ? left * right : left / right;
+    }
+    return left;
+  }
+
+  function parsePower() {
+    let base = parseUnary();
+    while (peek() === '^') {
+      consume();
+      const exp = parseUnary();
+      base = Math.pow(base, exp);
+    }
+    return base;
+  }
+
+  function parseUnary() {
+    if (peek() === '-') {
+      consume();
+      return -parsePrimary();
+    }
+    if (peek() === '+') {
+      consume();
+      return parsePrimary();
+    }
+    return parsePrimary();
+  }
+
+  function parsePrimary() {
+    const tok = peek();
+
+    // Parentheses
+    if (tok === '(') {
+      consume();
+      const val = parseExpr();
+      if (peek() !== ')') throw new Error('Mismatched parentheses');
+      consume();
+      return val;
+    }
+
+    // Math functions
+    if (typeof tok === 'string' && tok.match(/^(sqrt|abs|sin|cos|tan|log|ln|ceil|floor|round|exp|pow|min|max)$/)) {
+      consume();
+      return parseFunction(tok);
+    }
+
+    // Constants
+    if (tok === 'pi') { consume(); return Math.PI; }
+    if (tok === 'e') { consume(); return Math.E; }
+
+    // Number
+    if (typeof tok === 'number') {
+      consume();
+      return tok;
+    }
+
+    // Percentage after number: handled in tokenize
+    throw new Error(`Unexpected token: ${tok}`);
+  }
+
+  function parseFunction(name) {
+    if (peek() !== '(') throw new Error(`Expected ( after ${name}`);
+    consume();
+
+    const args = [parseExpr()];
+    while (peek() === ',') {
+      consume();
+      args.push(parseExpr());
+    }
+
+    if (peek() !== ')') throw new Error(`Expected ) after ${name} arguments`);
+    consume();
+
+    switch (name) {
+      case 'sqrt': return Math.sqrt(args[0]);
+      case 'abs': return Math.abs(args[0]);
+      case 'sin': return Math.sin(args[0]);
+      case 'cos': return Math.cos(args[0]);
+      case 'tan': return Math.tan(args[0]);
+      case 'log': return Math.log10(args[0]);
+      case 'ln': return Math.log(args[0]);
+      case 'ceil': return Math.ceil(args[0]);
+      case 'floor': return Math.floor(args[0]);
+      case 'round': return Math.round(args[0]);
+      case 'exp': return Math.exp(args[0]);
+      case 'pow': return Math.pow(args[0], args[1] ?? 2);
+      case 'min': return Math.min(...args);
+      case 'max': return Math.max(...args);
+      default: throw new Error(`Unknown function: ${name}`);
+    }
+  }
+
+  const result = parseExpr();
+  if (pos < tokens.length) {
+    throw new Error(`Unexpected token at position ${pos}: ${tokens[pos]}`);
+  }
+  return result;
+}
+
+/**
+ * Tokenize a math expression string.
+ * @param {string} expr
+ * @returns {Array<string|number>}
+ */
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  const s = expr.replace(/\s+/g, '');
+
+  while (i < s.length) {
+    const ch = s[i];
+
+    // Numbers (including decimals)
+    if (ch >= '0' && ch <= '9' || (ch === '.' && i + 1 < s.length && s[i + 1] >= '0' && s[i + 1] <= '9')) {
+      let num = '';
+      while (i < s.length && (s[i] >= '0' && s[i] <= '9' || s[i] === '.')) {
+        num += s[i++];
+      }
+      // Handle percentage: "20%" -> 0.2
+      if (i < s.length && s[i] === '%') {
+        i++;
+        tokens.push(parseFloat(num) / 100);
+      } else {
+        tokens.push(parseFloat(num));
+      }
+      continue;
+    }
+
+    // Operators and parentheses
+    if ('+-*/^(),'.includes(ch)) {
+      tokens.push(ch);
+      i++;
+      continue;
+    }
+
+    // Words (functions, constants, units)
+    if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')) {
+      let word = '';
+      while (i < s.length && ((s[i] >= 'a' && s[i] <= 'z') || (s[i] >= 'A' && s[i] <= 'Z') || (s[i] >= '0' && s[i] <= '9'))) {
+        word += s[i++];
+      }
+      tokens.push(word);
+      continue;
+    }
+
+    throw new Error(`Unexpected character: ${ch}`);
+  }
+
+  return tokens;
+}
+
+export default { evaluate };