@qwickapps/qwickbrain-proxy 1.0.0

package/src/bin/cli.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createDatabase, runMigrations } from '../db/client.js';
+import { ProxyServer } from '../lib/proxy-server.js';
+import { ConfigSchema, type Config } from '../types/config.js';
+import { join } from 'path';
+import { homedir } from 'os';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { VERSION } from '../version.js';
+
+const DEFAULT_CONFIG_DIR = join(homedir(), '.qwickbrain');
+const DEFAULT_CONFIG_PATH = join(DEFAULT_CONFIG_DIR, 'config.json');
+
+function loadConfig(): Config {
+  if (!existsSync(DEFAULT_CONFIG_PATH)) {
+    return ConfigSchema.parse({});
+  }
+
+  try {
+    const raw = readFileSync(DEFAULT_CONFIG_PATH, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return ConfigSchema.parse(parsed);
+  } catch (error) {
+    console.error('Failed to load config:', error);
+    return ConfigSchema.parse({});
+  }
+}
+
+function saveConfig(config: Config): void {
+  mkdirSync(DEFAULT_CONFIG_DIR, { recursive: true });
+  writeFileSync(DEFAULT_CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+const program = new Command();
+
+program
+  .name('qwickbrain-proxy')
+  .description('Local MCP proxy for QwickBrain with caching and resilience')
+  .version(VERSION);
+
+program
+  .command('serve')
+  .description('Start the MCP proxy server (stdio mode)')
+  .action(async () => {
+    try {
+      const config = loadConfig();
+      const { db } = createDatabase(config.cache.dir);
+
+      // Run migrations to ensure database schema is up to date
+      try {
+        runMigrations(db);
+      } catch (migrationError) {
+        console.error('Failed to run database migrations:', migrationError);
+        console.error('Please ensure the database directory is writable and try again.');
+        process.exit(1);
+      }
+
+      const server = new ProxyServer(db, config);
+
+      process.on('SIGINT', async () => {
+        console.error('\nShutting down...');
+        await server.stop();
+        process.exit(0);
+      });
+
+      await server.start();
+    } catch (error) {
+      console.error('Failed to start server:', error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('init')
+  .description('Initialize configuration')
+  .action(async () => {
+    console.log('QwickBrain Proxy Configuration');
+    console.log('==============================\n');
+
+    // Simple init - create default config
+    const config = ConfigSchema.parse({
+      qwickbrain: {
+        url: 'http://macmini-devserver.local:3000',
+      },
+    });
+
+    saveConfig(config);
+    console.log(`Configuration saved to: ${DEFAULT_CONFIG_PATH}`);
+    console.log('\nDefault settings:');
+    console.log(`  QwickBrain URL: ${config.qwickbrain.url}`);
+    console.log(`  Cache directory: ${join(homedir(), '.qwickbrain', 'cache')}`);
+    console.log('\nTo customize, edit the config file or use "qwickbrain-proxy config" commands.');
+  });
+
+const configCmd = program.command('config').description('Manage configuration');
+
+configCmd
+  .command('get <key>')
+  .description('Get a configuration value')
+  .action((key) => {
+    const config = loadConfig();
+    const value = key.split('.').reduce((obj: any, k: string) => obj?.[k], config);
+    console.log(value !== undefined ? value : 'Not set');
+  });
+
+configCmd
+  .command('set <key> <value>')
+  .description('Set a configuration value')
+  .action((key, value) => {
+    const config = loadConfig();
+    const keys = key.split('.');
+    const lastKey = keys.pop()!;
+    const target = keys.reduce((obj: any, k: string) => {
+      if (!obj[k]) obj[k] = {};
+      return obj[k];
+    }, config);
+
+    // Try to parse as JSON, otherwise use as string
+    try {
+      target[lastKey] = JSON.parse(value);
+    } catch {
+      target[lastKey] = value;
+    }
+
+    // Validate against schema to prevent bypassing validation
+    try {
+      const validatedConfig = ConfigSchema.parse(config);
+      saveConfig(validatedConfig);
+      console.log(`Updated ${key} = ${value}`);
+    } catch (error) {
+      console.error('Configuration validation failed:', error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('show')
+  .description('Show current configuration')
+  .action(() => {
+    const config = loadConfig();
+    console.log(JSON.stringify(config, null, 2));
+  });
+
+program
+  .command('status')
+  .description('Show proxy status')
+  .action(() => {
+    const config = loadConfig();
+    console.log('QwickBrain Proxy Status');
+    console.log('======================\n');
+    console.log(`Config file: ${DEFAULT_CONFIG_PATH}`);
+    console.log(`Config exists: ${existsSync(DEFAULT_CONFIG_PATH) ? 'Yes' : 'No'}`);
+    console.log(`QwickBrain URL: ${config.qwickbrain.url}`);
+    console.log(`Cache directory: ${config.cache.dir || join(homedir(), '.qwickbrain', 'cache')}`);
+  });
+
+program.parse();

package/src/db/client.ts

@@ -0,0 +1,34 @@
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+import * as schema from './schema.js';
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync } from 'fs';
+
+const DEFAULT_CACHE_DIR = join(homedir(), '.qwickbrain', 'cache');
+
+export function createDatabase(cacheDir: string = DEFAULT_CACHE_DIR): {
+  db: ReturnType<typeof drizzle<typeof schema>>;
+  sqlite: Database.Database
+} {
+  // Ensure cache directory exists
+  mkdirSync(cacheDir, { recursive: true });
+
+  const dbPath = join(cacheDir, 'qwickbrain.db');
+  const sqlite = new Database(dbPath);
+
+  // Enable WAL mode for better concurrency
+  sqlite.pragma('journal_mode = WAL');
+
+  const db = drizzle(sqlite, { schema });
+
+  return { db, sqlite };
+}
+
+export function runMigrations(db: ReturnType<typeof drizzle>) {
+  // Drizzle will look for migrations in drizzle/ directory
+  migrate(db, { migrationsFolder: './drizzle' });
+}
+
+export type DB = ReturnType<typeof createDatabase>['db'];

package/src/db/schema.ts

@@ -0,0 +1,68 @@
+import { sql } from 'drizzle-orm';
+import { integer, sqliteTable, text, unique } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Cached documents (workflows, rules, FRDs, designs, etc.)
+ */
+export const documents = sqliteTable('documents', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  docType: text('doc_type').notNull(), // workflow, rule, frd, design, spike, etc.
+  name: text('name').notNull(),
+  project: text('project'), // null for global documents
+  content: text('content').notNull(),
+  metadata: text('metadata'), // JSON string
+  cachedAt: integer('cached_at', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  synced: integer('synced', { mode: 'boolean' }).notNull().default(true),
+}, (table) => ({
+  uniqueDocument: unique().on(table.docType, table.name, table.project),
+}));
+
+/**
+ * Cached memories (project context, patterns, decisions)
+ */
+export const memories = sqliteTable('memories', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  project: text('project'), // null for global memories
+  content: text('content').notNull(),
+  metadata: text('metadata'), // JSON string
+  cachedAt: integer('cached_at', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  synced: integer('synced', { mode: 'boolean' }).notNull().default(true),
+}, (table) => ({
+  uniqueMemory: unique().on(table.name, table.project),
+}));
+
+/**
+ * Write queue for offline operations
+ */
+export const syncQueue = sqliteTable('sync_queue', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  operation: text('operation').notNull(), // create_document, update_document, set_memory, etc.
+  payload: text('payload').notNull(), // JSON string
+  createdAt: integer('created_at', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+  status: text('status').notNull().default('pending'), // pending, completed, failed
+  error: text('error'),
+  attempts: integer('attempts').notNull().default(0),
+  lastAttemptAt: integer('last_attempt_at', { mode: 'timestamp' }),
+});
+
+/**
+ * Connection health log
+ */
+export const connectionLog = sqliteTable('connection_log', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  timestamp: integer('timestamp', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+  state: text('state').notNull(), // connected, disconnected, reconnecting, failed
+  latencyMs: integer('latency_ms'),
+  error: text('error'),
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+export { ProxyServer } from './lib/proxy-server.js';
+export { ConnectionManager } from './lib/connection-manager.js';
+export { CacheManager } from './lib/cache-manager.js';
+export { createDatabase, runMigrations } from './db/client.js';
+export type { Config } from './types/config.js';
+export type { MCPRequest, MCPResponse, ConnectionState } from './types/mcp.js';

package/src/lib/__tests__/cache-manager.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createDatabase, runMigrations } from '../../db/client.js';
+import { CacheManager } from '../cache-manager.js';
+import type { Config } from '../../types/config.js';
+
+describe('CacheManager', () => {
+  let tmpDir: string;
+  let cacheManager: CacheManager;
+  let db: ReturnType<typeof createDatabase>['db'];
+
+  beforeEach(() => {
+    // Create temporary directory for test database
+    tmpDir = mkdtempSync(join(tmpdir(), 'cache-test-'));
+    const dbResult = createDatabase(tmpDir);
+    db = dbResult.db;
+
+    // Run migrations to create tables
+    runMigrations(db);
+
+    const config: Config['cache'] = {
+      dir: tmpDir,
+      ttl: {
+        workflows: 3600,
+        rules: 3600,
+        documents: 1800,
+        memories: 900,
+      },
+      preload: [],
+    };
+
+    cacheManager = new CacheManager(db, config);
+  });
+
+  afterEach(() => {
+    // Clean up temporary directory
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('setDocument and getDocument', () => {
+    it('should store and retrieve a document', async () => {
+      await cacheManager.setDocument('workflow', 'test-workflow', 'content here');
+
+      const cached = await cacheManager.getDocument('workflow', 'test-workflow');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.data.content).toBe('content here');
+      expect(cached?.data.doc_type).toBe('workflow');
+      expect(cached?.data.name).toBe('test-workflow');
+      expect(cached?.isExpired).toBe(false);
+    });
+
+    it('should store document with metadata', async () => {
+      const metadata = { author: 'test', version: 1 };
+      await cacheManager.setDocument('frd', 'test-frd', 'frd content', undefined, metadata);
+
+      const cached = await cacheManager.getDocument('frd', 'test-frd');
+
+      expect(cached?.data.metadata).toEqual(metadata);
+    });
+
+    it('should store document with project scope', async () => {
+      await cacheManager.setDocument('design', 'test-design', 'design content', 'my-project');
+
+      const cached = await cacheManager.getDocument('design', 'test-design', 'my-project');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.data.project).toBe('my-project');
+    });
+
+    it('should distinguish between global and project-scoped documents', async () => {
+      await cacheManager.setDocument('rule', 'test-rule', 'global rule');
+      await cacheManager.setDocument('rule', 'test-rule', 'project rule', 'my-project');
+
+      const globalDoc = await cacheManager.getDocument('rule', 'test-rule');
+      const projectDoc = await cacheManager.getDocument('rule', 'test-rule', 'my-project');
+
+      expect(globalDoc?.data.content).toBe('global rule');
+      expect(globalDoc?.data.project).toBe('');
+      expect(projectDoc?.data.content).toBe('project rule');
+      expect(projectDoc?.data.project).toBe('my-project');
+    });
+
+    it('should return null for non-existent document', async () => {
+      const cached = await cacheManager.getDocument('workflow', 'non-existent');
+      expect(cached).toBeNull();
+    });
+
+    it('should update existing document on conflict', async () => {
+      await cacheManager.setDocument('workflow', 'test', 'version 1');
+      await cacheManager.setDocument('workflow', 'test', 'version 2');
+
+      const cached = await cacheManager.getDocument('workflow', 'test');
+
+      expect(cached?.data.content).toBe('version 2');
+    });
+
+    it('should mark document as expired after TTL', async () => {
+      // Override config to have very short TTL for testing
+      const shortTTLConfig: Config['cache'] = {
+        dir: tmpDir,
+        ttl: {
+          workflows: 0, // Expire immediately
+          rules: 0,
+          documents: 0,
+          memories: 0,
+        },
+        preload: [],
+      };
+
+      const shortCacheManager = new CacheManager(db, shortTTLConfig);
+      await shortCacheManager.setDocument('workflow', 'test', 'content');
+
+      // Wait to ensure timestamp difference
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const cached = await shortCacheManager.getDocument('workflow', 'test');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.isExpired).toBe(true);
+    });
+  });
+
+  describe('setMemory and getMemory', () => {
+    it('should store and retrieve a memory', async () => {
+      await cacheManager.setMemory('test-memory', 'memory content');
+
+      const cached = await cacheManager.getMemory('test-memory');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.data.content).toBe('memory content');
+      expect(cached?.data.name).toBe('test-memory');
+      expect(cached?.isExpired).toBe(false);
+    });
+
+    it('should store memory with metadata', async () => {
+      const metadata = { lastUpdated: Date.now() };
+      await cacheManager.setMemory('test-memory', 'content', undefined, metadata);
+
+      const cached = await cacheManager.getMemory('test-memory');
+
+      expect(cached?.data.metadata).toEqual(metadata);
+    });
+
+    it('should store memory with project scope', async () => {
+      await cacheManager.setMemory('patterns', 'project patterns', 'my-project');
+
+      const cached = await cacheManager.getMemory('patterns', 'my-project');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.data.project).toBe('my-project');
+    });
+
+    it('should distinguish between global and project-scoped memories', async () => {
+      await cacheManager.setMemory('context', 'global context');
+      await cacheManager.setMemory('context', 'project context', 'my-project');
+
+      const globalMem = await cacheManager.getMemory('context');
+      const projectMem = await cacheManager.getMemory('context', 'my-project');
+
+      expect(globalMem?.data.content).toBe('global context');
+      expect(projectMem?.data.content).toBe('project context');
+    });
+
+    it('should return null for non-existent memory', async () => {
+      const cached = await cacheManager.getMemory('non-existent');
+      expect(cached).toBeNull();
+    });
+
+    it('should mark memory as expired after TTL', async () => {
+      const shortTTLConfig: Config['cache'] = {
+        dir: tmpDir,
+        ttl: {
+          workflows: 0,
+          rules: 0,
+          documents: 0,
+          memories: 0,
+        },
+        preload: [],
+      };
+
+      const shortCacheManager = new CacheManager(db, shortTTLConfig);
+      await shortCacheManager.setMemory('test', 'content');
+
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const cached = await shortCacheManager.getMemory('test');
+
+      expect(cached).not.toBeNull();
+      expect(cached?.isExpired).toBe(true);
+    });
+  });
+
+  describe('cleanupExpiredEntries', () => {
+    it('should delete expired documents and memories', async () => {
+      const shortTTLConfig: Config['cache'] = {
+        dir: tmpDir,
+        ttl: {
+          workflows: 0,
+          rules: 0,
+          documents: 0,
+          memories: 0,
+        },
+        preload: [],
+      };
+
+      const shortCacheManager = new CacheManager(db, shortTTLConfig);
+
+      // Add some items that will immediately expire
+      await shortCacheManager.setDocument('workflow', 'test1', 'content1');
+      await shortCacheManager.setDocument('rule', 'test2', 'content2');
+      await shortCacheManager.setMemory('memory1', 'content3');
+
+      // Wait to ensure they're expired (need sufficient time for clock to advance)
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // Clean up
+      const result = await shortCacheManager.cleanupExpiredEntries();
+
+      expect(result.documentsDeleted).toBe(2);
+      expect(result.memoriesDeleted).toBe(1);
+
+      // Verify they're gone
+      const doc1 = await shortCacheManager.getDocument('workflow', 'test1');
+      const mem1 = await shortCacheManager.getMemory('memory1');
+
+      expect(doc1).toBeNull();
+      expect(mem1).toBeNull();
+    });
+
+    it('should not delete non-expired items', async () => {
+      await cacheManager.setDocument('workflow', 'test', 'content');
+      await cacheManager.setMemory('memory', 'content');
+
+      const result = await cacheManager.cleanupExpiredEntries();
+
+      expect(result.documentsDeleted).toBe(0);
+      expect(result.memoriesDeleted).toBe(0);
+
+      // Verify they're still there
+      const doc = await cacheManager.getDocument('workflow', 'test');
+      const mem = await cacheManager.getMemory('memory');
+
+      expect(doc).not.toBeNull();
+      expect(mem).not.toBeNull();
+    });
+  });
+
+  describe('cache age calculation', () => {
+    it('should calculate age correctly', async () => {
+      await cacheManager.setDocument('workflow', 'test', 'content');
+
+      // Wait 100ms
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const cached = await cacheManager.getDocument('workflow', 'test');
+
+      expect(cached?.age).toBeGreaterThanOrEqual(0);
+      expect(cached?.age).toBeLessThan(1); // Less than 1 second
+    });
+  });
+});