@ekkos/cli 1.3.1 → 1.3.5

package/dist/local/offline-fallback.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Offline MCP Fallback
+ *
+ * When the remote API is unreachable, falls back to local SQLite.
+ * Transparent to callers — same interface, different backend.
+ *
+ * Tool coverage:
+ *   ekkOS_Search   → localStore.searchPatterns
+ *   ekkOS_Forge    → localStore.forgePattern
+ *   ekkOS_Track    → localStore.trackApplication
+ *   ekkOS_Outcome  → localStore.recordOutcome
+ *   ekkOS_Directive→ localStore.createDirective
+ *   ekkOS_Stats    → localStore.getStats
+ */
+declare const OFFLINE_CAPABLE_TOOLS: readonly ["ekkOS_Search", "ekkOS_Forge", "ekkOS_Track", "ekkOS_Outcome", "ekkOS_Directive", "ekkOS_Stats"];
+export interface ToolCallResult {
+    success: boolean;
+    data?: any;
+    error?: string;
+    /** Present when the call was served from local store rather than the cloud */
+    _degraded?: boolean;
+    /** Present when the call was served from local store */
+    _local?: boolean;
+}
+export type RemoteCallFn = () => Promise<any>;
+/**
+ * Attempt the remote MCP call. If it times out or throws, transparently fall
+ * back to the local SQLite store for supported tools.
+ *
+ * @param tool       - ekkOS tool name (e.g. 'ekkOS_Search')
+ * @param args       - Arguments to pass to the tool / local equivalent
+ * @param remoteCall - Zero-arg async function that performs the actual remote call
+ *
+ * @returns ToolCallResult with optional `_local: true` flag when served locally
+ */
+export declare function callWithFallback(tool: string, args: Record<string, any>, remoteCall: RemoteCallFn): Promise<ToolCallResult>;
+/**
+ * Convenience check: is the offline fallback layer ready to serve requests?
+ */
+export declare function isOfflineFallbackReady(): boolean;
+/**
+ * Exported constant for consumers that need to know which tools work offline.
+ */
+export { OFFLINE_CAPABLE_TOOLS };

