@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/models.js

@@ -0,0 +1,8 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Sync Metadata (stored in description as HTML comment)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The key used to store sync metadata in status_log.
+ * Prefixed with underscore to indicate internal/system use.
+ */
+export const SYNC_METADATA_KEY = "_ema_sync";

package/dist/sdk/state.js

@@ -0,0 +1,88 @@
+import Database from "better-sqlite3";
+export class StateStore {
+    db;
+    mapTable = "persona_map_v2";
+    fpTable = "persona_fingerprint_v2";
+    runsTable = "sync_runs_v2";
+    constructor(path) {
+        this.db = new Database(path);
+        this.db.pragma("journal_mode = WAL");
+        this.migrate();
+    }
+    close() {
+        this.db.close();
+    }
+    migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.mapTable} (
+        master_env TEXT NOT NULL,
+        master_user_id TEXT NOT NULL,
+        master_persona_id TEXT NOT NULL,
+        target_env TEXT NOT NULL,
+        target_user_id TEXT NOT NULL,
+        target_persona_id TEXT NOT NULL,
+        PRIMARY KEY (master_env, master_user_id, master_persona_id, target_env, target_user_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ${this.fpTable} (
+        env TEXT NOT NULL,
+        env_user_id TEXT NOT NULL,
+        persona_id TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL,
+        PRIMARY KEY (env, env_user_id, persona_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS ${this.runsTable} (
+        id TEXT PRIMARY KEY,
+        master_env TEXT NOT NULL,
+        master_env_user_id TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        status TEXT NOT NULL,
+        error TEXT
+      );
+    `);
+    }
+    getMapping(args) {
+        const row = this.db
+            .prepare(`SELECT target_persona_id
+         FROM ${this.mapTable}
+         WHERE master_env = ? AND master_user_id = ? AND master_persona_id = ? AND target_env = ? AND target_user_id = ?`)
+            .get(args.masterEnv, args.masterUserId, args.masterPersonaId, args.targetEnv, args.targetUserId);
+        return row?.target_persona_id ?? null;
+    }
+    upsertMapping(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.mapTable} (master_env, master_user_id, master_persona_id, target_env, target_user_id, target_persona_id)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(master_env, master_user_id, master_persona_id, target_env, target_user_id)
+         DO UPDATE SET target_persona_id = excluded.target_persona_id`)
+            .run(row.master_env, row.master_user_id, row.master_persona_id, row.target_env, row.target_user_id, row.target_persona_id);
+    }
+    getFingerprint(args) {
+        const row = this.db
+            .prepare(`SELECT fingerprint FROM ${this.fpTable} WHERE env = ? AND env_user_id = ? AND persona_id = ?`)
+            .get(args.env, args.envUserId, args.personaId);
+        return row?.fingerprint ?? null;
+    }
+    upsertFingerprint(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.fpTable} (env, env_user_id, persona_id, fingerprint, last_seen_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(env, env_user_id, persona_id)
+         DO UPDATE SET fingerprint = excluded.fingerprint, last_seen_at = excluded.last_seen_at`)
+            .run(row.env, row.env_user_id, row.persona_id, row.fingerprint, row.last_seen_at);
+    }
+    beginRun(row) {
+        this.db
+            .prepare(`INSERT INTO ${this.runsTable} (id, master_env, master_env_user_id, started_at, status)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(row.id, row.master_env, row.master_env_user_id, row.started_at, row.status);
+    }
+    finishRun(args) {
+        this.db
+            .prepare(`UPDATE ${this.runsTable} SET finished_at = ?, status = ?, error = ? WHERE id = ?`)
+            .run(args.finishedAt, args.status, args.error ?? null, args.id);
+    }
+}

package/dist/sdk/sync-options.js

@@ -0,0 +1,216 @@
+/**
+ * Sync Options Configuration
+ *
+ * Hierarchical configuration for sync behavior, loaded from:
+ * 1. .ema.yaml in repo root (shared team defaults)
+ * 2. ~/.ema.yaml in user home (personal overrides)
+ * 3. Tool parameters (runtime overrides)
+ *
+ * Resolution order (lowest → highest priority):
+ * Built-in defaults → defaults → targets[env] → personas[name] → tool params
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import yaml from "js-yaml";
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema
+// ─────────────────────────────────────────────────────────────────────────────
+const SyncBehaviorSchema = z.object({
+    sync_status: z.boolean().optional(),
+    dry_run: z.boolean().optional(),
+}).strict();
+const RoutingRuleSchema = z.object({
+    match: z.object({
+        names: z.array(z.string()).optional().default([]),
+        ids: z.array(z.string()).optional().default([]),
+    }).strict(),
+    targets: z.array(z.string()).min(1),
+}).strict();
+const SyncOptionsConfigSchema = z.object({
+    defaults: SyncBehaviorSchema.optional().default({}),
+    targets: z.record(SyncBehaviorSchema).optional().default({}),
+    personas: z.record(SyncBehaviorSchema).optional().default({}),
+    routing: z.array(RoutingRuleSchema).optional().default([]),
+}).strict();
+// ─────────────────────────────────────────────────────────────────────────────
+// Built-in defaults
+// ─────────────────────────────────────────────────────────────────────────────
+const BUILTIN_DEFAULTS = {
+    sync_status: false,
+    dry_run: false,
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Config loading
+// ─────────────────────────────────────────────────────────────────────────────
+let cachedSyncOptions = null;
+function loadYamlFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        return yaml.load(content);
+    }
+    catch {
+        return null;
+    }
+}
+function findRepoRoot() {
+    // Start from current working directory and look for .git or package.json
+    let dir = process.cwd();
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, ".git")) || fs.existsSync(path.join(dir, "package.json"))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd();
+}
+/**
+ * Load and merge sync options from all config sources.
+ * Caches result for performance.
+ */
+export function loadSyncOptions() {
+    if (cachedSyncOptions)
+        return cachedSyncOptions;
+    const repoRoot = findRepoRoot();
+    const homeDir = os.homedir();
+    // Load from repo .ema.yaml
+    const repoConfigPath = path.join(repoRoot, ".ema.yaml");
+    const repoConfig = loadYamlFile(repoConfigPath);
+    // Load from ~/.ema.yaml
+    const userConfigPath = path.join(homeDir, ".ema.yaml");
+    const userConfig = loadYamlFile(userConfigPath);
+    // Merge configs (user overrides repo)
+    const merged = {
+        defaults: {},
+        targets: {},
+        personas: {},
+        routing: [],
+    };
+    // Apply repo config
+    if (repoConfig && typeof repoConfig === "object") {
+        const parsed = SyncOptionsConfigSchema.safeParse(repoConfig);
+        if (parsed.success) {
+            merged.defaults = { ...merged.defaults, ...parsed.data.defaults };
+            merged.targets = { ...merged.targets, ...parsed.data.targets };
+            merged.personas = { ...merged.personas, ...parsed.data.personas };
+            merged.routing = [...(parsed.data.routing ?? [])];
+        }
+    }
+    // Apply user config (overrides repo)
+    if (userConfig && typeof userConfig === "object") {
+        const parsed = SyncOptionsConfigSchema.safeParse(userConfig);
+        if (parsed.success) {
+            merged.defaults = { ...merged.defaults, ...parsed.data.defaults };
+            // Deep merge targets
+            for (const [env, behavior] of Object.entries(parsed.data.targets ?? {})) {
+                merged.targets[env] = { ...merged.targets[env], ...behavior };
+            }
+            // Deep merge personas
+            for (const [name, behavior] of Object.entries(parsed.data.personas ?? {})) {
+                merged.personas[name] = { ...merged.personas[name], ...behavior };
+            }
+            // Prepend user routing rules (higher priority)
+            merged.routing = [...(parsed.data.routing ?? []), ...merged.routing];
+        }
+    }
+    cachedSyncOptions = merged;
+    return merged;
+}
+/**
+ * Clear the cached sync options (for testing or config reload).
+ */
+export function clearSyncOptionsCache() {
+    cachedSyncOptions = null;
+}
+/**
+ * Resolve sync behavior for a specific persona and target environment.
+ *
+ * Resolution order (lowest → highest priority):
+ * 1. Built-in defaults
+ * 2. Config defaults
+ * 3. Config targets[targetEnv]
+ * 4. Config personas[personaName]
+ * 5. Runtime overrides (passed as parameter)
+ */
+export function resolveSyncBehavior(opts) {
+    const { personaName, targetEnv, overrides } = opts;
+    const config = loadSyncOptions();
+    // Start with built-in defaults
+    const resolved = { ...BUILTIN_DEFAULTS };
+    // Apply config defaults
+    if (config.defaults) {
+        if (config.defaults.sync_status !== undefined)
+            resolved.sync_status = config.defaults.sync_status;
+        if (config.defaults.dry_run !== undefined)
+            resolved.dry_run = config.defaults.dry_run;
+    }
+    // Apply target env overrides
+    const targetConfig = config.targets?.[targetEnv];
+    if (targetConfig) {
+        if (targetConfig.sync_status !== undefined)
+            resolved.sync_status = targetConfig.sync_status;
+        if (targetConfig.dry_run !== undefined)
+            resolved.dry_run = targetConfig.dry_run;
+    }
+    // Apply persona overrides
+    if (personaName) {
+        const personaConfig = config.personas?.[personaName];
+        if (personaConfig) {
+            if (personaConfig.sync_status !== undefined)
+                resolved.sync_status = personaConfig.sync_status;
+            if (personaConfig.dry_run !== undefined)
+                resolved.dry_run = personaConfig.dry_run;
+        }
+    }
+    // Apply runtime overrides
+    if (overrides) {
+        if (overrides.sync_status !== undefined)
+            resolved.sync_status = overrides.sync_status;
+        if (overrides.dry_run !== undefined)
+            resolved.dry_run = overrides.dry_run;
+    }
+    return resolved;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Routing
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Check if a string matches a glob pattern (simple implementation).
+ * Supports * as wildcard.
+ */
+function matchGlob(pattern, value) {
+    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+    return regex.test(value);
+}
+/**
+ * Get target environments for a persona based on routing rules.
+ */
+export function getRoutingTargets(personaName, personaId) {
+    const config = loadSyncOptions();
+    const targets = new Set();
+    for (const rule of config.routing ?? []) {
+        // Check name patterns
+        for (const pattern of rule.match.names ?? []) {
+            if (matchGlob(pattern, personaName)) {
+                rule.targets.forEach((t) => targets.add(t));
+                break;
+            }
+        }
+        // Check IDs
+        if (rule.match.ids?.includes(personaId)) {
+            rule.targets.forEach((t) => targets.add(t));
+        }
+    }
+    return [...targets];
+}
+/**
+ * Validate sync options config.
+ */
+export function validateSyncOptions(input) {
+    const result = SyncOptionsConfigSchema.safeParse(input);
+    if (!result.success) {
+        return { ok: false, errors: result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) };
+    }
+    return { ok: true, config: result.data };
+}

package/dist/sdk/sync.js

@@ -0,0 +1,220 @@
+/**
+ * Sync SDK - Programmatic interface for persona synchronization
+ */
+import { getMasterEnv, resolveBearerToken } from "./config.js";
+import { EmaClient } from "./client.js";
+import { StateStore } from "./state.js";
+import { fingerprintPersona, syncOnce } from "../sync.js";
+/**
+ * Sync SDK for programmatic access to persona synchronization
+ */
+export class SyncSDK {
+    config;
+    state;
+    clients = new Map();
+    constructor(config, options) {
+        this.config = {
+            ...config,
+            stateDbPath: options?.stateDbPath ?? config.stateDbPath ?? "./ema-agent-sync.sqlite3",
+            dryRun: options?.dryRun ?? config.dryRun ?? false,
+        };
+        this.state = new StateStore(this.config.stateDbPath);
+    }
+    getClient(envName) {
+        if (!this.clients.has(envName)) {
+            const envCfg = this.config.environments.find((e) => e.name === envName);
+            if (!envCfg)
+                throw new Error(`Environment not found: ${envName}`);
+            const env = {
+                name: envCfg.name,
+                baseUrl: envCfg.baseUrl,
+                bearerToken: resolveBearerToken(envCfg.bearerTokenEnv),
+            };
+            this.clients.set(envName, new EmaClient(env));
+        }
+        return this.clients.get(envName);
+    }
+    /**
+     * Get the master environment configuration
+     */
+    getMasterEnvironment() {
+        const master = getMasterEnv(this.config);
+        if (!master) {
+            throw new Error("No master environment configured (isMaster: true)");
+        }
+        return master;
+    }
+    /**
+     * Get all environment configurations
+     */
+    getEnvironments() {
+        return this.config.environments;
+    }
+    /**
+     * Run a full sync from master to all configured targets
+     */
+    async runSync() {
+        return syncOnce(this.config, this.state);
+    }
+    /**
+     * List all personas from the master environment
+     */
+    async listMasterPersonas() {
+        const master = this.getMasterEnvironment();
+        const client = this.getClient(master.name);
+        return client.getPersonasForTenant();
+    }
+    /**
+     * Get a specific persona by ID from the master environment
+     */
+    async getMasterPersona(personaId) {
+        const personas = await this.listMasterPersonas();
+        return personas.find((p) => p.id === personaId) ?? null;
+    }
+    /**
+     * Get a specific persona by name from the master environment
+     */
+    async getMasterPersonaByName(name) {
+        const personas = await this.listMasterPersonas();
+        return personas.find((p) => p.name === name) ?? null;
+    }
+    /**
+     * Get all persona mappings between master and target environments
+     */
+    getAllMappings() {
+        // Query all mappings from state store
+        const master = this.getMasterEnvironment();
+        const mappings = [];
+        // We need to expose a method to get all mappings from state
+        // For now, return empty - this would need state.ts enhancement
+        return mappings;
+    }
+    /**
+     * Get the target persona ID for a master persona in a specific environment
+     */
+    getTargetPersonaId(masterPersonaId, targetEnv) {
+        const master = this.getMasterEnvironment();
+        const targetCfg = this.config.environments.find((e) => e.name === targetEnv);
+        if (!targetCfg)
+            return null;
+        return this.state.getMapping({
+            masterEnv: master.name,
+            masterUserId: master.userId ?? master.name,
+            masterPersonaId,
+            targetEnv,
+            targetUserId: targetCfg.userId ?? targetCfg.name,
+        });
+    }
+    /**
+     * Get sync status for a specific persona
+     */
+    async getPersonaSyncStatus(personaId) {
+        const master = this.getMasterEnvironment();
+        const persona = await this.getMasterPersona(personaId);
+        if (!persona)
+            return null;
+        const fp = fingerprintPersona(persona);
+        const storedFp = this.state.getFingerprint({
+            env: master.name,
+            envUserId: master.userId ?? master.name,
+            personaId,
+        });
+        const targetMappings = [];
+        for (const env of this.config.environments) {
+            if (env.isMaster)
+                continue;
+            const targetId = this.state.getMapping({
+                masterEnv: master.name,
+                masterUserId: master.userId ?? master.name,
+                masterPersonaId: personaId,
+                targetEnv: env.name,
+                targetUserId: env.userId ?? env.name,
+            });
+            if (targetId) {
+                const targetFp = this.state.getFingerprint({
+                    env: env.name,
+                    envUserId: env.userId ?? env.name,
+                    personaId: targetId,
+                });
+                targetMappings.push({
+                    targetEnv: env.name,
+                    targetPersonaId: targetId,
+                    targetFingerprint: targetFp ?? undefined,
+                    inSync: targetFp === fp,
+                });
+            }
+        }
+        return {
+            personaId,
+            personaName: persona.name,
+            fingerprint: fp,
+            lastSeenAt: undefined, // Would need state enhancement to get this
+            isSynced: targetMappings.every((m) => m.inSync),
+            targetMappings,
+        };
+    }
+    /**
+     * Sync a specific persona by ID
+     */
+    async syncPersona(personaId) {
+        const persona = await this.getMasterPersona(personaId);
+        if (!persona) {
+            return { success: false, synced: [], errors: [`Persona not found: ${personaId}`] };
+        }
+        // Create a temporary config that only routes this persona
+        const tempConfig = {
+            ...this.config,
+            routing: [
+                {
+                    personaIds: [personaId],
+                    targetEnvs: this.config.environments
+                        .filter((e) => !e.isMaster)
+                        .map((e) => e.name),
+                },
+            ],
+        };
+        // Reuse existing state store to avoid SQLite lock contention
+        try {
+            const result = await syncOnce(tempConfig, this.state);
+            return {
+                success: result.synced > 0 || result.skipped > 0,
+                synced: result.synced > 0
+                    ? this.config.environments.filter((e) => !e.isMaster).map((e) => e.name)
+                    : [],
+                errors: [],
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                synced: [],
+                errors: [e instanceof Error ? e.message : String(e)],
+            };
+        }
+    }
+    /**
+     * Sync a specific persona by name
+     */
+    async syncPersonaByName(name) {
+        const persona = await this.getMasterPersonaByName(name);
+        if (!persona) {
+            return { success: false, synced: [], errors: [`Persona not found: ${name}`] };
+        }
+        const result = await this.syncPersona(persona.id);
+        return { ...result, personaId: persona.id };
+    }
+    /**
+     * Get recent sync runs
+     */
+    getRecentRuns(limit = 10) {
+        // Would need state.ts enhancement to query runs
+        return [];
+    }
+    /**
+     * Close all connections
+     */
+    close() {
+        this.state.close();
+        this.clients.clear();
+    }
+}