@soleri/core 2.1.0 → 2.5.0

package/src/telemetry/telemetry.ts

@@ -0,0 +1,118 @@
+/**
+ * In-memory telemetry tracker for facade calls.
+ *
+ * No external deps — records calls, computes stats, bounds memory usage.
+ * Max 10 000 entries; auto-trims to 5 000 when limit is hit.
+ */
+
+export interface FacadeCall {
+  facade: string;
+  op: string;
+  timestamp: number;
+  durationMs: number;
+  success: boolean;
+  error?: string;
+}
+
+export interface TelemetryStats {
+  totalCalls: number;
+  successRate: number;
+  avgDurationMs: number;
+  callsByFacade: Record<string, number>;
+  callsByOp: Record<string, number>;
+  errorsByOp: Record<string, number>;
+  slowestOps: Array<{ op: string; avgMs: number }>;
+  since: number;
+}
+
+const MAX_ENTRIES = 10_000;
+const TRIM_TO = 5_000;
+
+export class Telemetry {
+  private calls: FacadeCall[] = [];
+  private startedAt = Date.now();
+
+  /**
+   * Record a facade call. Timestamp is auto-set to Date.now().
+   */
+  record(call: Omit<FacadeCall, 'timestamp'>): void {
+    this.calls.push({ ...call, timestamp: Date.now() });
+    if (this.calls.length > MAX_ENTRIES) {
+      this.calls = this.calls.slice(-TRIM_TO);
+    }
+  }
+
+  /**
+   * Compute aggregate stats from all recorded calls.
+   */
+  getStats(): TelemetryStats {
+    const total = this.calls.length;
+    if (total === 0) {
+      return {
+        totalCalls: 0,
+        successRate: 1,
+        avgDurationMs: 0,
+        callsByFacade: {},
+        callsByOp: {},
+        errorsByOp: {},
+        slowestOps: [],
+        since: this.startedAt,
+      };
+    }
+
+    const successes = this.calls.filter((c) => c.success).length;
+    const totalDuration = this.calls.reduce((sum, c) => sum + c.durationMs, 0);
+
+    const callsByFacade: Record<string, number> = {};
+    const callsByOp: Record<string, number> = {};
+    const errorsByOp: Record<string, number> = {};
+    const durationsByOp: Record<string, number[]> = {};
+
+    for (const call of this.calls) {
+      callsByFacade[call.facade] = (callsByFacade[call.facade] ?? 0) + 1;
+      callsByOp[call.op] = (callsByOp[call.op] ?? 0) + 1;
+
+      if (!call.success) {
+        errorsByOp[call.op] = (errorsByOp[call.op] ?? 0) + 1;
+      }
+
+      if (!durationsByOp[call.op]) durationsByOp[call.op] = [];
+      durationsByOp[call.op].push(call.durationMs);
+    }
+
+    // Compute slowest ops by average duration, top 10
+    const opAvgDurations = Object.entries(durationsByOp)
+      .map(([op, durations]) => ({
+        op,
+        avgMs: Math.round(durations.reduce((a, b) => a + b, 0) / durations.length),
+      }))
+      .sort((a, b) => b.avgMs - a.avgMs)
+      .slice(0, 10);
+
+    return {
+      totalCalls: total,
+      successRate: Math.round((successes / total) * 1000) / 1000,
+      avgDurationMs: Math.round(totalDuration / total),
+      callsByFacade,
+      callsByOp,
+      errorsByOp,
+      slowestOps: opAvgDurations,
+      since: this.startedAt,
+    };
+  }
+
+  /**
+   * Get the N most recent calls, newest first.
+   */
+  getRecent(limit = 50): FacadeCall[] {
+    return this.calls.slice(-limit).reverse();
+  }
+
+  /**
+   * Clear all recorded data and reset the start timestamp.
+   */
+  reset(): void {
+    this.calls = [];
+    this.startedAt = Date.now();
+  }
+}

package/src/vault/playbook.ts

@@ -0,0 +1,87 @@
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+export interface PlaybookStep {
+  order: number;
+  title: string;
+  description: string;
+  validation?: string;
+}
+
+export interface Playbook {
+  id: string;
+  title: string;
+  domain: string;
+  description: string;
+  steps: PlaybookStep[];
+  tags: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlaybookValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a playbook's structure.
+ * Checks: title non-empty, steps.length > 0, each step has order/title/description,
+ * orders are sequential starting from 1.
+ */
+export function validatePlaybook(playbook: Playbook): PlaybookValidationResult {
+  const errors: string[] = [];
+
+  if (!playbook.title || playbook.title.trim() === '') {
+    errors.push('Playbook title must not be empty');
+  }
+
+  if (!playbook.steps || playbook.steps.length === 0) {
+    errors.push('Playbook must have at least one step');
+  } else {
+    for (let i = 0; i < playbook.steps.length; i++) {
+      const step = playbook.steps[i];
+      const expectedOrder = i + 1;
+
+      if (step.order !== expectedOrder) {
+        errors.push(`Step ${i + 1} has order ${step.order}, expected ${expectedOrder}`);
+      }
+      if (!step.title || step.title.trim() === '') {
+        errors.push(`Step ${expectedOrder} title must not be empty`);
+      }
+      if (!step.description || step.description.trim() === '') {
+        errors.push(`Step ${expectedOrder} description must not be empty`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Parse a Playbook from a vault IntelligenceEntry.
+ * Returns null if the entry is not a playbook type or if the context is not valid
+ * JSON with a steps array.
+ */
+export function parsePlaybookFromEntry(entry: IntelligenceEntry): Playbook | null {
+  if (entry.type !== 'playbook') return null;
+
+  let steps: PlaybookStep[];
+  try {
+    const parsed = JSON.parse(entry.context ?? '');
+    if (!Array.isArray(parsed?.steps)) return null;
+    steps = parsed.steps;
+  } catch {
+    return null;
+  }
+
+  return {
+    id: entry.id,
+    title: entry.title,
+    domain: entry.domain,
+    description: entry.description,
+    steps,
+    tags: entry.tags,
+    createdAt: 0, // not available from entry directly
+    updatedAt: 0,
+  };
+}