fss-link 1.2.5 → 1.2.6

package/dist/src/config/queryOptimizer.js

@@ -0,0 +1,330 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Query Optimizer for FSS Link Database
+ * Provides prepared statement caching and query performance monitoring
+ */
+export class QueryOptimizer {
+    statementCache = new Map();
+    queryMetrics = new Map();
+    maxCacheSize = 100;
+    metricsEnabled = true;
+    /**
+     * Execute a query with optimization and metrics
+     */
+    async executeOptimized(db, query, params = [], operation) {
+        const startTime = Date.now();
+        try {
+            // Get or create prepared statement
+            const stmt = this.getOrCreateStatement(db, query);
+            // Bind parameters if provided
+            if (params.length > 0) {
+                stmt.bind(params);
+            }
+            // Execute the operation
+            const result = operation(stmt);
+            // Record metrics
+            if (this.metricsEnabled) {
+                const executionTime = Date.now() - startTime;
+                this.recordQueryMetrics(query, executionTime);
+            }
+            return result;
+        }
+        catch (error) {
+            // Record failed query metrics
+            if (this.metricsEnabled) {
+                const executionTime = Date.now() - startTime;
+                this.recordQueryMetrics(query, executionTime);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Execute a simple query and return results
+     */
+    async executeQuery(db, query, params = []) {
+        return this.executeOptimized(db, query, params, (stmt) => {
+            const results = [];
+            while (stmt.step()) {
+                results.push(stmt.getAsObject());
+            }
+            return results;
+        });
+    }
+    /**
+     * Execute a query and return a single result
+     */
+    async executeQuerySingle(db, query, params = []) {
+        return this.executeOptimized(db, query, params, (stmt) => stmt.step() ? stmt.getAsObject() : null);
+    }
+    /**
+     * Execute a modification query (INSERT, UPDATE, DELETE)
+     */
+    async executeModification(db, query, params = []) {
+        return this.executeOptimized(db, query, params, (stmt) => {
+            stmt.run(params);
+            return db.exec('SELECT changes()')[0]?.values[0]?.[0] || 0;
+        });
+    }
+    /**
+     * Get or create a prepared statement from cache
+     */
+    getOrCreateStatement(db, query) {
+        const normalizedQuery = this.normalizeQuery(query);
+        // Check cache first
+        const cached = this.statementCache.get(normalizedQuery);
+        if (cached) {
+            // Update usage statistics
+            cached.lastUsed = new Date();
+            cached.usageCount++;
+            return cached.statement;
+        }
+        // Create new prepared statement
+        const statement = db.prepare(query);
+        // Add to cache
+        this.addToCache(normalizedQuery, query, statement);
+        return statement;
+    }
+    /**
+     * Add prepared statement to cache
+     */
+    addToCache(normalizedQuery, originalQuery, statement) {
+        // Evict old entries if cache is full
+        if (this.statementCache.size >= this.maxCacheSize) {
+            this.evictLeastRecentlyUsed();
+        }
+        // Add new entry
+        this.statementCache.set(normalizedQuery, {
+            statement,
+            query: originalQuery,
+            lastUsed: new Date(),
+            usageCount: 1
+        });
+    }
+    /**
+     * Evict least recently used statement from cache
+     */
+    evictLeastRecentlyUsed() {
+        let oldestEntry = null;
+        let oldestTime = Date.now();
+        for (const [key, entry] of this.statementCache.entries()) {
+            if (entry.lastUsed.getTime() < oldestTime) {
+                oldestTime = entry.lastUsed.getTime();
+                oldestEntry = key;
+            }
+        }
+        if (oldestEntry) {
+            // CRITICAL FIX: Properly free the statement before removing from cache
+            const entry = this.statementCache.get(oldestEntry);
+            if (entry?.statement && typeof entry.statement.free === 'function') {
+                try {
+                    entry.statement.free();
+                }
+                catch (error) {
+                    // Statement might already be closed, but we should continue cleanup
+                    console.warn('Warning: Could not free statement during cache eviction:', error);
+                }
+            }
+            this.statementCache.delete(oldestEntry);
+        }
+    }
+    /**
+     * Normalize query for caching (remove extra whitespace, etc.)
+     */
+    normalizeQuery(query) {
+        return query
+            .replace(/\s+/g, ' ')
+            .trim()
+            .toLowerCase();
+    }
+    /**
+     * Record query execution metrics
+     */
+    recordQueryMetrics(query, executionTime) {
+        const normalizedQuery = this.normalizeQuery(query);
+        const existing = this.queryMetrics.get(normalizedQuery);
+        if (existing) {
+            // Update existing metrics
+            existing.executionCount++;
+            existing.totalTime += executionTime;
+            existing.averageTime = existing.totalTime / existing.executionCount;
+            existing.minTime = Math.min(existing.minTime, executionTime);
+            existing.maxTime = Math.max(existing.maxTime, executionTime);
+            existing.lastExecuted = new Date();
+        }
+        else {
+            // Create new metrics entry
+            this.queryMetrics.set(normalizedQuery, {
+                query: normalizedQuery,
+                executionCount: 1,
+                totalTime: executionTime,
+                averageTime: executionTime,
+                minTime: executionTime,
+                maxTime: executionTime,
+                lastExecuted: new Date()
+            });
+        }
+    }
+    /**
+     * Get query performance metrics
+     */
+    getQueryMetrics() {
+        return Array.from(this.queryMetrics.values())
+            .sort((a, b) => b.totalTime - a.totalTime); // Sort by total time (descending)
+    }
+    /**
+     * Get slow queries (above threshold)
+     */
+    getSlowQueries(thresholdMs = 100) {
+        return this.getQueryMetrics()
+            .filter(metric => metric.averageTime > thresholdMs);
+    }
+    /**
+     * Get most frequently executed queries
+     */
+    getFrequentQueries(limit = 10) {
+        return Array.from(this.queryMetrics.values())
+            .sort((a, b) => b.executionCount - a.executionCount)
+            .slice(0, limit);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        const entries = Array.from(this.statementCache.entries()).map(([key, entry]) => ({
+            query: entry.query,
+            usageCount: entry.usageCount,
+            lastUsed: entry.lastUsed
+        }));
+        // Calculate hit rate (approximate)
+        const totalQueries = Array.from(this.queryMetrics.values())
+            .reduce((sum, metric) => sum + metric.executionCount, 0);
+        const totalCacheUsage = entries
+            .reduce((sum, entry) => sum + entry.usageCount, 0);
+        const hitRate = totalQueries > 0 ? totalCacheUsage / totalQueries : 0;
+        return {
+            size: this.statementCache.size,
+            maxSize: this.maxCacheSize,
+            hitRate,
+            entries: entries.sort((a, b) => b.usageCount - a.usageCount)
+        };
+    }
+    /**
+     * Clear query metrics
+     */
+    clearMetrics() {
+        this.queryMetrics.clear();
+    }
+    /**
+     * Clear statement cache
+     */
+    clearCache() {
+        // CRITICAL FIX: Properly free all statements before clearing cache
+        for (const [key, entry] of this.statementCache.entries()) {
+            if (entry?.statement && typeof entry.statement.free === 'function') {
+                try {
+                    entry.statement.free();
+                }
+                catch (error) {
+                    // Statement might already be closed, but we should continue cleanup
+                    console.warn(`Warning: Could not free statement for query "${key}":`, error);
+                }
+            }
+        }
+        this.statementCache.clear();
+    }
+    /**
+     * Set cache size limit
+     */
+    setCacheSize(size) {
+        this.maxCacheSize = size;
+        // Evict entries if current size exceeds new limit
+        while (this.statementCache.size > size) {
+            this.evictLeastRecentlyUsed();
+        }
+    }
+    /**
+     * Enable or disable metrics collection
+     */
+    setMetricsEnabled(enabled) {
+        this.metricsEnabled = enabled;
+    }
+    /**
+     * Optimize database by running ANALYZE
+     */
+    async optimizeDatabase(db) {
+        try {
+            console.log('Running ANALYZE to optimize query plans...');
+            db.exec('ANALYZE');
+            console.log('Database optimization completed');
+        }
+        catch (error) {
+            console.warn('Failed to optimize database:', error);
+        }
+    }
+    /**
+     * Get database statistics
+     */
+    async getDatabaseStats(db) {
+        try {
+            // Get basic database info
+            const pragmaInfo = db.exec('PRAGMA page_count, page_size, freelist_count, schema_version, user_version');
+            const [pageCount, pageSize, freelistCount, schemaVersion, userVersion] = pragmaInfo[0]?.values[0] || [0, 0, 0, 0, 0];
+            // Get table information
+            const tableResult = db.exec(`
+        SELECT name FROM sqlite_master 
+        WHERE type='table' AND name NOT LIKE 'sqlite_%'
+      `);
+            const tables = [];
+            if (tableResult.length > 0) {
+                for (const row of tableResult[0].values) {
+                    const tableName = row[0];
+                    try {
+                        const countResult = db.exec(`SELECT COUNT(*) FROM "${tableName}"`);
+                        const rowCount = countResult[0]?.values[0]?.[0] || 0;
+                        tables.push({ name: tableName, rowCount });
+                    }
+                    catch {
+                        tables.push({ name: tableName, rowCount: 0 });
+                    }
+                }
+            }
+            return {
+                pageCount: pageCount,
+                pageSize: pageSize,
+                freelistCount: freelistCount,
+                schemaVersion: schemaVersion,
+                userVersion: userVersion,
+                tables
+            };
+        }
+        catch (error) {
+            console.warn('Failed to get database stats:', error);
+            return {
+                pageCount: 0,
+                pageSize: 0,
+                freelistCount: 0,
+                schemaVersion: 0,
+                userVersion: 0,
+                tables: []
+            };
+        }
+    }
+    /**
+     * Run VACUUM to reclaim space and defragment
+     */
+    async vacuumDatabase(db) {
+        try {
+            console.log('Running VACUUM to reclaim space...');
+            db.exec('VACUUM');
+            console.log('Database VACUUM completed');
+        }
+        catch (error) {
+            console.warn('Failed to vacuum database:', error);
+        }
+    }
+}
+//# sourceMappingURL=queryOptimizer.js.map

package/dist/src/config/queryOptimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryOptimizer.js","sourceRoot":"","sources":["../../../src/config/queryOptimizer.ts"],"names":[],"mappings":"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"}

package/dist/src/config/repository-types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ======================================================================================
+ * REPOSITORY TYPE DEFINITIONS - TASK 3: EXPLICIT ANY TYPE ELIMINATION
+ * ======================================================================================
+ *
+ * Proper TypeScript types to replace explicit 'any' types in repository classes.
+ * These types provide type safety while maintaining flexibility for database operations.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ * @task Task 3: Replace Explicit 'any' Types with Proper TypeScript Types
+ */
+import { AuthType } from 'fss-link-core';
+/**
+ * ======================================================================================
+ * DATABASE ROW TYPES
+ * ======================================================================================
+ */
+/**
+ * Generic database row interface extending Record<string, any> for database results
+ * Provides base structure while allowing additional properties from database queries
+ */
+export interface DatabaseRow extends Record<string, any> {
+    id?: number;
+    created_at?: string;
+    updated_at?: string;
+}
+/**
+ * ======================================================================================
+ * QUERY PARAMETER TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid SQL parameter types for prepared statements
+ * Matches SQLite supported parameter types
+ */
+export type QueryParameter = string | number | boolean | null | Buffer | undefined;
+/**
+ * Array of query parameters for prepared statements
+ */
+export type QueryParameters = QueryParameter[];
+/**
+ * ======================================================================================
+ * SETTING VALUE TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid setting value types for application settings
+ * Covers all common configuration value types
+ */
+export type SettingValue = string | number | boolean | null;
+/**
+ * Setting value with JSON support for complex configurations
+ */
+export type SettingValueWithJson = SettingValue | object;
+/**
+ * ======================================================================================
+ * PREFERENCE VALUE TYPES
+ * ======================================================================================
+ */
+/**
+ * Valid preference value types for user preferences
+ * Includes object support for complex preference structures
+ */
+export type PreferenceValue = string | number | boolean | object | null;
+/**
+ * ======================================================================================
+ * MODEL CONFIGURATION TYPES
+ * ======================================================================================
+ */
+/**
+ * Model configuration value types for model repository
+ * Includes AuthType enum for proper auth type validation
+ */
+export type ModelConfigValue = string | number | boolean | AuthType | null;
+/**
+ * ======================================================================================
+ * VALIDATION AND UTILITY TYPES
+ * ======================================================================================
+ */
+/**
+ * Unknown type for input validation before type assertion
+ * Use when receiving untyped input that needs validation
+ */
+export type UnknownInput = unknown;
+/**
+ * Generic JSON value type for JSON parsing/stringifying
+ */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+/**
+ * JSON object type
+ */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON array type
+ */
+export type JsonArray = JsonValue[];
+/**
+ * ======================================================================================
+ * DATABASE OPERATION RESULT TYPES
+ * ======================================================================================
+ */
+/**
+ * Database query result for operations that return rows
+ */
+export interface QueryResult<T = DatabaseRow> {
+    rows: T[];
+    rowCount: number;
+}
+/**
+ * Database execution result for INSERT/UPDATE/DELETE operations
+ */
+export interface ExecResult {
+    rowsAffected: number;
+    lastInsertId?: number;
+}
+/**
+ * ======================================================================================
+ * TYPE GUARDS AND VALIDATION HELPERS
+ * ======================================================================================
+ */
+/**
+ * Type guard to check if value is a valid QueryParameter
+ */
+export declare function isQueryParameter(value: unknown): value is QueryParameter;
+/**
+ * Type guard to check if value is a valid SettingValue
+ */
+export declare function isSettingValue(value: unknown): value is SettingValue;
+/**
+ * Type guard to check if value is a valid PreferenceValue
+ */
+export declare function isPreferenceValue(value: unknown): value is PreferenceValue;
+/**
+ * ======================================================================================
+ * MIGRATION MAPPING
+ * ======================================================================================
+ *
+ * This file replaces explicit 'any' types found in:
+ *
+ * BaseRepository:
+ * - params: any[] → QueryParameters
+ * - mapRow(row: any) → mapRow(row: DatabaseRow)
+ * - query parameters → QueryParameter[]
+ *
+ * SettingsRepository:
+ * - value: any → SettingValue | SettingValueWithJson
+ * - validateSettingValue(value: any) → validateSettingValue(value: unknown)
+ * - parseValue/stringifyValue(value: any) → proper typing
+ *
+ * PreferencesRepository:
+ * - value: any → PreferenceValue
+ * - setPreference(value: any) → setPreference(value: PreferenceValue)
+ * - preference operations → PreferenceValue
+ *
+ * ModelRepository:
+ * - auth_type: any → AuthType
+ * - configuration values → ModelConfigValue
+ * - database result mapping → proper typing
+ */ 

package/dist/src/config/repository-types.js

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ======================================================================================
+ * TYPE GUARDS AND VALIDATION HELPERS
+ * ======================================================================================
+ */
+/**
+ * Type guard to check if value is a valid QueryParameter
+ */
+export function isQueryParameter(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null ||
+        value instanceof Buffer);
+}
+/**
+ * Type guard to check if value is a valid SettingValue
+ */
+export function isSettingValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null);
+}
+/**
+ * Type guard to check if value is a valid PreferenceValue
+ */
+export function isPreferenceValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null ||
+        (typeof value === 'object' && value !== null));
+}
+/**
+ * ======================================================================================
+ * MIGRATION MAPPING
+ * ======================================================================================
+ *
+ * This file replaces explicit 'any' types found in:
+ *
+ * BaseRepository:
+ * - params: any[] → QueryParameters
+ * - mapRow(row: any) → mapRow(row: DatabaseRow)
+ * - query parameters → QueryParameter[]
+ *
+ * SettingsRepository:
+ * - value: any → SettingValue | SettingValueWithJson
+ * - validateSettingValue(value: any) → validateSettingValue(value: unknown)
+ * - parseValue/stringifyValue(value: any) → proper typing
+ *
+ * PreferencesRepository:
+ * - value: any → PreferenceValue
+ * - setPreference(value: any) → setPreference(value: PreferenceValue)
+ * - preference operations → PreferenceValue
+ *
+ * ModelRepository:
+ * - auth_type: any → AuthType
+ * - configuration values → ModelConfigValue
+ * - database result mapping → proper typing
+ */ 
+//# sourceMappingURL=repository-types.js.map

