forge-server 0.1.0

package/dist/knowledge/search.js

@@ -0,0 +1,428 @@
+// KnowledgeSearch — semantic search over the Qdrant knowledge collection.
+//
+// Architecture notes (ADR-2):
+// - ALL knowledge search goes through Qdrant. There is no SQLite FTS fallback.
+// - When Qdrant is unavailable the search returns [] with a logged warning —
+//   it does NOT throw. The pipeline continues; agents just receive no gotchas.
+// - Cross-repo search is opt-in (include_cross_repo defaults to false at the
+//   tool layer). Results from the caller's repo get a small score boost to
+//   surface local knowledge first without completely filtering out cross-repo
+//   items when cross-repo is enabled.
+// - stack_tags filtering uses a Qdrant "should" condition (any tag matches)
+//   rather than "must" (all tags must match), because a gotcha tagged with
+//   ["nestjs", "swc"] is equally relevant to a query from a project that uses
+//   either nestjs or swc.
+//
+// Qdrant filter shape reference:
+//   must  → all conditions must be satisfied (AND)
+//   should→ at least one condition must be satisfied (OR)
+//   Values indexed as 'keyword' support match: { value: "..." } for exact match
+//   Values indexed as 'float' support range: { gte: 0.3 }
+import { logger } from '../util/logger.js';
+import { embedText } from '../ingestion/embedder.js';
+// ---------------------------------------------------------------------------
+// Score boost applied to results from the same repo as the caller.
+// Set conservatively: local items should surface first but not crowd out
+// highly relevant cross-repo items.
+// ---------------------------------------------------------------------------
+const SAME_REPO_SCORE_BOOST = 0.05;
+// ---------------------------------------------------------------------------
+// KnowledgeSearch
+// ---------------------------------------------------------------------------
+export class KnowledgeSearch {
+    vectorStore;
+    constructor(vectorStore) {
+        this.vectorStore = vectorStore;
+    }
+    // ---------------------------------------------------------------------------
+    // Primary search method (spec B4 signature)
+    // ---------------------------------------------------------------------------
+    /**
+     * Semantic search across knowledge items stored in the Qdrant knowledge
+     * collection.
+     *
+     * Options:
+     *   category          — filter to a single KnowledgeCategory
+     *   stack_tags        — filter to items that share at least one tag (OR match)
+     *   repo_id           — used for same-repo scoring boost; also hard-filters
+     *                       when include_cross_repo is false
+     *   limit             — max results to return (default 10)
+     *   include_cross_repo— include items from other repos (default true)
+     *   min_confidence    — minimum confidence score (default 0.3)
+     *
+     * Returns results sorted descending by relevance_score.
+     * Returns [] when Qdrant is unavailable — never throws.
+     */
+    async search(query, options) {
+        const { category, stack_tags, repo_id, limit = 10, include_cross_repo = true, min_confidence = 0.3, } = options ?? {};
+        // Check Qdrant availability first — avoid embedding model init overhead
+        // when Qdrant is down.
+        const healthy = await this.vectorStore.isHealthy();
+        if (!healthy) {
+            logger.warn('KnowledgeSearch.search: Qdrant unavailable, returning empty results', {
+                query: query.slice(0, 80),
+            });
+            return [];
+        }
+        let queryVector;
+        try {
+            queryVector = await embedText(query);
+        }
+        catch (err) {
+            logger.warn('KnowledgeSearch.search: embedding failed, returning empty results', {
+                error: String(err),
+            });
+            return [];
+        }
+        // Build Qdrant filter.
+        // When include_cross_repo is false, hard-filter to repo_id only.
+        // When include_cross_repo is true, only include cross-repo items that have
+        // sharing = 'team' or 'public' (private repos never leak into other repos'
+        // results). Items from the caller's own repo are always included regardless
+        // of sharing setting.
+        const qdrantFilter = this._buildQdrantFilter({
+            category,
+            stack_tags,
+            repo_id: include_cross_repo ? undefined : repo_id,
+            caller_repo_id: include_cross_repo ? repo_id : undefined,
+            min_confidence,
+        });
+        let rawResults;
+        try {
+            // Fetch more than requested to allow re-ranking after same-repo boost.
+            const fetchLimit = Math.min(limit * 3, 100);
+            const results = await this.vectorStore.searchKnowledge(queryVector, {
+                limit: fetchLimit,
+                // We handle min_confidence via the filter's range condition on the
+                // confidence payload field rather than scoreThreshold (which applies
+                // to the cosine similarity score, a different axis).
+                scoreThreshold: 0.0,
+                filter: qdrantFilter,
+            });
+            rawResults = results.map((r) => ({
+                id: r.id,
+                score: r.score,
+                payload: r.payload,
+            }));
+        }
+        catch (err) {
+            logger.warn('KnowledgeSearch.search: Qdrant search failed, returning empty results', {
+                error: String(err),
+            });
+            return [];
+        }
+        // Apply same-repo boost, re-rank, trim to limit.
+        const boosted = rawResults.map((r) => {
+            const payload = r.payload;
+            const boost = repo_id && payload.repo_id === repo_id ? SAME_REPO_SCORE_BOOST : 0;
+            return { ...r, boostedScore: r.score + boost };
+        });
+        boosted.sort((a, b) => b.boostedScore - a.boostedScore);
+        const output = [];
+        for (const r of boosted) {
+            if (output.length >= limit)
+                break;
+            const p = r.payload;
+            if (!p.id || !p.title || !p.content)
+                continue;
+            output.push({
+                id: p.id,
+                category: p.category ?? 'pattern',
+                title: p.title,
+                content: p.content,
+                confidence: p.confidence ?? 0,
+                stack_tags: Array.isArray(p.stack_tags) ? p.stack_tags : [],
+                source_repo: p.repo_id ?? '',
+                relevance_score: r.boostedScore,
+            });
+        }
+        logger.debug('KnowledgeSearch.search: completed', {
+            query: query.slice(0, 80),
+            resultCount: output.length,
+            category,
+            hadSameRepoBoost: !!repo_id,
+        });
+        return output;
+    }
+    // ---------------------------------------------------------------------------
+    // Confidence boost
+    // ---------------------------------------------------------------------------
+    /**
+     * Increment access_count and update accessed_at for a knowledge item.
+     * Optionally bumps the confidence score by boostAmount.
+     *
+     * Called when an agent actively consumes a knowledge item — access signals
+     * genuine utility and nudges confidence upward.
+     * Silent on Qdrant failure (non-fatal side effect).
+     */
+    async boostConfidence(knowledgeId, boostAmount = 0.01) {
+        const healthy = await this.vectorStore.isHealthy();
+        if (!healthy) {
+            logger.debug('KnowledgeSearch.boostConfidence: Qdrant unavailable, skip', { knowledgeId });
+            return;
+        }
+        try {
+            // Use setKnowledgePayload if the store exposes it; otherwise fall back
+            // to a no-op so callers never see an exception from a best-effort call.
+            const store = this.vectorStore;
+            let currentConfidence = 0;
+            let currentAccessCount = 0;
+            if (typeof store.getKnowledge === 'function') {
+                const existing = await store.getKnowledge(knowledgeId);
+                if (existing) {
+                    currentConfidence = existing['confidence'] ?? 0;
+                    currentAccessCount = existing['access_count'] ?? 0;
+                }
+            }
+            const patch = {
+                accessed_at: Date.now(),
+                access_count: currentAccessCount + 1,
+                confidence: Math.min(1.0, currentConfidence + boostAmount),
+            };
+            if (typeof store.setKnowledgePayload === 'function') {
+                await store.setKnowledgePayload(knowledgeId, patch);
+                logger.debug('KnowledgeSearch.boostConfidence: boosted', {
+                    knowledgeId,
+                    newAccessCount: patch['access_count'],
+                    newConfidence: patch['confidence'],
+                });
+            }
+            else {
+                logger.debug('KnowledgeSearch.boostConfidence: setKnowledgePayload not available, skipping', { knowledgeId });
+            }
+        }
+        catch (err) {
+            logger.warn('KnowledgeSearch.boostConfidence: failed (non-fatal)', {
+                knowledgeId,
+                error: String(err),
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Typed accessors
+    // ---------------------------------------------------------------------------
+    /**
+     * Return gotcha items optionally filtered by stack tags.
+     * Uses Qdrant filter (category=gotcha) plus optional stack_tags OR match.
+     * Results sorted by confidence descending.
+     * Gracefully returns [] on Qdrant unavailability.
+     */
+    async getGotchas(stack, limit = 20, minConfidence = 0.3) {
+        return this._getByCategory('gotcha', stack, limit, minConfidence);
+    }
+    /**
+     * Return pattern items optionally filtered by domain.
+     * `domain` is treated as a stack tag (single-element array) for consistency.
+     * Results sorted by confidence descending.
+     * Gracefully returns [] on Qdrant unavailability.
+     */
+    async getPatterns(domain, limit = 20, minConfidence = 0.3) {
+        const tags = domain ? [domain] : undefined;
+        return this._getByCategory('pattern', tags, limit, minConfidence);
+    }
+    // ---------------------------------------------------------------------------
+    // Backward-compat helpers (camelCase signature from the prior implementation)
+    // ---------------------------------------------------------------------------
+    /** Convenience: search with category=gotcha. Backward-compat camelCase API. */
+    async searchGotchas(query, opts) {
+        return this.search(query, {
+            category: 'gotcha',
+            stack_tags: opts?.stackTags,
+            repo_id: opts?.repoId,
+            limit: opts?.limit,
+            min_confidence: opts?.minConfidence,
+        });
+    }
+    /** Convenience: search with category=decision. Backward-compat camelCase API. */
+    async searchDecisions(query, opts) {
+        return this.search(query, {
+            category: 'decision',
+            stack_tags: opts?.stackTags,
+            repo_id: opts?.repoId,
+            limit: opts?.limit,
+            min_confidence: opts?.minConfidence,
+        });
+    }
+    /** Convenience: search with category=pattern. Backward-compat camelCase API. */
+    async searchPatterns(query, opts) {
+        return this.search(query, {
+            category: 'pattern',
+            stack_tags: opts?.stackTags,
+            repo_id: opts?.repoId,
+            limit: opts?.limit,
+            min_confidence: opts?.minConfidence,
+        });
+    }
+    /** Convenience: search with category=convention. Backward-compat camelCase API. */
+    async searchConventions(query, opts) {
+        return this.search(query, {
+            category: 'convention',
+            stack_tags: opts?.stackTags,
+            repo_id: opts?.repoId,
+            limit: opts?.limit,
+            min_confidence: opts?.minConfidence,
+        });
+    }
+    /** True when the vector store is configured and healthy. */
+    async isAvailable() {
+        return this.vectorStore.isHealthy();
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Retrieve knowledge items by category using Qdrant filter scroll (no
+     * semantic query). Falls back to semantic search when filterKnowledge is
+     * not yet available on the store.
+     */
+    async _getByCategory(category, stack, limit = 20, minConfidence = 0.3) {
+        const healthy = await this.vectorStore.isHealthy();
+        if (!healthy) {
+            logger.warn(`KnowledgeSearch._getByCategory: Qdrant unavailable`, { category });
+            return [];
+        }
+        try {
+            const qdrantFilter = this._buildQdrantFilter({
+                category,
+                stack_tags: stack,
+                min_confidence: minConfidence,
+            });
+            // Use filterKnowledge (scroll-based, no semantic ranking) if available.
+            const store = this.vectorStore;
+            if (typeof store.filterKnowledge === 'function') {
+                const rawItems = await store.filterKnowledge(qdrantFilter, limit);
+                return rawItems
+                    .map((r) => this._payloadToKnowledgeItem(r.payload))
+                    .filter((item) => item !== null)
+                    .sort((a, b) => b.confidence - a.confidence);
+            }
+            // Fallback: semantic search using the category name as query.
+            // Less accurate but functional until filterKnowledge lands.
+            logger.debug(`KnowledgeSearch._getByCategory: filterKnowledge unavailable, ` +
+                `falling back to semantic search`, { category });
+            const results = await this.search(category, {
+                category: category,
+                stack_tags: stack,
+                limit,
+                min_confidence: minConfidence,
+            });
+            return results.map((r) => this._resultToKnowledgeItem(r));
+        }
+        catch (err) {
+            logger.warn(`KnowledgeSearch._getByCategory: failed`, {
+                category,
+                error: String(err),
+            });
+            return [];
+        }
+    }
+    /**
+     * Build the Qdrant filter object from search option components.
+     *
+     * We construct the full Qdrant filter shape directly here (not relying on
+     * QdrantVectorStore.buildFilter) because we need both "must" (AND) and
+     * "should" (OR) conditions which the simple flat-map builder cannot express.
+     *
+     * Qdrant filter reference:
+     *   { must: [...], should: [...], must_not: [...] }
+     *   Each condition: { key: string, match: { value } } or { key, range: { gte } }
+     */
+    _buildQdrantFilter(opts) {
+        const must = [];
+        const should = [];
+        if (opts.category) {
+            must.push({ key: 'category', match: { value: opts.category } });
+        }
+        // Hard-filter to a single repo (used when include_cross_repo is false).
+        if (opts.repo_id) {
+            must.push({ key: 'repo_id', match: { value: opts.repo_id } });
+        }
+        // Cross-repo sharing enforcement: when searching across repos, only include
+        // items that are either (a) from the caller's own repo, or (b) have sharing
+        // set to 'team' or 'public'. Private repos never leak into other repos.
+        //
+        // Qdrant filter logic:
+        //   must: [{ should: [
+        //     { repo_id == caller_repo_id },   ← own repo: always included
+        //     { sharing == 'team' },            ← team-shared repos
+        //     { sharing == 'public' },          ← public repos
+        //   ]}]
+        if (opts.caller_repo_id && !opts.repo_id) {
+            must.push({
+                should: [
+                    { key: 'repo_id', match: { value: opts.caller_repo_id } },
+                    { key: 'sharing', match: { value: 'team' } },
+                    { key: 'sharing', match: { value: 'public' } },
+                ],
+            });
+        }
+        else if (!opts.repo_id && !opts.caller_repo_id) {
+            // No caller repo context — only allow team/public items to prevent
+            // accidental exposure of private repo knowledge.
+            must.push({
+                should: [
+                    { key: 'sharing', match: { value: 'team' } },
+                    { key: 'sharing', match: { value: 'public' } },
+                ],
+            });
+        }
+        if (opts.min_confidence !== undefined && opts.min_confidence > 0) {
+            must.push({ key: 'confidence', range: { gte: opts.min_confidence } });
+        }
+        // stack_tags: require at least one matching tag (OR semantics).
+        if (opts.stack_tags && opts.stack_tags.length > 0) {
+            for (const tag of opts.stack_tags) {
+                should.push({ key: 'stack_tags', match: { value: tag } });
+            }
+        }
+        if (must.length === 0 && should.length === 0) {
+            return undefined;
+        }
+        const filter = {};
+        if (must.length > 0)
+            filter['must'] = must;
+        if (should.length > 0)
+            filter['should'] = should;
+        return filter;
+    }
+    /**
+     * Convert a KnowledgePayload from Qdrant into a KnowledgeItem.
+     * Returns null if required fields are missing.
+     */
+    _payloadToKnowledgeItem(payload) {
+        const p = payload;
+        if (!p.id || !p.title || !p.content)
+            return null;
+        return {
+            id: p.id,
+            title: p.title,
+            content: p.content,
+            stack_tags: Array.isArray(p.stack_tags) ? p.stack_tags : [],
+            confidence: p.confidence ?? 0,
+            source: p.source ?? 'manual',
+            source_phase: p.source_phase ?? null,
+            source_agent: p.source_agent ?? null,
+            created_at: p.created_at ?? Date.now(),
+            updated_at: p.updated_at ?? Date.now(),
+        };
+    }
+    /**
+     * Convert a KnowledgeSearchResult back to a KnowledgeItem shape.
+     * Used as a fallback when filterKnowledge is not available on the store.
+     */
+    _resultToKnowledgeItem(result) {
+        return {
+            id: result.id,
+            title: result.title,
+            content: result.content,
+            stack_tags: result.stack_tags,
+            confidence: result.confidence,
+            source: 'manual',
+            source_phase: null,
+            source_agent: null,
+            created_at: Date.now(),
+            updated_at: Date.now(),
+        };
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/knowledge/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/knowledge/search.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,8BAA8B;AAC9B,+EAA+E;AAC/E,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,sCAAsC;AACtC,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAC9E,0BAA0B;AAC1B,EAAE;AACF,iCAAiC;AACjC,mDAAmD;AACnD,0DAA0D;AAC1D,gFAAgF;AAChF,0DAA0D;AAE1D,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAkCrD,8EAA8E;AAC9E,mEAAmE;AACnE,yEAAyE;AACzE,oCAAoC;AACpC,8EAA8E;AAC9E,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,WAA8B;QAA9B,gBAAW,GAAX,WAAW,CAAmB;IAAG,CAAC;IAE/D,8EAA8E;IAC9E,4CAA4C;IAC5C,8EAA8E;IAE9E;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAOC;QAED,MAAM,EACJ,QAAQ,EACR,UAAU,EACV,OAAO,EACP,KAAK,GAAG,EAAE,EACV,kBAAkB,GAAG,IAAI,EACzB,cAAc,GAAG,GAAG,GACrB,GAAG,OAAO,IAAI,EAAE,CAAC;QAElB,wEAAwE;QACxE,uBAAuB;QACvB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,qEAAqE,EAAE;gBACjF,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;aAC1B,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,WAAqB,CAAC;QAC1B,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,mEAAmE,EAAE;gBAC/E,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,uBAAuB;QACvB,iEAAiE;QACjE,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,sBAAsB;QACtB,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC;YAC3C,QAAQ;YACR,UAAU;YACV,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;YACjD,cAAc,EAAE,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YACxD,cAAc;SACf,CAAC,CAAC;QAEH,IAAI,UAAkF,CAAC;QACvF,IAAI,CAAC;YACH,uEAAuE;YACvE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YAE5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,WAAW,EAAE;gBAClE,KAAK,EAAE,UAAU;gBACjB,mEAAmE;gBACnE,qEAAqE;gBACrE,qDAAqD;gBACrD,cAAc,EAAE,GAAG;gBACnB,MAAM,EAAE,YAAuC;aAChD,CAAC,CAAC;YAEH,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAA6C;aACzD,CAAC,CAAC,CAAC;QACN,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,uEAAuE,EAAE;gBACnF,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,iDAAiD;QACjD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACnC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAoC,CAAC;YACvD,MAAM,KAAK,GAAG,OAAO,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;YACjF,OAAO,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,GAAG,KAAK,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;QAExD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;gBAAE,MAAM;YAElC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAoC,CAAC;YACjD,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO;gBAAE,SAAS;YAE9C,MAAM,CAAC,IAAI,CAAC;gBACV,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,SAAS;gBACjC,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC;gBAC7B,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;gBAC3D,WAAW,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE;gBAC5B,eAAe,EAAE,CAAC,CAAC,YAAY;aAChC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE;YAChD,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACzB,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,QAAQ;YACR,gBAAgB,EAAE,CAAC,CAAC,OAAO;SAC5B,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,8EAA8E;IAC9E,mBAAmB;IACnB,8EAA8E;IAE9E;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CAAC,WAAmB,EAAE,WAAW,GAAG,IAAI;QAC3D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,2DAA2D,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YAC3F,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,KAAK,GAAG,IAAI,CAAC,WAGlB,CAAC;YAEF,IAAI,iBAAiB,GAAG,CAAC,CAAC;YAC1B,IAAI,kBAAkB,GAAG,CAAC,CAAC;YAE3B,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;gBAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;gBACvD,IAAI,QAAQ,EAAE,CAAC;oBACb,iBAAiB,GAAI,QAAQ,CAAC,YAAY,CAAwB,IAAI,CAAC,CAAC;oBACxE,kBAAkB,GAAI,QAAQ,CAAC,cAAc,CAAwB,IAAI,CAAC,CAAC;gBAC7E,CAAC;YACH,CAAC;YAED,MAAM,KAAK,GAA4B;gBACrC,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;gBACvB,YAAY,EAAE,kBAAkB,GAAG,CAAC;gBACpC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,iBAAiB,GAAG,WAAW,CAAC;aAC3D,CAAC;YAEF,IAAI,OAAO,KAAK,CAAC,mBAAmB,KAAK,UAAU,EAAE,CAAC;gBACpD,MAAM,KAAK,CAAC,mBAAmB,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;gBACpD,MAAM,CAAC,KAAK,CAAC,0CAA0C,EAAE;oBACvD,WAAW;oBACX,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC;oBACrC,aAAa,EAAE,KAAK,CAAC,YAAY,CAAC;iBACnC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CACV,8EAA8E,EAC9E,EAAE,WAAW,EAAE,CAChB,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,qDAAqD,EAAE;gBACjE,WAAW;gBACX,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CACd,KAAgB,EAChB,KAAK,GAAG,EAAE,EACV,aAAa,GAAG,GAAG;QAEnB,OAAO,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IACpE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CACf,MAAe,EACf,KAAK,GAAG,EAAE,EACV,aAAa,GAAG,GAAG;QAEnB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3C,OAAO,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IACpE,CAAC;IAED,8EAA8E;IAC9E,8EAA8E;IAC9E,8EAA8E;IAE9E,+EAA+E;IAC/E,KAAK,CAAC,aAAa,CACjB,KAAa,EACb,IAA+C;QAE/C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;YACxB,QAAQ,EAAE,QAAQ;YAClB,UAAU,EAAE,IAAI,EAAE,SAAS;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM;YACrB,KAAK,EAAE,IAAI,EAAE,KAAK;YAClB,cAAc,EAAE,IAAI,EAAE,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,eAAe,CACnB,KAAa,EACb,IAA+C;QAE/C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;YACxB,QAAQ,EAAE,UAAU;YACpB,UAAU,EAAE,IAAI,EAAE,SAAS;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM;YACrB,KAAK,EAAE,IAAI,EAAE,KAAK;YAClB,cAAc,EAAE,IAAI,EAAE,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,IAA+C;QAE/C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;YACxB,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,IAAI,EAAE,SAAS;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM;YACrB,KAAK,EAAE,IAAI,EAAE,KAAK;YAClB,cAAc,EAAE,IAAI,EAAE,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,iBAAiB,CACrB,KAAa,EACb,IAA+C;QAE/C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;YACxB,QAAQ,EAAE,YAAY;YACtB,UAAU,EAAE,IAAI,EAAE,SAAS;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM;YACrB,KAAK,EAAE,IAAI,EAAE,KAAK;YAClB,cAAc,EAAE,IAAI,EAAE,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;IACtC,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;OAIG;IACK,KAAK,CAAC,cAAc,CAC1B,QAA2B,EAC3B,KAAgB,EAChB,KAAK,GAAG,EAAE,EACV,aAAa,GAAG,GAAG;QAEnB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,oDAAoD,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAChF,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC;gBAC3C,QAAQ;gBACR,UAAU,EAAE,KAAK;gBACjB,cAAc,EAAE,aAAa;aAC9B,CAAC,CAAC;YAEH,wEAAwE;YACxE,MAAM,KAAK,GAAG,IAAI,CAAC,WAKlB,CAAC;YAEF,IAAI,OAAO,KAAK,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;gBAChD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,eAAe,CAC1C,YAAuC,EACvC,KAAK,CACN,CAAC;gBACF,OAAO,QAAQ;qBACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;qBACnD,MAAM,CAAC,CAAC,IAAI,EAAyB,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC;qBACtD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;YACjD,CAAC;YAED,8DAA8D;YAC9D,4DAA4D;YAC5D,MAAM,CAAC,KAAK,CACV,+DAA+D;gBAC/D,iCAAiC,EACjC,EAAE,QAAQ,EAAE,CACb,CAAC;YACF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAC1C,QAAQ,EAAE,QAA6B;gBACvC,UAAU,EAAE,KAAK;gBACjB,KAAK;gBACL,cAAc,EAAE,aAAa;aAC9B,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,wCAAwC,EAAE;gBACpD,QAAQ;gBACR,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;aACnB,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACK,kBAAkB,CAAC,IAM1B;QACC,MAAM,IAAI,GAAc,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,wEAAwE;QACxE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,4EAA4E;QAC5E,4EAA4E;QAC5E,wEAAwE;QACxE,EAAE;QACF,uBAAuB;QACvB,uBAAuB;QACvB,mEAAmE;QACnE,4DAA4D;QAC5D,uDAAuD;QACvD,QAAQ;QACR,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC;gBACR,MAAM,EAAE;oBACN,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE;oBACzD,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;oBAC5C,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;iBAC/C;aACF,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACjD,mEAAmE;YACnE,iDAAiD;YACjD,IAAI,CAAC,IAAI,CAAC;gBACR,MAAM,EAAE;oBACN,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;oBAC5C,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;iBAC/C;aACF,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,gEAAgE;QAChE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBAClC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAC3C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC;QAEjD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,uBAAuB,CAC7B,OAAgC;QAEhC,MAAM,CAAC,GAAG,OAAoC,CAAC;QAC/C,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAEjD,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;YAC3D,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC;YAC7B,MAAM,EAAG,CAAC,CAAC,MAAkC,IAAI,QAAQ;YACzD,YAAY,EAAG,CAAC,CAAC,YAA8C,IAAI,IAAI;YACvE,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI;YACpC,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE;YACtC,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE;SACvC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,sBAAsB,CAAC,MAA6B;QAC1D,OAAO;YACL,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,QAAQ;YAChB,YAAY,EAAE,IAAI;YAClB,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;YACtB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;SACvB,CAAC;IACJ,CAAC;CACF"}

package/dist/knowledge/store.d.ts

@@ -0,0 +1,76 @@
+import type { KnowledgeCategory, KnowledgeItem } from '../util/types.js';
+export type { KnowledgeCategory, KnowledgeItem } from '../util/types.js';
+export declare class KnowledgeYamlStore {
+    private readonly forgeDir;
+    private readonly knowledgeDir;
+    constructor(forgeDir: string);
+    /**
+     * Read all items from a single category file.
+     * Returns an empty array if the file does not exist or is empty.
+     */
+    readCategory(category: KnowledgeCategory): KnowledgeItem[];
+    /**
+     * Read all items across every category file, concatenated into one array.
+     * Items from each category are returned in file order, categories in the
+     * order defined by ALL_CATEGORIES.
+     */
+    readAll(): KnowledgeItem[];
+    /**
+     * Overwrite a category file with the supplied items array.
+     * Creates the knowledge directory if it does not exist.
+     * Passing an empty array produces a file containing `[]`.
+     */
+    writeCategory(category: KnowledgeCategory, items: KnowledgeItem[]): void;
+    /**
+     * Append a single item to the appropriate category file.
+     * The category is derived from the item's id prefix:
+     *   gotcha-*    → gotcha
+     *   pattern-*   → pattern
+     *   decision-*  → decision
+     *   convention-* → convention
+     *
+     * If the item does not match any prefix, it falls through to the pattern
+     * file as a safe default.
+     */
+    addItem(item: KnowledgeItem): void;
+    /**
+     * Update an existing item by id across all category files.
+     * Applies the supplied partial updates to the first matching item.
+     * Returns true if an item was found and updated, false otherwise.
+     */
+    updateItem(id: string, updates: Partial<KnowledgeItem>): boolean;
+    /**
+     * Remove an item by id across all category files.
+     * Returns true if an item was found and removed, false otherwise.
+     */
+    removeItem(id: string): boolean;
+    /**
+     * Create the .forge/knowledge/ directory and initialise empty YAML files
+     * for every category. Existing files are left untouched — initialize() is
+     * safe to call multiple times.
+     */
+    initialize(): void;
+    /**
+     * Compute a SHA-256 hash over the concatenated contents of all category
+     * files. Files that do not exist contribute an empty string to the hash.
+     * The hash changes whenever any item is added, updated, or removed, making
+     * it useful for cheap change detection without re-parsing every item.
+     */
+    getContentHash(): string;
+    /** Absolute path to the YAML file for a given category. */
+    private _filePath;
+    /** Ensure the knowledge directory exists. */
+    private _ensureDir;
+    /**
+     * Parse a YAML file and return its items.
+     * Returns [] when the file is missing, empty, or contains a YAML null
+     * (which is what an empty file or `---` alone produces).
+     */
+    private _readFile;
+    /**
+     * Derive the KnowledgeCategory for a given item based on its id prefix.
+     * Falls back to 'pattern' when the id does not match a known prefix.
+     */
+    private _categoryFromItem;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/knowledge/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/knowledge/store.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIzE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAmBzE,qBAAa,kBAAkB;IAGjB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,QAAQ,EAAE,MAAM;IAQ7C;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,aAAa,EAAE;IAK1D;;;;OAIG;IACH,OAAO,IAAI,aAAa,EAAE;IAQ1B;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,IAAI;IAWxE;;;;;;;;;;OAUG;IACH,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAelC;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO;IAkBhE;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAY/B;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAWlB;;;;;OAKG;IACH,cAAc,IAAI,MAAM;IAkBxB,2DAA2D;IAC3D,OAAO,CAAC,SAAS;IAIjB,6CAA6C;IAC7C,OAAO,CAAC,UAAU;IAMlB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IA8BjB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAQ1B"}