package/dist/local/offline-fallback.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Offline MCP Fallback
+ *
+ * When the remote API is unreachable, falls back to local SQLite.
+ * Transparent to callers — same interface, different backend.
+ *
+ * Tool coverage:
+ *   ekkOS_Search   → localStore.searchPatterns
+ *   ekkOS_Forge    → localStore.forgePattern
+ *   ekkOS_Track    → localStore.trackApplication
+ *   ekkOS_Outcome  → localStore.recordOutcome
+ *   ekkOS_Directive→ localStore.createDirective
+ *   ekkOS_Stats    → localStore.getStats
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFFLINE_CAPABLE_TOOLS = void 0;
+exports.callWithFallback = callWithFallback;
+exports.isOfflineFallbackReady = isOfflineFallbackReady;
+const sqlite_store_1 = require("./sqlite-store");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MCP_TIMEOUT = 3000; // 3 seconds
+const OFFLINE_CAPABLE_TOOLS = [
+    'ekkOS_Search',
+    'ekkOS_Forge',
+    'ekkOS_Track',
+    'ekkOS_Outcome',
+    'ekkOS_Directive',
+    'ekkOS_Stats',
+];
+exports.OFFLINE_CAPABLE_TOOLS = OFFLINE_CAPABLE_TOOLS;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isOfflineCapable(tool) {
+    return OFFLINE_CAPABLE_TOOLS.includes(tool);
+}
+function withTimeout(promise, ms) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout after ${ms}ms`)), ms)),
+    ]);
+}
+// ---------------------------------------------------------------------------
+// Local tool dispatch
+// ---------------------------------------------------------------------------
+function dispatchLocal(tool, args) {
+    if (!sqlite_store_1.localStore.isAvailable()) {
+        return {
+            success: false,
+            error: 'Local store not available (better-sqlite3 not installed)',
+            _degraded: true,
+        };
+    }
+    try {
+        switch (tool) {
+            case 'ekkOS_Search': {
+                const { user_id, query, limit } = args;
+                const patterns = sqlite_store_1.localStore.searchPatterns(user_id, query, limit);
+                return {
+                    success: true,
+                    data: { patterns, source: 'local', total: patterns.length },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Forge': {
+                const { user_id, title, problem, solution, tags } = args;
+                const patternId = sqlite_store_1.localStore.forgePattern(user_id, { title, problem, solution, tags });
+                return {
+                    success: true,
+                    data: { pattern_id: patternId, source: 'local' },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Track': {
+                const { pattern_id } = args;
+                sqlite_store_1.localStore.trackApplication(pattern_id);
+                return { success: true, data: { tracked: true, source: 'local' }, _local: true };
+            }
+            case 'ekkOS_Outcome': {
+                const { pattern_id, success } = args;
+                sqlite_store_1.localStore.recordOutcome(pattern_id, success);
+                return { success: true, data: { recorded: true, source: 'local' }, _local: true };
+            }
+            case 'ekkOS_Directive': {
+                const { user_id, type, rule, reason, priority, scope } = args;
+                const id = sqlite_store_1.localStore.createDirective(user_id, { type, rule, reason, priority, scope });
+                return {
+                    success: true,
+                    data: { id, source: 'local' },
+                    _local: true,
+                };
+            }
+            case 'ekkOS_Stats': {
+                const { user_id } = args;
+                const stats = sqlite_store_1.localStore.getStats(user_id);
+                return { success: true, data: { ...stats, source: 'local' }, _local: true };
+            }
+            default: {
+                // TypeScript exhaustiveness guard — should never reach here
+                const _never = tool;
+                return {
+                    success: false,
+                    error: `Unknown offline-capable tool: ${_never}`,
+                    _degraded: true,
+                };
+            }
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `Local store error: ${err.message}`,
+            _degraded: true,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main export: callWithFallback
+// ---------------------------------------------------------------------------
+/**
+ * Attempt the remote MCP call. If it times out or throws, transparently fall
+ * back to the local SQLite store for supported tools.
+ *
+ * @param tool       - ekkOS tool name (e.g. 'ekkOS_Search')
+ * @param args       - Arguments to pass to the tool / local equivalent
+ * @param remoteCall - Zero-arg async function that performs the actual remote call
+ *
+ * @returns ToolCallResult with optional `_local: true` flag when served locally
+ */
+async function callWithFallback(tool, args, remoteCall) {
+    // Attempt remote call with timeout
+    try {
+        const data = await withTimeout(remoteCall(), MCP_TIMEOUT);
+        return { success: true, data };
+    }
+    catch (err) {
+        const reason = err.message;
+        // Check whether we can serve this tool locally
+        if (!isOfflineCapable(tool)) {
+            return {
+                success: false,
+                error: `Offline — tool not available locally (${reason})`,
+                _degraded: true,
+            };
+        }
+        // Log the fallback so callers / users are aware
+        console.warn(`[OfflineFallback] Remote call failed for ${tool} (${reason}) — using local store`);
+        return dispatchLocal(tool, args);
+    }
+}
+/**
+ * Convenience check: is the offline fallback layer ready to serve requests?
+ */
+function isOfflineFallbackReady() {
+    return sqlite_store_1.localStore.isAvailable();
+}

package/dist/local/sqlite-store.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Local SQLite Memory Store
+ *
+ * Provides offline-capable memory storage using SQLite with WAL mode.
+ * Mirrors the Supabase schema for seamless sync.
+ * Location: ~/.ekkos/memory.db
+ *
+ * Dependency: better-sqlite3
+ * Add to package.json: "better-sqlite3": "^9.4.0"
+ * Dev dep:             "@types/better-sqlite3": "^7.6.8"
+ */
+export interface Pattern {
+    pattern_id: string;
+    user_id: string;
+    title: string;
+    problem: string;
+    solution: string;
+    status: string;
+    applied_count: number;
+    success_rate: number;
+    tags: string[];
+    quarantined: boolean;
+    created_at: string;
+    updated_at: string;
+    synced_at: string | null;
+}
+export interface Directive {
+    id: string;
+    user_id: string;
+    type: 'MUST' | 'NEVER' | 'PREFER' | 'AVOID';
+    rule: string;
+    reason: string;
+    priority: number;
+    scope: string | null;
+    is_active: boolean;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface EpisodicMemory {
+    id: string;
+    user_id: string;
+    problem: string;
+    solution: string;
+    session_name: string | null;
+    quality_score: number;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface SyncQueueItem {
+    id: number;
+    table_name: string;
+    record_id: string;
+    operation: 'insert' | 'update' | 'delete';
+    payload: any;
+    created_at: string;
+    synced_at: string | null;
+}
+export interface StoreStats {
+    pattern_count: number;
+    active_pattern_count: number;
+    directive_count: number;
+    episodic_count: number;
+    pending_sync_count: number;
+    db_path: string;
+}
+export declare class LocalMemoryStore {
+    private db;
+    constructor();
+    private init;
+    private get database();
+    private migrate;
+    private rowToPattern;
+    private parseTags;
+    /**
+     * Full-text search across title, problem, solution, and tags using LIKE.
+     * Falls back gracefully when FTS5 is unavailable.
+     */
+    searchPatterns(userId: string, query: string, limit?: number): Pattern[];
+    /**
+     * Insert a new pattern and enqueue it for sync.
+     * Returns the generated pattern_id.
+     */
+    forgePattern(userId: string, input: {
+        title: string;
+        problem: string;
+        solution: string;
+        tags?: string[];
+    }): string;
+    /**
+     * Increment applied_count and mark as needing sync.
+     */
+    trackApplication(patternId: string): void;
+    /**
+     * Update success_rate using a weighted moving average and enqueue sync.
+     * Weight: 0.1 for new observation (exponential moving average).
+     */
+    recordOutcome(patternId: string, success: boolean): void;
+    /**
+     * Get active directives for a user, optionally filtered by type.
+     */
+    getDirectives(userId: string, types?: string[]): Directive[];
+    /**
+     * Insert a new directive and enqueue for sync.
+     * Returns the generated id.
+     */
+    createDirective(userId: string, input: {
+        type: string;
+        rule: string;
+        reason: string;
+        priority?: number;
+        scope?: string;
+    }): string;
+    /**
+     * Soft-delete a directive by setting is_active = 0.
+     */
+    deleteDirective(id: string): void;
+    private rowToDirective;
+    getStats(userId: string): StoreStats;
+    getPendingSync(): SyncQueueItem[];
+    markSynced(id: number): void;
+    getMeta(key: string): string | null;
+    setMeta(key: string, value: string): void;
+    private queueSync;
+    isAvailable(): boolean;
+}
+export declare const localStore: LocalMemoryStore;