crewly 1.0.7 → 1.0.8

package/dist/cli/backend/src/services/knowledge/knowledge-search.service.js

@@ -0,0 +1,247 @@
+/**
+ * Knowledge Search Service
+ *
+ * Provides pluggable search strategies for knowledge documents.
+ * Uses keyword matching by default (zero dependencies), with optional
+ * Gemini embedding-based semantic search when GEMINI_API_KEY is set.
+ *
+ * @module services/knowledge/knowledge-search.service
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { KnowledgeService } from './knowledge.service.js';
+import { EMBEDDING_CONSTANTS, ENV_CONSTANTS } from '../../constants.js';
+/** Default number of results returned by search */
+const DEFAULT_SEARCH_LIMIT = 5;
+/**
+ * Keyword-based search strategy (default, zero dependencies).
+ *
+ * Splits the query into words and scores documents by matching against
+ * title (3x weight), tags (2x weight), and preview (1x weight).
+ */
+export class KeywordSearchStrategy {
+    /**
+     * Score documents using keyword matching.
+     *
+     * @param query - Search query text
+     * @param documents - Documents to score
+     * @returns Scored documents sorted by relevance
+     */
+    async search(query, documents) {
+        const queryWords = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 1);
+        if (queryWords.length === 0) {
+            return [];
+        }
+        const scored = [];
+        for (const doc of documents) {
+            const titleLower = doc.title.toLowerCase();
+            const previewLower = doc.preview.toLowerCase();
+            const tagsLower = doc.tags.map((t) => t.toLowerCase());
+            let score = 0;
+            for (const word of queryWords) {
+                if (titleLower.includes(word)) {
+                    score += 3;
+                }
+                if (tagsLower.some((tag) => tag.includes(word))) {
+                    score += 2;
+                }
+                if (previewLower.includes(word)) {
+                    score += 1;
+                }
+            }
+            if (score > 0) {
+                scored.push({ document: doc, score });
+            }
+        }
+        return scored.sort((a, b) => b.score - a.score);
+    }
+}
+/**
+ * Cosine similarity between two vectors.
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Cosine similarity in range [-1, 1]
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0) {
+        return 0;
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+}
+/**
+ * Gemini embedding-based semantic search strategy.
+ *
+ * Calls the Gemini Embedding API to embed query text, then computes
+ * cosine similarity against document embeddings. Falls back to
+ * KeywordSearchStrategy if the API call fails.
+ */
+export class GeminiEmbeddingStrategy {
+    apiKey;
+    fallback;
+    logger;
+    /**
+     * Creates a GeminiEmbeddingStrategy instance.
+     *
+     * @param apiKey - Gemini API key for embedding requests
+     */
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.fallback = new KeywordSearchStrategy();
+        this.logger = LoggerService.getInstance().createComponentLogger('GeminiEmbeddingStrategy');
+    }
+    /**
+     * Embed a single text string via the Gemini API.
+     *
+     * @param text - Text to embed
+     * @returns Embedding vector, or null on failure
+     */
+    async embed(text) {
+        try {
+            const url = `${EMBEDDING_CONSTANTS.GEMINI_ENDPOINT}/${EMBEDDING_CONSTANTS.GEMINI_MODEL}:embedContent?key=${this.apiKey}`;
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), EMBEDDING_CONSTANTS.TIMEOUT_MS);
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model: `models/${EMBEDDING_CONSTANTS.GEMINI_MODEL}`,
+                        content: { parts: [{ text }] },
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    this.logger.warn('Gemini embedding API returned non-OK status', {
+                        status: response.status,
+                    });
+                    return null;
+                }
+                const data = (await response.json());
+                return data.embedding?.values ?? null;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn('Gemini embedding API call failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Score documents using Gemini embeddings and cosine similarity.
+     * Falls back to keyword search if embedding fails.
+     *
+     * @param query - Search query text
+     * @param documents - Documents to score
+     * @returns Scored documents sorted by relevance
+     */
+    async search(query, documents) {
+        const queryEmbedding = await this.embed(query);
+        if (!queryEmbedding) {
+            this.logger.info('Falling back to keyword search due to embedding failure');
+            return this.fallback.search(query, documents);
+        }
+        const scored = [];
+        for (const doc of documents) {
+            const docText = `${doc.title} ${doc.tags.join(' ')} ${doc.preview}`;
+            const docEmbedding = await this.embed(docText);
+            if (!docEmbedding) {
+                continue;
+            }
+            const score = cosineSimilarity(queryEmbedding, docEmbedding);
+            if (score > 0) {
+                scored.push({ document: doc, score });
+            }
+        }
+        if (scored.length === 0) {
+            this.logger.info('No embedding results, falling back to keyword search');
+            return this.fallback.search(query, documents);
+        }
+        return scored.sort((a, b) => b.score - a.score);
+    }
+}
+/**
+ * Knowledge Search Service singleton.
+ *
+ * Factory that selects the appropriate search strategy based on
+ * environment configuration. Provides a high-level search interface
+ * over the KnowledgeService document store.
+ *
+ * @example
+ * ```typescript
+ * const results = await KnowledgeSearchService.getInstance().search(
+ *   'deployment runbook',
+ *   'global',
+ * );
+ * ```
+ */
+export class KnowledgeSearchService {
+    static instance = null;
+    strategy;
+    logger;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('KnowledgeSearchService');
+        const geminiKey = process.env[ENV_CONSTANTS.GEMINI_API_KEY];
+        if (geminiKey) {
+            this.logger.info('Using Gemini embedding search strategy');
+            this.strategy = new GeminiEmbeddingStrategy(geminiKey);
+        }
+        else {
+            this.logger.info('Using keyword search strategy (no GEMINI_API_KEY set)');
+            this.strategy = new KeywordSearchStrategy();
+        }
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns KnowledgeSearchService instance
+     */
+    static getInstance() {
+        if (!KnowledgeSearchService.instance) {
+            KnowledgeSearchService.instance = new KnowledgeSearchService();
+        }
+        return KnowledgeSearchService.instance;
+    }
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance() {
+        KnowledgeSearchService.instance = null;
+    }
+    /**
+     * Search knowledge documents using the configured strategy.
+     *
+     * @param query - Search query text
+     * @param scope - Document scope ('global' or 'project')
+     * @param projectPath - Project path (required when scope is 'project')
+     * @param category - Optional category filter
+     * @param limit - Maximum number of results (default 5)
+     * @returns Matching document summaries sorted by relevance
+     */
+    async search(query, scope, projectPath, category, limit = DEFAULT_SEARCH_LIMIT) {
+        this.logger.debug('Searching knowledge documents', { query, scope, category });
+        const knowledgeService = KnowledgeService.getInstance();
+        const candidates = await knowledgeService.listDocuments(scope, projectPath, { category });
+        if (candidates.length === 0) {
+            return [];
+        }
+        const scored = await this.strategy.search(query, candidates);
+        return scored.slice(0, limit).map((s) => s.document);
+    }
+}
+//# sourceMappingURL=knowledge-search.service.js.map