package/dist/src/config/repository-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-types.js","sourceRoot":"","sources":["../../../src/config/repository-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2IH;;;;GAIG;AAEH;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI;QACd,KAAK,YAAY,MAAM,CACxB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI,CACf,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,KAAK,KAAK,IAAI;QACd,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/src/config/sandboxConfig.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SandboxConfig } from 'fss-link-core';
+import { Settings } from './settings.js';
+interface SandboxCliArgs {
+    sandbox?: boolean | string;
+    sandboxImage?: string;
+}
+export declare function loadSandboxConfig(settings: Settings, argv: SandboxCliArgs): Promise<SandboxConfig | undefined>;
+export {};

package/dist/src/config/sandboxConfig.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import commandExists from 'command-exists';
+import * as os from 'node:os';
+import { getPackageJson } from '../utils/package.js';
+const VALID_SANDBOX_COMMANDS = [
+    'docker',
+    'podman',
+    'sandbox-exec',
+];
+function isSandboxCommand(value) {
+    return VALID_SANDBOX_COMMANDS.includes(value);
+}
+function getSandboxCommand(sandbox) {
+    // If the SANDBOX env var is set, we're already inside the sandbox.
+    if (process.env['SANDBOX']) {
+        return '';
+    }
+    // note environment variable takes precedence over argument (from command line or settings)
+    const environmentConfiguredSandbox = process.env['GEMINI_SANDBOX']?.toLowerCase().trim() ?? '';
+    sandbox =
+        environmentConfiguredSandbox?.length > 0
+            ? environmentConfiguredSandbox
+            : sandbox;
+    if (sandbox === '1' || sandbox === 'true')
+        sandbox = true;
+    else if (sandbox === '0' || sandbox === 'false' || !sandbox)
+        sandbox = false;
+    if (sandbox === false) {
+        return '';
+    }
+    if (typeof sandbox === 'string' && sandbox) {
+        if (!isSandboxCommand(sandbox)) {
+            console.error(`ERROR: invalid sandbox command '${sandbox}'. Must be one of ${VALID_SANDBOX_COMMANDS.join(', ')}`);
+            process.exit(1);
+        }
+        // confirm that specified command exists
+        if (commandExists.sync(sandbox)) {
+            return sandbox;
+        }
+        console.error(`ERROR: missing sandbox command '${sandbox}' (from GEMINI_SANDBOX)`);
+        process.exit(1);
+    }
+    // look for seatbelt, docker, or podman, in that order
+    // for container-based sandboxing, require sandbox to be enabled explicitly
+    if (os.platform() === 'darwin' && commandExists.sync('sandbox-exec')) {
+        return 'sandbox-exec';
+    }
+    else if (commandExists.sync('docker') && sandbox === true) {
+        return 'docker';
+    }
+    else if (commandExists.sync('podman') && sandbox === true) {
+        return 'podman';
+    }
+    // throw an error if user requested sandbox but no command was found
+    if (sandbox === true) {
+        console.error('ERROR: GEMINI_SANDBOX is true but failed to determine command for sandbox; ' +
+            'install docker or podman or specify command in GEMINI_SANDBOX');
+        process.exit(1);
+    }
+    return '';
+}
+export async function loadSandboxConfig(settings, argv) {
+    const sandboxOption = argv.sandbox ?? settings.sandbox;
+    const command = getSandboxCommand(sandboxOption);
+    const packageJson = await getPackageJson();
+    const image = argv.sandboxImage ??
+        process.env['GEMINI_SANDBOX_IMAGE'] ??
+        packageJson?.config?.sandboxImageUri;
+    return command && image ? { command, image } : undefined;
+}
+//# sourceMappingURL=sandboxConfig.js.map

package/dist/src/config/sandboxConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxConfig.js","sourceRoot":"","sources":["../../../src/config/sandboxConfig.ts"],"names":[],"mappings":"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"}