@usejarvis/brain 0.1.0

package/src/workflows/triggers/cron.ts

@@ -0,0 +1,311 @@
+/**
+ * CronScheduler — lightweight cron expression parser and scheduler
+ *
+ * Supports standard 5-field cron: minute hour dayOfMonth month dayOfWeek
+ * Special characters: * / - and comma-separated lists
+ * No external dependencies.
+ */
+
+// ── Types ──
+
+export type CronJob = {
+  id: string;
+  expression: string;
+  callback: () => void;
+  lastRun: number | null;
+  nextRun: number;
+  handle: ReturnType<typeof setInterval>;
+};
+
+export type CronJobInfo = {
+  id: string;
+  expression: string;
+  lastRun: number | null;
+  nextRun: number;
+};
+
+// ── Parser helpers ──
+
+/**
+ * Parse a single cron field value into a sorted array of matching integers.
+ */
+function parseField(field: string, min: number, max: number): number[] {
+  const values = new Set<number>();
+
+  for (const part of field.split(',')) {
+    const trimmed = part.trim();
+
+    // Wildcard: *
+    if (trimmed === '*') {
+      for (let i = min; i <= max; i++) values.add(i);
+      continue;
+    }
+
+    // Step: */n or start/n
+    if (trimmed.includes('/')) {
+      const [rangeStr, stepStr] = trimmed.split('/');
+      const step = parseInt(stepStr!, 10);
+      if (isNaN(step) || step <= 0) throw new Error(`Invalid step in cron field: "${trimmed}"`);
+
+      let rangeMin = min;
+      let rangeMax = max;
+
+      if (rangeStr !== '*') {
+        if (rangeStr!.includes('-')) {
+          const [a, b] = rangeStr!.split('-').map(s => parseInt(s, 10));
+          rangeMin = a!;
+          rangeMax = b!;
+        } else {
+          rangeMin = parseInt(rangeStr!, 10);
+        }
+      }
+
+      for (let i = rangeMin; i <= rangeMax; i += step) values.add(i);
+      continue;
+    }
+
+    // Range: a-b
+    if (trimmed.includes('-')) {
+      const [a, b] = trimmed.split('-').map(s => parseInt(s, 10));
+      if (isNaN(a!) || isNaN(b!)) throw new Error(`Invalid range in cron field: "${trimmed}"`);
+      for (let i = a!; i <= b!; i += 1) values.add(i);
+      continue;
+    }
+
+    // Literal value
+    const val = parseInt(trimmed, 10);
+    if (isNaN(val)) throw new Error(`Invalid value in cron field: "${trimmed}"`);
+    values.add(val);
+  }
+
+  return Array.from(values).sort((a, b) => a - b);
+}
+
+/**
+ * Parse a full 5-field cron expression into its component arrays.
+ */
+function parseExpression(expression: string): {
+  minutes: number[];
+  hours: number[];
+  daysOfMonth: number[];
+  months: number[];
+  daysOfWeek: number[];
+} {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression "${expression}": expected 5 fields, got ${parts.length}`);
+  }
+
+  const [minField, hourField, domField, monthField, dowField] = parts;
+
+  return {
+    minutes: parseField(minField!, 0, 59),
+    hours: parseField(hourField!, 0, 23),
+    daysOfMonth: parseField(domField!, 1, 31),
+    months: parseField(monthField!, 1, 12),
+    daysOfWeek: parseField(dowField!, 0, 6),  // 0 = Sunday
+  };
+}
+
+// ── CronScheduler ──
+
+export class CronScheduler {
+  private jobs: Map<string, CronJob> = new Map();
+
+  /**
+   * Check if a cron expression matches a given date.
+   */
+  static matches(expression: string, date: Date = new Date()): boolean {
+    try {
+      const { minutes, hours, daysOfMonth, months, daysOfWeek } = parseExpression(expression);
+
+      const minute = date.getMinutes();
+      const hour = date.getHours();
+      const dom = date.getDate();
+      const month = date.getMonth() + 1;  // getMonth() is 0-based
+      const dow = date.getDay();           // 0 = Sunday
+
+      return (
+        minutes.includes(minute) &&
+        hours.includes(hour) &&
+        daysOfMonth.includes(dom) &&
+        months.includes(month) &&
+        daysOfWeek.includes(dow)
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Calculate the next execution time for a cron expression.
+   * @param expression - 5-field cron expression
+   * @param from - start searching from this date (default: now)
+   * @returns Date of next execution, or null if none found within 1 year
+   */
+  static nextRun(expression: string, from: Date = new Date()): Date | null {
+    try {
+      const { minutes, hours, daysOfMonth, months, daysOfWeek } = parseExpression(expression);
+
+      // Start from the next minute
+      const start = new Date(from);
+      start.setSeconds(0, 0);
+      start.setMinutes(start.getMinutes() + 1);
+
+      // Search up to 1 year ahead (minute-by-minute is too slow; step by minute smartly)
+      const limit = new Date(from);
+      limit.setFullYear(limit.getFullYear() + 1);
+
+      const candidate = new Date(start);
+
+      while (candidate < limit) {
+        const month = candidate.getMonth() + 1;
+        const dom = candidate.getDate();
+        const hour = candidate.getHours();
+        const minute = candidate.getMinutes();
+        const dow = candidate.getDay();
+
+        if (!months.includes(month)) {
+          // Advance to next valid month
+          candidate.setMonth(candidate.getMonth() + 1);
+          candidate.setDate(1);
+          candidate.setHours(0, 0, 0, 0);
+          continue;
+        }
+
+        if (!daysOfMonth.includes(dom) || !daysOfWeek.includes(dow)) {
+          // Advance to next day
+          candidate.setDate(candidate.getDate() + 1);
+          candidate.setHours(0, 0, 0, 0);
+          continue;
+        }
+
+        if (!hours.includes(hour)) {
+          // Find next valid hour
+          const nextHour = hours.find(h => h > hour);
+          if (nextHour !== undefined) {
+            candidate.setHours(nextHour, 0, 0, 0);
+          } else {
+            candidate.setDate(candidate.getDate() + 1);
+            candidate.setHours(0, 0, 0, 0);
+          }
+          continue;
+        }
+
+        if (!minutes.includes(minute)) {
+          // Find next valid minute in this hour
+          const nextMinute = minutes.find(m => m > minute);
+          if (nextMinute !== undefined) {
+            candidate.setMinutes(nextMinute, 0, 0);
+          } else {
+            // Advance to next valid hour
+            const nextHour = hours.find(h => h > hour);
+            if (nextHour !== undefined) {
+              candidate.setHours(nextHour, 0, 0, 0);
+            } else {
+              candidate.setDate(candidate.getDate() + 1);
+              candidate.setHours(0, 0, 0, 0);
+            }
+          }
+          continue;
+        }
+
+        // All fields match
+        return new Date(candidate);
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Schedule a recurring callback based on a cron expression.
+   * Uses setInterval to check every 30 seconds whether the expression matches.
+   */
+  schedule(id: string, expression: string, callback: () => void): void {
+    if (this.jobs.has(id)) {
+      this.cancel(id);
+    }
+
+    // Validate expression eagerly
+    parseExpression(expression);
+
+    const nextRun = CronScheduler.nextRun(expression);
+    if (!nextRun) {
+      throw new Error(`Cron expression "${expression}" has no upcoming execution times`);
+    }
+
+    let lastTickMinute = -1;
+
+    const handle = setInterval(() => {
+      const now = new Date();
+      const currentMinute = now.getFullYear() * 525960 + (now.getMonth() + 1) * 43830 + now.getDate() * 1440 + now.getHours() * 60 + now.getMinutes();
+
+      // Only evaluate once per minute
+      if (currentMinute === lastTickMinute) return;
+      lastTickMinute = currentMinute;
+
+      if (CronScheduler.matches(expression, now)) {
+        const job = this.jobs.get(id);
+        if (job) {
+          job.lastRun = Date.now();
+          const next = CronScheduler.nextRun(expression, now);
+          job.nextRun = next ? next.getTime() : Date.now();
+        }
+        try {
+          callback();
+        } catch (err) {
+          console.error(`[CronScheduler] Job "${id}" threw an error:`, err);
+        }
+      }
+    }, 30_000);
+
+    this.jobs.set(id, {
+      id,
+      expression,
+      callback,
+      lastRun: null,
+      nextRun: nextRun.getTime(),
+      handle,
+    });
+
+    console.log(`[CronScheduler] Scheduled job "${id}" (${expression}), next run: ${nextRun.toISOString()}`);
+  }
+
+  /**
+   * Cancel a specific scheduled job.
+   */
+  cancel(id: string): void {
+    const job = this.jobs.get(id);
+    if (job) {
+      clearInterval(job.handle);
+      this.jobs.delete(id);
+      console.log(`[CronScheduler] Cancelled job "${id}"`);
+    }
+  }
+
+  /**
+   * Cancel all scheduled jobs.
+   */
+  cancelAll(): void {
+    for (const job of this.jobs.values()) {
+      clearInterval(job.handle);
+    }
+    this.jobs.clear();
+    console.log('[CronScheduler] All jobs cancelled');
+  }
+
+  /**
+   * Returns info about all active jobs (without the handle or callback).
+   */
+  getJobs(): CronJobInfo[] {
+    return Array.from(this.jobs.values()).map(({ id, expression, lastRun, nextRun }) => ({
+      id,
+      expression,
+      lastRun,
+      nextRun,
+    }));
+  }
+}

package/src/workflows/triggers/manager.ts

@@ -0,0 +1,285 @@
+/**
+ * TriggerManager — ties together all trigger mechanisms and maps them to the WorkflowEngine
+ *
+ * Implements the Service interface and acts as the single entry point for:
+ *   - Cron-based scheduling (trigger.cron)
+ *   - Inbound webhooks (trigger.webhook)
+ *   - Outbound HTTP polling (trigger.poll)
+ *   - Observer-based events (trigger.file_change, trigger.clipboard, etc.)
+ *   - Manual triggers (fired externally via fireTrigger)
+ */
+
+import type { Service, ServiceStatus } from '../../daemon/services.ts';
+import type { WorkflowEngine } from '../engine.ts';
+import type { WorkflowDefinition, WorkflowNode } from '../types.ts';
+import { CronScheduler } from './cron.ts';
+import { WebhookManager } from './webhook.ts';
+import { PollingEngine } from './poller.ts';
+import type { PollConfig } from './poller.ts';
+import * as vault from '../../vault/workflows.ts';
+
+// ── Types ──
+
+/** All trigger node types recognised by the TriggerManager */
+const TRIGGER_TYPES = new Set([
+  'trigger.cron',
+  'trigger.webhook',
+  'trigger.poll',
+  'trigger.manual',
+  'trigger.file_change',
+  'trigger.clipboard',
+  'trigger.process',
+  'trigger.email',
+  'trigger.calendar',
+  'trigger.notification',
+  'trigger.screen',
+]);
+
+// ── TriggerManager ──
+
+export class TriggerManager implements Service {
+  readonly name = 'trigger-manager';
+
+  private _status: ServiceStatus = 'stopped';
+  private engine: WorkflowEngine;
+
+  private cron: CronScheduler;
+  private webhooks: WebhookManager;
+  private poller: PollingEngine;
+
+  /** workflowId → set of registered trigger identifiers */
+  private registrations: Map<string, Set<string>> = new Map();
+
+  constructor(workflowEngine: WorkflowEngine) {
+    this.engine = workflowEngine;
+    this.cron = new CronScheduler();
+    this.webhooks = new WebhookManager();
+    this.poller = new PollingEngine();
+
+    // Wire webhook callbacks
+    this.webhooks.setTriggerCallback((workflowId, data) => {
+      this.fire(workflowId, 'webhook', data);
+    });
+  }
+
+  // ── Service lifecycle ──
+
+  async start(): Promise<void> {
+    this._status = 'starting';
+    try {
+      await this.reloadAll();
+      this._status = 'running';
+      console.log('[TriggerManager] Started');
+    } catch (err) {
+      this._status = 'error';
+      throw err;
+    }
+  }
+
+  async stop(): Promise<void> {
+    this._status = 'stopping';
+
+    this.cron.cancelAll();
+    this.poller.unregisterAll();
+    this.registrations.clear();
+    // Webhooks are stateless HTTP handlers; nothing to teardown at the transport level
+
+    this._status = 'stopped';
+    console.log('[TriggerManager] Stopped');
+  }
+
+  status(): ServiceStatus {
+    return this._status;
+  }
+
+  // ── Public API ──
+
+  /**
+   * Register all trigger nodes found in a workflow definition.
+   */
+  registerWorkflow(workflowId: string, definition: WorkflowDefinition): void {
+    // Remove any existing triggers first (idempotent)
+    this.unregisterWorkflow(workflowId);
+
+    const triggerNodes = definition.nodes.filter(n => TRIGGER_TYPES.has(n.type));
+    const ids = new Set<string>();
+
+    for (const node of triggerNodes) {
+      const nodeKey = `${workflowId}:${node.id}`;
+      this.registerTriggerNode(workflowId, node, nodeKey);
+      ids.add(nodeKey);
+    }
+
+    if (ids.size > 0) {
+      this.registrations.set(workflowId, ids);
+      console.log(`[TriggerManager] Registered ${ids.size} trigger(s) for workflow "${workflowId}"`);
+    }
+  }
+
+  /**
+   * Unregister all triggers associated with a workflow.
+   */
+  unregisterWorkflow(workflowId: string): void {
+    const ids = this.registrations.get(workflowId);
+    if (!ids) return;
+
+    for (const id of ids) {
+      this.cron.cancel(id);
+      this.poller.unregister(id);
+      // Webhook is keyed by workflowId, unregister once
+    }
+
+    this.webhooks.unregister(workflowId);
+    this.registrations.delete(workflowId);
+    console.log(`[TriggerManager] Unregistered triggers for workflow "${workflowId}"`);
+  }
+
+  /**
+   * Load all enabled workflows from the vault and register their triggers.
+   * Safe to call multiple times (idempotent — clears first).
+   */
+  async reloadAll(): Promise<void> {
+    // Clear existing
+    this.cron.cancelAll();
+    this.poller.unregisterAll();
+    this.registrations.clear();
+
+    const workflows = vault.findWorkflows({ enabled: true });
+    let registered = 0;
+
+    for (const wf of workflows) {
+      const version = vault.getLatestVersion(wf.id);
+      if (!version) continue;
+
+      try {
+        this.registerWorkflow(wf.id, version.definition);
+        registered++;
+      } catch (err) {
+        console.error(`[TriggerManager] Failed to register triggers for workflow "${wf.name}":`, err);
+      }
+    }
+
+    console.log(`[TriggerManager] Loaded triggers for ${registered}/${workflows.length} workflows`);
+  }
+
+  /**
+   * Manually fire a trigger for a workflow (useful for manual/test triggers).
+   */
+  fireTrigger(workflowId: string, triggerType: string, data?: Record<string, unknown>): void {
+    this.fire(workflowId, triggerType, data ?? {});
+  }
+
+  // ── Accessors ──
+
+  getCronScheduler(): CronScheduler {
+    return this.cron;
+  }
+
+  getWebhookManager(): WebhookManager {
+    return this.webhooks;
+  }
+
+  getPollingEngine(): PollingEngine {
+    return this.poller;
+  }
+
+  // ── Internal ──
+
+  private registerTriggerNode(workflowId: string, node: WorkflowNode, nodeKey: string): void {
+    switch (node.type) {
+      case 'trigger.cron':
+        this.registerCronTrigger(workflowId, node, nodeKey);
+        break;
+
+      case 'trigger.webhook':
+        this.registerWebhookTrigger(workflowId, node);
+        break;
+
+      case 'trigger.poll':
+        this.registerPollTrigger(workflowId, node, nodeKey);
+        break;
+
+      case 'trigger.manual':
+        // Manual triggers are fired programmatically via fireTrigger() — no setup needed
+        console.log(`[TriggerManager] Manual trigger registered for workflow "${workflowId}" (node: ${node.id})`);
+        break;
+
+      // Observer-sourced triggers — registered via ObserverBridge externally,
+      // but we still track them in registrations for cleanup purposes
+      case 'trigger.file_change':
+      case 'trigger.clipboard':
+      case 'trigger.process':
+      case 'trigger.email':
+      case 'trigger.calendar':
+      case 'trigger.notification':
+      case 'trigger.screen':
+        console.log(`[TriggerManager] Observer trigger "${node.type}" registered for workflow "${workflowId}"`);
+        break;
+
+      default:
+        console.warn(`[TriggerManager] Unknown trigger type "${node.type}" in workflow "${workflowId}"`);
+    }
+  }
+
+  private registerCronTrigger(workflowId: string, node: WorkflowNode, key: string): void {
+    const expression = node.config.expression as string | undefined;
+    if (!expression) {
+      console.warn(`[TriggerManager] Cron trigger node "${node.id}" in workflow "${workflowId}" has no expression`);
+      return;
+    }
+
+    try {
+      this.cron.schedule(key, expression, () => {
+        this.fire(workflowId, 'cron', { expression, nodeId: node.id });
+      });
+    } catch (err) {
+      console.error(`[TriggerManager] Failed to schedule cron "${expression}" for workflow "${workflowId}":`, err);
+    }
+  }
+
+  private registerWebhookTrigger(workflowId: string, node: WorkflowNode): void {
+    const secret = node.config.secret as string | undefined;
+    const path = this.webhooks.register(workflowId, secret);
+    console.log(`[TriggerManager] Webhook trigger for workflow "${workflowId}" registered at ${path}`);
+  }
+
+  private registerPollTrigger(workflowId: string, node: WorkflowNode, key: string): void {
+    const url = node.config.url as string | undefined;
+    if (!url) {
+      console.warn(`[TriggerManager] Poll trigger node "${node.id}" in workflow "${workflowId}" has no url`);
+      return;
+    }
+
+    const config: PollConfig = {
+      url,
+      intervalMs: (node.config.intervalMs as number | undefined) ?? 60_000,
+      method: (node.config.method as string | undefined) ?? 'GET',
+      headers: node.config.headers as Record<string, string> | undefined,
+      body: node.config.body as string | undefined,
+      deduplicateField: node.config.deduplicateField as string | undefined,
+    };
+
+    try {
+      this.poller.register(key, config, (data, meta) => {
+        this.fire(workflowId, 'poll', {
+          data,
+          url: meta.url,
+          status: meta.status,
+          timestamp: meta.timestamp,
+          nodeId: node.id,
+        });
+      });
+    } catch (err) {
+      console.error(`[TriggerManager] Failed to register poll trigger for workflow "${workflowId}":`, err);
+    }
+  }
+
+  /**
+   * Fire the WorkflowEngine for a given workflow trigger.
+   */
+  private fire(workflowId: string, triggerType: string, data: Record<string, unknown>): void {
+    this.engine.execute(workflowId, triggerType, data).catch(err => {
+      console.error(`[TriggerManager] Execution failed for workflow "${workflowId}" (trigger: ${triggerType}):`, err);
+    });
+  }
+}