refactor(database): move db into typescript

- Implemented githubTokensDb for managing GitHub tokens with CRUD operations.
- Created
otificationPreferencesDb to handle user notification preferences.
- Added projectsDb for project path management and related operations.
- Introduced pushSubscriptionsDb for managing browser push subscriptions.
- Developed scanStateDb to track the last scanned timestamp.
- Established sessionsDb for session management with CRUD functionalities.
- Created userDb for user management, including authentication and onboarding.
- Implemented apidKeysDb for storing and managing VAPID keys.

feat(database): define schema for new database tables

- Added SQL schema definitions for users, API keys, user credentials, notification preferences, VAPID keys, push subscriptions, projects, sessions, scan state, and app configuration.
- Included necessary indexes for performance optimization.

refactor(shared): enhance type definitions and utility functions

- Updated shared types and interfaces for improved clarity and consistency.
- Added new types for credential management and provider-specific operations.
- Refined utility functions for better error handling and message normalization.

server/shared/interfaces.ts

@@ -9,6 +9,7 @@ import type {
   UpsertProviderMcpServerInput,
 } from '@/shared/types.js';
 
+//----------------- PROVIDER CONTRACT INTERFACES ------------
 /**
  * Main provider contract for CLI and SDK integrations.
  *
@@ -22,9 +23,13 @@ export interface IProvider {
   readonly sessions: IProviderSessions;
 }
 
-
+// ---------------------------
+//----------------- PROVIDER AUTH INTERFACE ------------
 /**
  * Auth contract for one provider.
+ *
+ * Implementations should return a complete installation/authentication status
+ * without throwing for normal "not installed" or "not authenticated" states.
  */
 export interface IProviderAuth {
   /**
@@ -33,8 +38,13 @@ export interface IProviderAuth {
   getStatus(): Promise<ProviderAuthStatus>;
 }
 
+// ---------------------------
+//----------------- PROVIDER MCP INTERFACE ------------
 /**
  * MCP contract for one provider.
+ *
+ * Implementations must map provider-native MCP config formats to shared
+ * `ProviderMcpServer` records used by routes and frontend state.
  */
 export interface IProviderMcp {
   listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>>;
@@ -45,8 +55,13 @@ export interface IProviderMcp {
   ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }>;
 }
 
+// ---------------------------
+//----------------- PROVIDER SESSION INTERFACE ------------
 /**
  * Session/history contract for one provider.
+ *
+ * Implementations normalize provider-specific events and message history into
+ * shared transport shapes consumed by API routes and realtime streams.
  */
 export interface IProviderSessions {
   normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];