@ema.co/mcp-toolkit 0.2.3 → 0.3.0

package/dist/sdk/version-policy.js

@@ -0,0 +1,328 @@
+/**
+ * Persona Version Policy Engine
+ *
+ * Handles automatic versioning decisions based on policies.
+ * Determines when to create snapshots, manages retention, and
+ * enforces versioning rules.
+ */
+import { createVersionSnapshot, hashSnapshot, createSnapshotFromPersona, generateChangesSummary, compareVersions, } from "./version-tracking.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Policy Engine Class
+// ─────────────────────────────────────────────────────────────────────────────
+export class VersionPolicyEngine {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    // ─────────────── Policy Checks ───────────────
+    /**
+     * Check if a version should be created for a persona.
+     */
+    checkPolicy(persona, trigger) {
+        const policy = this.storage.getPolicy(persona.id);
+        const snapshot = createSnapshotFromPersona(persona);
+        const contentHash = hashSnapshot(snapshot);
+        // Check if this would be a duplicate
+        const isDuplicate = this.storage.hasContentHash(persona.id, contentHash);
+        // Determine if we should create based on trigger and policy
+        let shouldCreate = false;
+        let reason = "";
+        let skipReason;
+        switch (trigger) {
+            case "manual":
+                // Always allow manual creation
+                shouldCreate = true;
+                reason = "Manual version creation requested";
+                break;
+            case "deploy":
+                if (policy.auto_version_on_deploy) {
+                    if (isDuplicate) {
+                        shouldCreate = false;
+                        skipReason = "Content unchanged from existing version";
+                    }
+                    else {
+                        shouldCreate = true;
+                        reason = "Auto-versioning on deploy enabled";
+                    }
+                }
+                else {
+                    shouldCreate = false;
+                    skipReason = "Auto-versioning on deploy disabled by policy";
+                }
+                break;
+            case "sync":
+                if (policy.auto_version_on_sync) {
+                    if (isDuplicate) {
+                        shouldCreate = false;
+                        skipReason = "Content unchanged from existing version";
+                    }
+                    else {
+                        shouldCreate = true;
+                        reason = "Auto-versioning on sync enabled";
+                    }
+                }
+                else {
+                    shouldCreate = false;
+                    skipReason = "Auto-versioning on sync disabled by policy";
+                }
+                break;
+            case "auto":
+                // Check interval if specified
+                if (policy.min_interval) {
+                    const latest = this.storage.getLatestVersion(persona.id);
+                    if (latest && !this.hasIntervalPassed(latest.created_at, policy.min_interval)) {
+                        shouldCreate = false;
+                        skipReason = `Minimum interval (${policy.min_interval}) not yet passed`;
+                        break;
+                    }
+                }
+                if (isDuplicate) {
+                    shouldCreate = false;
+                    skipReason = "Content unchanged from existing version";
+                }
+                else {
+                    shouldCreate = true;
+                    reason = "Auto-snapshot triggered";
+                }
+                break;
+            case "import":
+                // Always allow imports (but check dedup)
+                if (isDuplicate) {
+                    shouldCreate = false;
+                    skipReason = "Imported content matches existing version";
+                }
+                else {
+                    shouldCreate = true;
+                    reason = "Importing version from external source";
+                }
+                break;
+        }
+        return {
+            should_create_version: shouldCreate,
+            reason: shouldCreate ? reason : skipReason ?? "Unknown reason",
+            skip_reason: shouldCreate ? undefined : skipReason,
+            content_hash: contentHash,
+            is_duplicate: isDuplicate,
+        };
+    }
+    /**
+     * Check if the minimum interval has passed since the last version.
+     */
+    hasIntervalPassed(lastCreatedAt, interval) {
+        const last = new Date(lastCreatedAt);
+        const now = new Date();
+        // Parse ISO duration (simplified - supports PT{n}H, PT{n}M, P{n}D)
+        const hours = interval.match(/PT(\d+)H/)?.[1];
+        const minutes = interval.match(/PT(\d+)M/)?.[1];
+        const days = interval.match(/P(\d+)D/)?.[1];
+        let intervalMs = 0;
+        if (hours)
+            intervalMs += parseInt(hours, 10) * 60 * 60 * 1000;
+        if (minutes)
+            intervalMs += parseInt(minutes, 10) * 60 * 1000;
+        if (days)
+            intervalMs += parseInt(days, 10) * 24 * 60 * 60 * 1000;
+        return now.getTime() - last.getTime() >= intervalMs;
+    }
+    // ─────────────── Version Creation ───────────────
+    /**
+     * Create a version if policy allows.
+     * This is the main entry point for automatic versioning.
+     */
+    createVersionIfAllowed(persona, trigger, options) {
+        // Check policy (unless forced)
+        const check = this.checkPolicy(persona, trigger);
+        if (!options.force && !check.should_create_version) {
+            return {
+                created: false,
+                reason: check.reason,
+                versions_pruned: 0,
+            };
+        }
+        // Get parent version info
+        const latest = this.storage.getLatestVersion(persona.id);
+        const previousVersionNumber = latest?.version_number;
+        const parentVersionId = latest?.id;
+        // Create the version
+        const version = createVersionSnapshot({
+            persona,
+            environment: options.environment,
+            tenant_id: options.tenant_id,
+            trigger,
+            message: options.message,
+            created_by: options.created_by,
+            previous_version_number: previousVersionNumber,
+            parent_version_id: parentVersionId,
+        });
+        // Compute changes from parent
+        let changesFromParent;
+        if (latest) {
+            const diff = compareVersions(latest, version);
+            changesFromParent = generateChangesSummary(diff);
+            version.changes_summary = changesFromParent;
+        }
+        // Save the version
+        this.storage.saveVersion(version);
+        // Prune if necessary
+        const versionsPruned = this.storage.pruneVersions(persona.id);
+        return {
+            created: true,
+            version,
+            reason: `Created ${version.version_name}${options.force ? " (forced)" : ""}`,
+            changes_from_parent: changesFromParent,
+            versions_pruned: versionsPruned,
+        };
+    }
+    /**
+     * Force create a version regardless of policy.
+     */
+    forceCreateVersion(persona, options) {
+        return this.createVersionIfAllowed(persona, "manual", {
+            ...options,
+            force: true,
+        });
+    }
+    // ─────────────── Version Restoration ───────────────
+    /**
+     * Get the snapshot data needed to restore a version.
+     * Returns the persona configuration that can be applied via updateAiEmployee.
+     */
+    getRestoreData(personaId, versionIdentifier) {
+        // Get the version
+        let version = null;
+        if (typeof versionIdentifier === "number") {
+            version = this.storage.getVersion(personaId, versionIdentifier);
+        }
+        else if (versionIdentifier.match(/^v\d+$/)) {
+            version = this.storage.getVersionByName(personaId, versionIdentifier);
+        }
+        else {
+            // Assume it's a version ID
+            version = this.storage.getVersionById(personaId, versionIdentifier);
+        }
+        if (!version) {
+            return {
+                success: false,
+                error: `Version not found: ${versionIdentifier}`,
+            };
+        }
+        // Build restore payload
+        const snapshot = version.snapshot;
+        return {
+            success: true,
+            version,
+            restore_payload: {
+                persona_id: personaId,
+                name: snapshot.display_name,
+                description: snapshot.description,
+                proto_config: snapshot.proto_config ?? {},
+                workflow: snapshot.workflow_definition,
+                welcome_messages: snapshot.welcome_messages ?? null,
+                embedding_enabled: snapshot.embedding_enabled ?? null,
+            },
+        };
+    }
+    // ─────────────── Policy Management ───────────────
+    /**
+     * Get policy for a persona.
+     */
+    getPolicy(personaId) {
+        return this.storage.getPolicy(personaId);
+    }
+    /**
+     * Update policy for a persona.
+     */
+    updatePolicy(personaId, updates) {
+        const current = this.storage.getPolicy(personaId);
+        const updated = {
+            ...current,
+            ...updates,
+            persona_id: personaId, // Ensure this is always set
+        };
+        this.storage.savePolicy(updated);
+        return updated;
+    }
+    // ─────────────── Query Methods ───────────────
+    /**
+     * List versions for a persona with optional filtering.
+     */
+    listVersions(personaId, options) {
+        let versions = this.storage.listVersions(personaId);
+        // Apply filters
+        if (options?.trigger) {
+            versions = versions.filter((v) => v.trigger === options.trigger);
+        }
+        if (options?.since) {
+            const sinceDate = new Date(options.since);
+            versions = versions.filter((v) => new Date(v.created_at) >= sinceDate);
+        }
+        // Sort by version number descending (newest first)
+        versions = versions.sort((a, b) => b.version_number - a.version_number);
+        // Apply limit
+        if (options?.limit) {
+            versions = versions.slice(0, options.limit);
+        }
+        return versions.map((v) => ({
+            id: v.id,
+            version_number: v.version_number,
+            version_name: v.version_name,
+            created_at: v.created_at,
+            trigger: v.trigger,
+            message: v.message,
+            content_hash: v.content_hash,
+        }));
+    }
+    /**
+     * Get a specific version with full details.
+     */
+    getVersion(personaId, versionIdentifier) {
+        if (versionIdentifier === "latest") {
+            return this.storage.getLatestVersion(personaId);
+        }
+        if (typeof versionIdentifier === "number") {
+            return this.storage.getVersion(personaId, versionIdentifier);
+        }
+        // Try as version name first (v1, v2, etc.)
+        if (versionIdentifier.match(/^v\d+$/)) {
+            return this.storage.getVersionByName(personaId, versionIdentifier);
+        }
+        // Try as version ID
+        return this.storage.getVersionById(personaId, versionIdentifier);
+    }
+    /**
+     * Compare two versions.
+     */
+    compareVersions(personaId, v1Identifier, v2Identifier) {
+        const v1 = this.getVersion(personaId, v1Identifier);
+        const v2 = this.getVersion(personaId, v2Identifier);
+        if (!v1) {
+            return { success: false, error: `Version not found: ${v1Identifier}` };
+        }
+        if (!v2) {
+            return { success: false, error: `Version not found: ${v2Identifier}` };
+        }
+        const diff = compareVersions(v1, v2);
+        const summary = generateChangesSummary(diff);
+        return {
+            success: true,
+            diff,
+            summary,
+        };
+    }
+    // ─────────────── Storage Access ───────────────
+    /**
+     * Get the underlying storage instance.
+     */
+    getStorage() {
+        return this.storage;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory Function
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a VersionPolicyEngine instance.
+ */
+export function createVersionPolicyEngine(storage) {
+    return new VersionPolicyEngine(storage);
+}