@prmichaelsen/remember-mcp 0.1.0

package/agent/tasks/task-3-setup-weaviate-client.md

@@ -0,0 +1,330 @@
+# Task 3: Set Up Weaviate Client
+
+**Milestone**: M1 - Project Foundation
+**Estimated Time**: 3 hours
+**Dependencies**: Task 2 ✅
+**Status**: ✅ COMPLETED (2026-02-11)
+
+---
+
+## Objective
+
+Create Weaviate client wrapper with connection management and user-scoped collection handling.
+
+---
+
+## Steps
+
+### 1. Create Weaviate Client Wrapper
+
+**src/weaviate/client.ts**:
+```typescript
+import weaviate, { WeaviateClient, ApiKey } from 'weaviate-client';
+import { config } from '../config.js';
+
+let client: WeaviateClient | null = null;
+
+/**
+ * Initialize Weaviate client
+ */
+export async function initWeaviateClient(): Promise<WeaviateClient> {
+  if (client) {
+    return client;
+  }
+
+  const clientConfig: any = {
+    scheme: config.weaviate.url.startsWith('https') ? 'https' : 'http',
+    host: config.weaviate.url.replace(/^https?:\/\//, ''),
+  };
+
+  if (config.weaviate.apiKey) {
+    clientConfig.apiKey = new ApiKey(config.weaviate.apiKey);
+  }
+
+  client = await weaviate.client(clientConfig);
+
+  console.log('[Weaviate] Client initialized');
+  return client;
+}
+
+/**
+ * Get Weaviate client instance
+ */
+export function getWeaviateClient(): WeaviateClient {
+  if (!client) {
+    throw new Error('Weaviate client not initialized. Call initWeaviateClient() first.');
+  }
+  return client;
+}
+
+/**
+ * Test Weaviate connection
+ */
+export async function testWeaviateConnection(): Promise<boolean> {
+  try {
+    const client = getWeaviateClient();
+    const meta = await client.misc.metaGetter().do();
+    console.log('[Weaviate] Connection successful:', meta.version);
+    return true;
+  } catch (error) {
+    console.error('[Weaviate] Connection failed:', error);
+    return false;
+  }
+}
+
+/**
+ * Sanitize user_id for collection name
+ * Weaviate collection names must start with uppercase and contain only alphanumeric
+ */
+export function sanitizeUserId(userId: string): string {
+  // Remove special characters, keep alphanumeric
+  const sanitized = userId.replace(/[^a-zA-Z0-9]/g, '_');
+  // Ensure starts with uppercase
+  return sanitized.charAt(0).toUpperCase() + sanitized.slice(1);
+}
+
+/**
+ * Get collection name for user's memories
+ */
+export function getMemoryCollectionName(userId: string): string {
+  return `Memory_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Get collection name for user's templates
+ */
+export function getTemplateCollectionName(userId: string): string {
+  return `Template_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Get collection name for user's audit logs
+ */
+export function getAuditCollectionName(userId: string): string {
+  return `Audit_${sanitizeUserId(userId)}`;
+}
+
+/**
+ * Check if collection exists
+ */
+export async function collectionExists(collectionName: string): Promise<boolean> {
+  try {
+    const client = getWeaviateClient();
+    const schema = await client.schema.getter().do();
+    return schema.classes?.some((c: any) => c.class === collectionName) ?? false;
+  } catch (error) {
+    console.error(`[Weaviate] Error checking collection ${collectionName}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Close Weaviate client connection
+ */
+export async function closeWeaviateClient(): Promise<void> {
+  if (client) {
+    // Weaviate client doesn't have explicit close method
+    client = null;
+    console.log('[Weaviate] Client closed');
+  }
+}
+```
+
+### 2. Create Configuration Module
+
+**src/config.ts**:
+```typescript
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const config = {
+  // Weaviate
+  weaviate: {
+    url: process.env.WEAVIATE_URL || 'http://localhost:8080',
+    apiKey: process.env.WEAVIATE_API_KEY || '',
+  },
+
+  // OpenAI
+  openai: {
+    apiKey: process.env.OPENAI_APIKEY || '',
+  },
+
+  // Firebase
+  firebase: {
+    projectId: process.env.FIREBASE_PROJECT_ID || '',
+    credentialsPath: process.env.GOOGLE_APPLICATION_CREDENTIALS || './serviceAccount.json',
+  },
+
+  // Server
+  server: {
+    port: parseInt(process.env.PORT || '3000', 10),
+    nodeEnv: process.env.NODE_ENV || 'development',
+    logLevel: process.env.LOG_LEVEL || 'info',
+  },
+
+  // MCP
+  mcp: {
+    transport: process.env.MCP_TRANSPORT || 'sse',
+  },
+} as const;
+
+/**
+ * Validate required configuration
+ */
+export function validateConfig(): void {
+  const required = [
+    { key: 'WEAVIATE_URL', value: config.weaviate.url },
+    { key: 'OPENAI_APIKEY', value: config.openai.apiKey },
+    { key: 'FIREBASE_PROJECT_ID', value: config.firebase.projectId },
+  ];
+
+  const missing = required.filter((r) => !r.value);
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missing.map((m) => m.key).join(', ')}`
+    );
+  }
+
+  console.log('[Config] Configuration validated');
+}
+```
+
+### 3. Create Logger Utility
+
+**src/utils/logger.ts**:
+```typescript
+import { config } from '../config.js';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const currentLevel = LOG_LEVELS[config.server.logLevel as LogLevel] ?? LOG_LEVELS.info;
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= currentLevel;
+}
+
+export const logger = {
+  debug: (message: string, ...args: any[]) => {
+    if (shouldLog('debug')) {
+      console.debug(`[DEBUG] ${message}`, ...args);
+    }
+  },
+
+  info: (message: string, ...args: any[]) => {
+    if (shouldLog('info')) {
+      console.info(`[INFO] ${message}`, ...args);
+    }
+  },
+
+  warn: (message: string, ...args: any[]) => {
+    if (shouldLog('warn')) {
+      console.warn(`[WARN] ${message}`, ...args);
+    }
+  },
+
+  error: (message: string, ...args: any[]) => {
+    if (shouldLog('error')) {
+      console.error(`[ERROR] ${message}`, ...args);
+    }
+  },
+};
+```
+
+### 4. Create Test File
+
+**tests/unit/weaviate-client.test.ts**:
+```typescript
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  initWeaviateClient,
+  testWeaviateConnection,
+  sanitizeUserId,
+  getMemoryCollectionName,
+} from '../../src/weaviate/client.js';
+
+describe('Weaviate Client', () => {
+  beforeAll(async () => {
+    await initWeaviateClient();
+  });
+
+  it('should initialize client', async () => {
+    const result = await testWeaviateConnection();
+    expect(result).toBe(true);
+  });
+
+  it('should sanitize user IDs', () => {
+    expect(sanitizeUserId('user@example.com')).toBe('User_example_com');
+    expect(sanitizeUserId('user-123')).toBe('User_123');
+    expect(sanitizeUserId('123user')).toBe('_23user');
+  });
+
+  it('should generate collection names', () => {
+    expect(getMemoryCollectionName('user123')).toBe('Memory_User123');
+    expect(getMemoryCollectionName('user@test.com')).toBe('Memory_User_test_com');
+  });
+});
+```
+
+---
+
+## Verification
+
+- [x] src/weaviate/client.ts created
+- [x] src/config.ts created
+- [x] src/utils/logger.ts created
+- [x] Tests created (tests/unit/weaviate-client.test.ts)
+- [x] Can initialize Weaviate client (with Weaviate v3 API)
+- [x] Connection test implemented (skipped - requires Weaviate instance)
+- [x] User ID sanitization works (7/7 tests passing)
+- [x] Collection name generation works (all tests passing)
+- [x] Jest configured for ESM support
+
+## Completion Notes
+
+**Completed**: 2026-02-11
+
+**What Was Created**:
+- ✅ [`src/config.ts`](../../src/config.ts) - Configuration management with environment variables
+- ✅ [`src/utils/logger.ts`](../../src/utils/logger.ts) - Logging utility with log levels
+- ✅ [`src/weaviate/client.ts`](../../src/weaviate/client.ts) - Weaviate client wrapper with:
+  - Client initialization using Weaviate v3 API
+  - Connection testing
+  - User ID sanitization for collection names
+  - Collection name generators (Memory, Template, Audit)
+  - Collection existence checking
+- ✅ [`tests/unit/weaviate-client.test.ts`](../../tests/unit/weaviate-client.test.ts) - Unit tests (7 passing, 1 skipped)
+- ✅ Updated [`jest.config.js`](../../jest.config.js) for ESM support
+
+**Test Results**: 7 passed, 1 skipped (connection test requires Weaviate instance)
+
+**What's Next**:
+- Task 4: Set up Firestore client wrapper
+
+---
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Test connection manually
+npm run dev
+# Should see: [Weaviate] Client initialized
+# Should see: [Weaviate] Connection successful
+```
+
+---
+
+## Next Task
+
+Task 4: Set Up Firestore Client

package/agent/tasks/task-4-setup-firestore-client.md

@@ -0,0 +1,362 @@
+# Task 4: Set Up Firestore Client
+
+**Milestone**: M1 - Project Foundation
+**Estimated Time**: 2 hours
+**Dependencies**: Task 2 ✅
+**Status**: ✅ COMPLETED (2026-02-11)
+
+---
+
+## Objective
+
+Create Firestore initialization helper and path utilities using firebase-admin-sdk-v8 (service layer pattern, no wrapper needed per design decision in [`agent/design/firestore-wrapper-analysis.md`](../../agent/design/firestore-wrapper-analysis.md)).
+
+---
+
+## Steps
+
+### 1. Create Firestore Client Wrapper
+
+**src/firestore/client.ts**:
+```typescript
+import admin from 'firebase-admin';
+import { Firestore, Timestamp } from 'firebase-admin/firestore';
+import { config } from '../config.js';
+import { readFileSync } from 'fs';
+
+let firestore: Firestore | null = null;
+
+/**
+ * Initialize Firebase Admin and Firestore
+ */
+export async function initFirestore(): Promise<Firestore> {
+  if (firestore) {
+    return firestore;
+  }
+
+  try {
+    // Read service account key
+    const serviceAccount = JSON.parse(
+      readFileSync(config.firebase.credentialsPath, 'utf8')
+    );
+
+    // Initialize Firebase Admin
+    admin.initializeApp({
+      credential: admin.credential.cert(serviceAccount),
+      projectId: config.firebase.projectId,
+    });
+
+    firestore = admin.firestore();
+
+    // Configure Firestore settings
+    firestore.settings({
+      ignoreUndefinedProperties: true,
+    });
+
+    console.log('[Firestore] Client initialized');
+    return firestore;
+  } catch (error) {
+    console.error('[Firestore] Initialization failed:', error);
+    throw error;
+  }
+}
+
+/**
+ * Get Firestore instance
+ */
+export function getFirestore(): Firestore {
+  if (!firestore) {
+    throw new Error('Firestore not initialized. Call initFirestore() first.');
+  }
+  return firestore;
+}
+
+/**
+ * Test Firestore connection
+ */
+export async function testFirestoreConnection(): Promise<boolean> {
+  try {
+    const db = getFirestore();
+    // Try to read a document (will fail gracefully if doesn't exist)
+    await db.collection('_health_check').doc('test').get();
+    console.log('[Firestore] Connection successful');
+    return true;
+  } catch (error) {
+    console.error('[Firestore] Connection failed:', error);
+    return false;
+  }
+}
+
+/**
+ * Get document from Firestore
+ */
+export async function getDocument<T = any>(
+  collection: string,
+  docId: string
+): Promise<T | null> {
+  try {
+    const db = getFirestore();
+    const doc = await db.collection(collection).doc(docId).get();
+
+    if (!doc.exists) {
+      return null;
+    }
+
+    return doc.data() as T;
+  } catch (error) {
+    console.error(`[Firestore] Error getting document ${collection}/${docId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Set document in Firestore
+ */
+export async function setDocument<T = any>(
+  collection: string,
+  docId: string,
+  data: T
+): Promise<void> {
+  try {
+    const db = getFirestore();
+    await db.collection(collection).doc(docId).set(data);
+  } catch (error) {
+    console.error(`[Firestore] Error setting document ${collection}/${docId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Update document in Firestore
+ */
+export async function updateDocument<T = any>(
+  collection: string,
+  docId: string,
+  data: Partial<T>
+): Promise<void> {
+  try {
+    const db = getFirestore();
+    await db.collection(collection).doc(docId).update(data as any);
+  } catch (error) {
+    console.error(`[Firestore] Error updating document ${collection}/${docId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Delete document from Firestore
+ */
+export async function deleteDocument(collection: string, docId: string): Promise<void> {
+  try {
+    const db = getFirestore();
+    await db.collection(collection).doc(docId).delete();
+  } catch (error) {
+    console.error(`[Firestore] Error deleting document ${collection}/${docId}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Query documents from Firestore
+ */
+export async function queryDocuments<T = any>(
+  collection: string,
+  filters?: Array<{ field: string; operator: FirebaseFirestore.WhereFilterOp; value: any }>
+): Promise<T[]> {
+  try {
+    const db = getFirestore();
+    let query: FirebaseFirestore.Query = db.collection(collection);
+
+    if (filters) {
+      for (const filter of filters) {
+        query = query.where(filter.field, filter.operator, filter.value);
+      }
+    }
+
+    const snapshot = await query.get();
+    return snapshot.docs.map((doc) => doc.data() as T);
+  } catch (error) {
+    console.error(`[Firestore] Error querying collection ${collection}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Export Timestamp for use in other modules
+ */
+export { Timestamp };
+```
+
+### 2. Create Firestore Path Helpers
+
+**src/firestore/paths.ts**:
+```typescript
+/**
+ * Firestore path helpers following users/{user_id}/ pattern
+ */
+
+/**
+ * Get path to user's preferences document
+ */
+export function getUserPreferencesPath(userId: string): string {
+  return `users/${userId}/preferences`;
+}
+
+/**
+ * Get path to user's templates collection
+ */
+export function getUserTemplatesPath(userId: string): string {
+  return `users/${userId}/templates`;
+}
+
+/**
+ * Get path to specific user template
+ */
+export function getUserTemplatePath(userId: string, templateId: string): string {
+  return `users/${userId}/templates/${templateId}`;
+}
+
+/**
+ * Get path to user's access logs collection
+ */
+export function getUserAccessLogsPath(userId: string): string {
+  return `users/${userId}/access_logs`;
+}
+
+/**
+ * Get path to user's trust relationships collection
+ */
+export function getUserTrustRelationshipsPath(userId: string): string {
+  return `users/${userId}/trust_relationships`;
+}
+
+/**
+ * Get path to default templates collection
+ */
+export function getDefaultTemplatesPath(): string {
+  return 'templates/default';
+}
+
+/**
+ * Get path to specific default template
+ */
+export function getDefaultTemplatePath(templateId: string): string {
+  return `templates/default/${templateId}`;
+}
+
+/**
+ * Get path to user permissions (cross-user)
+ */
+export function getUserPermissionsPath(ownerUserId: string, accessorUserId: string): string {
+  return `user_permissions/${ownerUserId}/allowed_accessors/${accessorUserId}`;
+}
+```
+
+### 3. Create Test File
+
+**tests/unit/firestore-client.test.ts**:
+```typescript
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  initFirestore,
+  testFirestoreConnection,
+  setDocument,
+  getDocument,
+  deleteDocument,
+} from '../../src/firestore/client.js';
+
+describe('Firestore Client', () => {
+  beforeAll(async () => {
+    await initFirestore();
+  });
+
+  it('should initialize client', async () => {
+    const result = await testFirestoreConnection();
+    expect(result).toBe(true);
+  });
+
+  it('should set and get document', async () => {
+    const testData = { test: 'value', timestamp: new Date().toISOString() };
+    
+    await setDocument('_test', 'test-doc', testData);
+    const retrieved = await getDocument('_test', 'test-doc');
+    
+    expect(retrieved).toEqual(testData);
+    
+    // Cleanup
+    await deleteDocument('_test', 'test-doc');
+  });
+
+  it('should return null for non-existent document', async () => {
+    const result = await getDocument('_test', 'non-existent');
+    expect(result).toBeNull();
+  });
+});
+```
+
+---
+
+## Verification
+
+- [x] src/firestore/init.ts created (minimal initialization helper)
+- [x] src/firestore/paths.ts created (collection path helpers)
+- [x] Tests created (tests/unit/firestore-paths.test.ts)
+- [x] Can initialize Firestore (initFirestore function)
+- [x] Connection test implemented (testFirestoreConnection)
+- [x] Re-exports firebase-admin-sdk-v8 functions (no wrapper needed)
+- [x] Path helpers work correctly (7 tests passing, 100% coverage)
+
+## Completion Notes
+
+**Completed**: 2026-02-11
+
+**What Was Created**:
+- ✅ [`src/firestore/init.ts`](../../src/firestore/init.ts) - Minimal initialization helper
+  - `initFirestore()` - Initialize firebase-admin-sdk-v8 once
+  - `isFirestoreInitialized()` - Check initialization state
+  - `testFirestoreConnection()` - Test connection
+  - Re-exports all firebase-admin-sdk-v8 functions for convenience
+  
+- ✅ [`src/firestore/paths.ts`](../../src/firestore/paths.ts) - Collection path helpers
+  - `getUserPreferencesPath()` - user_preferences/{userId}
+  - `getUserTemplatesPath()` - users/{userId}/templates
+  - `getUserPermissionsPath()` - user_permissions/{userId}/allowed_accessors
+  - `getUserPermissionPath()` - Specific permission document
+  - `getTrustHistoryPath()` - trust_history/{userId}/history
+  - `getDefaultTemplatesPath()` - templates/default
+  - `getDefaultTemplatePath()` - Specific default template
+  
+- ✅ [`tests/unit/firestore-paths.test.ts`](../../tests/unit/firestore-paths.test.ts) - Unit tests
+  - 7 tests passing
+  - 100% code coverage for paths.ts
+
+**Design Decision**:
+- ✅ Using firebase-admin-sdk-v8 instead of firebase-admin (edge-compatible)
+- ✅ Service layer pattern (no wrapper) per [`agent/design/firestore-wrapper-analysis.md`](../../agent/design/firestore-wrapper-analysis.md)
+- ✅ Minimal init helper + re-exports (not a full wrapper class)
+- ✅ Path helpers for multi-tenant collection organization
+
+**Test Results**: 14 passed, 1 skipped (all Firestore path tests passing)
+
+**What's Next**:
+- Task 5: Create basic MCP server
+
+---
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Test connection manually
+npm run dev
+# Should see: [Firestore] Client initialized
+# Should see: [Firestore] Connection successful
+```
+
+---
+
+## Next Task
+
+Task 5: Create Basic MCP Server