@ema.co/mcp-toolkit 0.2.3 → 0.3.0

package/dist/sdk/version-storage.js

@@ -0,0 +1,465 @@
+/**
+ * Persona Version Storage - Git-backed Local Storage
+ *
+ * Provides file-based storage for version snapshots with content-addressed
+ * blob storage for deduplication.
+ *
+ * Directory structure:
+ * .ema-versions/
+ * ├── config.yaml                    # Global version tracking config
+ * ├── policies/
+ * │   └── {persona_id}.yaml          # Per-persona policies
+ * ├── snapshots/
+ * │   └── {persona_id}/
+ * │       ├── manifest.json          # Index of all versions
+ * │       ├── v001.json              # Full snapshot
+ * │       └── latest.json            # Copy of latest (for quick access)
+ * └── blobs/                         # Content-addressed storage
+ *     └── {content_hash}.json        # Deduplicated snapshot content
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { nowIso } from "./version-tracking.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const DEFAULT_BASE_DIR = ".ema-versions";
+const SNAPSHOTS_DIR = "snapshots";
+const BLOBS_DIR = "blobs";
+const POLICIES_DIR = "policies";
+const CONFIG_FILE = "config.yaml";
+const MANIFEST_FILE = "manifest.json";
+const LATEST_FILE = "latest.json";
+const DEFAULT_CONFIG = {
+    default_auto_version_on_deploy: true,
+    default_auto_version_on_sync: true,
+    default_max_versions: 50,
+    default_prune_strategy: "oldest",
+    enable_blob_dedup: true,
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Version Storage Class
+// ─────────────────────────────────────────────────────────────────────────────
+export class VersionStorage {
+    baseDir;
+    config;
+    constructor(workspaceRoot, baseDir) {
+        this.baseDir = path.join(workspaceRoot, baseDir ?? DEFAULT_BASE_DIR);
+        this.config = DEFAULT_CONFIG;
+        this.ensureDirectories();
+        this.loadConfig();
+    }
+    // ─────────────── Directory Management ───────────────
+    ensureDirectories() {
+        const dirs = [
+            this.baseDir,
+            path.join(this.baseDir, SNAPSHOTS_DIR),
+            path.join(this.baseDir, BLOBS_DIR),
+            path.join(this.baseDir, POLICIES_DIR),
+        ];
+        for (const dir of dirs) {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
+    }
+    getSnapshotDir(personaId) {
+        return path.join(this.baseDir, SNAPSHOTS_DIR, personaId);
+    }
+    ensurePersonaDir(personaId) {
+        const dir = this.getSnapshotDir(personaId);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    // ─────────────── Config Management ───────────────
+    loadConfig() {
+        const configPath = path.join(this.baseDir, CONFIG_FILE);
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, "utf8");
+                // Simple YAML parsing for flat config (avoids dependency)
+                const parsed = this.parseSimpleYaml(content);
+                this.config = { ...DEFAULT_CONFIG, ...parsed };
+            }
+            catch {
+                // Use defaults on error
+            }
+        }
+    }
+    parseSimpleYaml(content) {
+        const result = {};
+        const lines = content.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const colonIdx = trimmed.indexOf(":");
+            if (colonIdx === -1)
+                continue;
+            const key = trimmed.slice(0, colonIdx).trim();
+            let value = trimmed.slice(colonIdx + 1).trim();
+            // Type coercion
+            if (value === "true")
+                value = true;
+            else if (value === "false")
+                value = false;
+            else if (/^\d+$/.test(value))
+                value = parseInt(value, 10);
+            result[key] = value;
+        }
+        return result;
+    }
+    saveConfig() {
+        const configPath = path.join(this.baseDir, CONFIG_FILE);
+        const lines = [
+            "# Ema Version Tracking Configuration",
+            `default_auto_version_on_deploy: ${this.config.default_auto_version_on_deploy}`,
+            `default_auto_version_on_sync: ${this.config.default_auto_version_on_sync}`,
+            `default_max_versions: ${this.config.default_max_versions}`,
+            `default_prune_strategy: ${this.config.default_prune_strategy}`,
+            `enable_blob_dedup: ${this.config.enable_blob_dedup}`,
+        ];
+        fs.writeFileSync(configPath, lines.join("\n") + "\n");
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        this.saveConfig();
+    }
+    // ─────────────── Manifest Management ───────────────
+    getManifestPath(personaId) {
+        return path.join(this.getSnapshotDir(personaId), MANIFEST_FILE);
+    }
+    getManifest(personaId) {
+        const manifestPath = this.getManifestPath(personaId);
+        if (!fs.existsSync(manifestPath)) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(manifestPath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    saveManifest(personaId, manifest) {
+        this.ensurePersonaDir(personaId);
+        const manifestPath = this.getManifestPath(personaId);
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    }
+    createEmptyManifest(personaId, environment) {
+        return {
+            persona_id: personaId,
+            environment,
+            latest_version_id: null,
+            latest_version_number: 0,
+            versions: [],
+            updated_at: nowIso(),
+        };
+    }
+    // ─────────────── Blob Storage ───────────────
+    getBlobPath(contentHash) {
+        return path.join(this.baseDir, BLOBS_DIR, `${contentHash}.json`);
+    }
+    saveBlob(contentHash, snapshot) {
+        const blobPath = this.getBlobPath(contentHash);
+        if (!fs.existsSync(blobPath)) {
+            fs.writeFileSync(blobPath, JSON.stringify(snapshot, null, 2));
+        }
+    }
+    loadBlob(contentHash) {
+        const blobPath = this.getBlobPath(contentHash);
+        if (!fs.existsSync(blobPath)) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(blobPath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    // ─────────────── Version Snapshot Storage ───────────────
+    getVersionPath(personaId, versionNumber) {
+        const paddedNum = String(versionNumber).padStart(3, "0");
+        return path.join(this.getSnapshotDir(personaId), `v${paddedNum}.json`);
+    }
+    getLatestPath(personaId) {
+        return path.join(this.getSnapshotDir(personaId), LATEST_FILE);
+    }
+    /**
+     * Save a version snapshot to storage.
+     */
+    saveVersion(version) {
+        this.ensurePersonaDir(version.persona_id);
+        // Save blob if dedup enabled
+        if (this.config.enable_blob_dedup) {
+            this.saveBlob(version.content_hash, version.snapshot);
+        }
+        // Save full version snapshot
+        const versionPath = this.getVersionPath(version.persona_id, version.version_number);
+        fs.writeFileSync(versionPath, JSON.stringify(version, null, 2));
+        // Update latest
+        const latestPath = this.getLatestPath(version.persona_id);
+        fs.writeFileSync(latestPath, JSON.stringify(version, null, 2));
+        // Update manifest
+        let manifest = this.getManifest(version.persona_id);
+        if (!manifest) {
+            manifest = this.createEmptyManifest(version.persona_id, version.environment);
+        }
+        const entry = {
+            id: version.id,
+            version_number: version.version_number,
+            version_name: version.version_name,
+            content_hash: version.content_hash,
+            created_at: version.created_at,
+            created_by: version.created_by,
+            trigger: version.trigger,
+            message: version.message,
+            parent_version_id: version.parent_version_id,
+        };
+        manifest.versions.push(entry);
+        manifest.latest_version_id = version.id;
+        manifest.latest_version_number = version.version_number;
+        manifest.updated_at = nowIso();
+        this.saveManifest(version.persona_id, manifest);
+    }
+    /**
+     * Get a specific version by number.
+     */
+    getVersion(personaId, versionNumber) {
+        const versionPath = this.getVersionPath(personaId, versionNumber);
+        if (!fs.existsSync(versionPath)) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(versionPath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get a version by ID.
+     */
+    getVersionById(personaId, versionId) {
+        const manifest = this.getManifest(personaId);
+        if (!manifest)
+            return null;
+        const entry = manifest.versions.find((v) => v.id === versionId);
+        if (!entry)
+            return null;
+        return this.getVersion(personaId, entry.version_number);
+    }
+    /**
+     * Get a version by name (e.g., "v3", "latest").
+     */
+    getVersionByName(personaId, versionName) {
+        if (versionName === "latest") {
+            return this.getLatestVersion(personaId);
+        }
+        const manifest = this.getManifest(personaId);
+        if (!manifest)
+            return null;
+        const entry = manifest.versions.find((v) => v.version_name === versionName);
+        if (!entry)
+            return null;
+        return this.getVersion(personaId, entry.version_number);
+    }
+    /**
+     * Get the latest version.
+     */
+    getLatestVersion(personaId) {
+        const latestPath = this.getLatestPath(personaId);
+        if (!fs.existsSync(latestPath)) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(latestPath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all versions for a persona (from manifest).
+     */
+    listVersions(personaId) {
+        const manifest = this.getManifest(personaId);
+        return manifest?.versions ?? [];
+    }
+    /**
+     * Check if a content hash already exists (for deduplication).
+     */
+    hasContentHash(personaId, contentHash) {
+        const manifest = this.getManifest(personaId);
+        if (!manifest)
+            return false;
+        return manifest.versions.some((v) => v.content_hash === contentHash);
+    }
+    /**
+     * Get the next version number for a persona.
+     */
+    getNextVersionNumber(personaId) {
+        const manifest = this.getManifest(personaId);
+        return (manifest?.latest_version_number ?? 0) + 1;
+    }
+    // ─────────────── Policy Management ───────────────
+    getPolicyPath(personaId) {
+        return path.join(this.baseDir, POLICIES_DIR, `${personaId}.yaml`);
+    }
+    getPolicy(personaId) {
+        const policyPath = this.getPolicyPath(personaId);
+        if (fs.existsSync(policyPath)) {
+            try {
+                const content = fs.readFileSync(policyPath, "utf8");
+                const parsed = this.parseSimpleYaml(content);
+                return {
+                    persona_id: personaId,
+                    auto_version_on_deploy: parsed.auto_version_on_deploy ?? this.config.default_auto_version_on_deploy,
+                    auto_version_on_sync: parsed.auto_version_on_sync ?? this.config.default_auto_version_on_sync,
+                    max_versions: parsed.max_versions ?? this.config.default_max_versions,
+                    prune_strategy: parsed.prune_strategy ?? this.config.default_prune_strategy,
+                    min_interval: parsed.min_interval,
+                };
+            }
+            catch {
+                // Return defaults on error
+            }
+        }
+        // Return default policy
+        return {
+            persona_id: personaId,
+            auto_version_on_deploy: this.config.default_auto_version_on_deploy,
+            auto_version_on_sync: this.config.default_auto_version_on_sync,
+            max_versions: this.config.default_max_versions,
+            prune_strategy: this.config.default_prune_strategy,
+        };
+    }
+    savePolicy(policy) {
+        const policyPath = this.getPolicyPath(policy.persona_id);
+        const lines = [
+            `# Version policy for persona ${policy.persona_id}`,
+            `auto_version_on_deploy: ${policy.auto_version_on_deploy}`,
+            `auto_version_on_sync: ${policy.auto_version_on_sync}`,
+            `max_versions: ${policy.max_versions}`,
+            `prune_strategy: ${policy.prune_strategy}`,
+        ];
+        if (policy.min_interval) {
+            lines.push(`min_interval: ${policy.min_interval}`);
+        }
+        fs.writeFileSync(policyPath, lines.join("\n") + "\n");
+    }
+    // ─────────────── Pruning ───────────────
+    /**
+     * Prune old versions according to policy.
+     * Returns the number of versions pruned.
+     */
+    pruneVersions(personaId) {
+        const policy = this.getPolicy(personaId);
+        if (policy.max_versions === 0) {
+            return 0; // Unlimited
+        }
+        const manifest = this.getManifest(personaId);
+        if (!manifest || manifest.versions.length <= policy.max_versions) {
+            return 0;
+        }
+        // Sort by version number (ascending)
+        const sorted = [...manifest.versions].sort((a, b) => a.version_number - b.version_number);
+        // Determine which to keep
+        let toKeep;
+        if (policy.prune_strategy === "keep_tagged") {
+            // Keep tagged versions (those with custom names or non-empty messages)
+            const tagged = sorted.filter((v) => !v.version_name.match(/^v\d+$/) || v.message.trim().length > 0);
+            const untagged = sorted.filter((v) => v.version_name.match(/^v\d+$/) && v.message.trim().length === 0);
+            // Keep all tagged + most recent untagged up to limit
+            const keepCount = Math.max(0, policy.max_versions - tagged.length);
+            toKeep = [...tagged, ...untagged.slice(-keepCount)];
+        }
+        else {
+            // Keep newest
+            toKeep = sorted.slice(-policy.max_versions);
+        }
+        const keepIds = new Set(toKeep.map((v) => v.id));
+        const toDelete = sorted.filter((v) => !keepIds.has(v.id));
+        // Delete version files
+        for (const v of toDelete) {
+            const versionPath = this.getVersionPath(personaId, v.version_number);
+            if (fs.existsSync(versionPath)) {
+                fs.unlinkSync(versionPath);
+            }
+        }
+        // Update manifest
+        manifest.versions = toKeep.sort((a, b) => a.version_number - b.version_number);
+        manifest.updated_at = nowIso();
+        this.saveManifest(personaId, manifest);
+        return toDelete.length;
+    }
+    // ─────────────── Utilities ───────────────
+    /**
+     * List all personas that have version history.
+     */
+    listPersonasWithVersions() {
+        const snapshotsDir = path.join(this.baseDir, SNAPSHOTS_DIR);
+        if (!fs.existsSync(snapshotsDir)) {
+            return [];
+        }
+        return fs
+            .readdirSync(snapshotsDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    /**
+     * Get storage statistics.
+     */
+    getStats() {
+        const personas = this.listPersonasWithVersions();
+        let totalVersions = 0;
+        let storageBytes = 0;
+        for (const personaId of personas) {
+            const manifest = this.getManifest(personaId);
+            if (manifest) {
+                totalVersions += manifest.versions.length;
+            }
+        }
+        // Count blobs
+        const blobsDir = path.join(this.baseDir, BLOBS_DIR);
+        let totalBlobs = 0;
+        if (fs.existsSync(blobsDir)) {
+            const blobs = fs.readdirSync(blobsDir);
+            totalBlobs = blobs.length;
+            for (const blob of blobs) {
+                const stat = fs.statSync(path.join(blobsDir, blob));
+                storageBytes += stat.size;
+            }
+        }
+        return {
+            total_personas: personas.length,
+            total_versions: totalVersions,
+            total_blobs: totalBlobs,
+            storage_bytes: storageBytes,
+        };
+    }
+    /**
+     * Get the base directory path.
+     */
+    getBaseDir() {
+        return this.baseDir;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory Function
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a VersionStorage instance.
+ */
+export function createVersionStorage(workspaceRoot, baseDir) {
+    return new VersionStorage(workspaceRoot, baseDir);
+}