package/dist/cli/backend/src/services/knowledge/knowledge-search.service.js.map

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

package/dist/cli/backend/src/services/knowledge/knowledge.service.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Knowledge Service
+ *
+ * Manages Company Knowledge documents — markdown files with YAML frontmatter
+ * stored at global (~/.crewly/docs/) or project ({projectPath}/.crewly/docs/) scope.
+ * Provides CRUD operations with a JSON index for fast listing.
+ *
+ * @module services/knowledge/knowledge.service
+ */
+import type { KnowledgeDocument, KnowledgeDocumentSummary, KnowledgeScope, CreateKnowledgeDocumentParams, UpdateKnowledgeDocumentParams, KnowledgeDocumentFilters } from '../../types/knowledge.types.js';
+/**
+ * Knowledge Service singleton.
+ *
+ * Follows the same singleton + filesystem pattern used by SOPService.
+ */
+export declare class KnowledgeService {
+    private static instance;
+    private readonly logger;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns KnowledgeService instance
+     */
+    static getInstance(): KnowledgeService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Resolve the docs directory for a given scope.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Absolute path to the docs directory
+     */
+    private docsDir;
+    /**
+     * Resolve the index file path for a given scope.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Absolute path to the index JSON file
+     */
+    private indexPath;
+    /**
+     * Resolve the file path for a specific document.
+     *
+     * @param id - Document identifier
+     * @param scope - Document scope
+     * @param projectPath - Project path for project-scoped docs
+     * @returns Absolute path to the .md file
+     */
+    private docFilePath;
+    /**
+     * Ensure the docs directory exists.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path for project-scoped docs
+     */
+    private ensureDocsDir;
+    /**
+     * Read the knowledge index, returning an empty index if the file doesn't exist.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path for project-scoped docs
+     * @returns The knowledge index
+     */
+    private readIndex;
+    /**
+     * Write the knowledge index atomically.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path for project-scoped docs
+     * @param index - The index data to write
+     */
+    private writeIndex;
+    /**
+     * Parse a knowledge document from its markdown file content.
+     *
+     * @param raw - Raw file content with YAML frontmatter
+     * @param scope - Document scope
+     * @param projectPath - Optional project path
+     * @returns Parsed KnowledgeDocument or null if parsing fails
+     */
+    private parseDocumentFile;
+    /**
+     * Serialize a knowledge document to markdown with YAML frontmatter.
+     *
+     * @param doc - The document to serialize
+     * @returns Markdown string with frontmatter
+     */
+    private serializeDocument;
+    /**
+     * Build an index entry from a knowledge document.
+     *
+     * @param doc - The document
+     * @returns Index entry with preview
+     */
+    private buildIndexEntry;
+    /**
+     * List all documents for a given scope, optionally filtered.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @param filters - Optional category/search filters
+     * @returns Array of document summaries
+     */
+    listDocuments(scope: KnowledgeScope, projectPath?: string, filters?: KnowledgeDocumentFilters): Promise<KnowledgeDocumentSummary[]>;
+    /**
+     * Get a single document by ID.
+     *
+     * @param id - Document identifier
+     * @param scope - Document scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Full document or null if not found
+     */
+    getDocument(id: string, scope: KnowledgeScope, projectPath?: string): Promise<KnowledgeDocument | null>;
+    /**
+     * Create a new knowledge document.
+     *
+     * @param params - Document creation parameters
+     * @returns The generated document ID
+     * @throws Error if validation fails
+     */
+    createDocument(params: CreateKnowledgeDocumentParams): Promise<string>;
+    /**
+     * Update an existing knowledge document.
+     *
+     * @param id - Document identifier
+     * @param params - Update parameters
+     * @throws Error if document not found or validation fails
+     */
+    updateDocument(id: string, params: UpdateKnowledgeDocumentParams): Promise<void>;
+    /**
+     * Delete a knowledge document.
+     *
+     * @param id - Document identifier
+     * @param scope - Document scope
+     * @param projectPath - Required when scope is 'project'
+     * @throws Error if document not found
+     */
+    deleteDocument(id: string, scope: KnowledgeScope, projectPath?: string): Promise<void>;
+    /**
+     * List all categories in use for a given scope, merged with defaults.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Array of category names (defaults + custom in-use)
+     */
+    listCategories(scope: KnowledgeScope, projectPath?: string): Promise<string[]>;
+}
+//# sourceMappingURL=knowledge.service.d.ts.map

package/dist/cli/backend/src/services/knowledge/knowledge.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/knowledge/knowledge.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,KAAK,EACV,iBAAiB,EACjB,wBAAwB,EAIxB,cAAc,EACd,6BAA6B,EAC7B,6BAA6B,EAC7B,wBAAwB,EACzB,MAAM,gCAAgC,CAAC;AAkBxC;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO;IAIP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAQ5B;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IAWf;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;OAKG;YACW,aAAa;IAW3B;;;;;;OAMG;YACW,SAAS;IAKvB;;;;;;OAMG;YACW,UAAU;IAexB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAoCzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;;;OAOG;IACG,aAAa,CACjB,KAAK,EAAE,cAAc,EACrB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAwBtC;;;;;;;OAOG;IACG,WAAW,CACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,cAAc,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAUpC;;;;;;OAMG;IACG,cAAc,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,MAAM,CAAC;IAiD5E;;;;;;OAMG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CtF;;;;;;;OAOG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5F;;;;;;OAMG;IACG,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAMrF"}