forge-server 0.1.0

package/dist/knowledge/store.js

@@ -0,0 +1,230 @@
+// KnowledgeYamlStore — reads and writes .forge/knowledge/*.yaml files.
+//
+// Each file is a YAML array of KnowledgeItem objects. The store maps
+// KnowledgeCategory values to dedicated files so items can be retrieved
+// by category without loading the full corpus.
+//
+// Design notes:
+// - File I/O is synchronous. The MCP server is single-threaded; sync I/O
+//   keeps the surface area small and the error handling straightforward.
+// - The store never caches in memory — every read hits the filesystem.
+//   This ensures multi-process safety (e.g. CLI + server running together)
+//   and keeps memory pressure low for a local dev tool.
+// - getContentHash() enables cheap change detection by the knowledge-keeper
+//   agent without re-parsing every item.
+import { parse, stringify } from 'yaml';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CATEGORY_FILES = {
+    gotcha: 'gotchas.yaml',
+    pattern: 'patterns.yaml',
+    decision: 'decisions.yaml',
+    convention: 'conventions.yaml',
+};
+const ALL_CATEGORIES = ['gotcha', 'pattern', 'decision', 'convention'];
+// ---------------------------------------------------------------------------
+// KnowledgeYamlStore
+// ---------------------------------------------------------------------------
+export class KnowledgeYamlStore {
+    forgeDir;
+    knowledgeDir;
+    constructor(forgeDir) {
+        this.forgeDir = forgeDir;
+        this.knowledgeDir = join(forgeDir, 'knowledge');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Read all items from a single category file.
+     * Returns an empty array if the file does not exist or is empty.
+     */
+    readCategory(category) {
+        const filePath = this._filePath(category);
+        return this._readFile(filePath);
+    }
+    /**
+     * 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() {
+        const result = [];
+        for (const category of ALL_CATEGORIES) {
+            result.push(...this.readCategory(category));
+        }
+        return result;
+    }
+    /**
+     * 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, items) {
+        this._ensureDir();
+        const filePath = this._filePath(category);
+        const yaml = stringify(items, {
+            indent: 2,
+            // Use block scalars for long content strings so diffs are readable.
+            defaultStringType: 'PLAIN',
+        });
+        writeFileSync(filePath, yaml, 'utf8');
+    }
+    /**
+     * 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) {
+        const category = this._categoryFromItem(item);
+        const existing = this.readCategory(category);
+        // Deduplicate by id — if an item with this id already exists, replace it.
+        const idx = existing.findIndex((i) => i.id === item.id);
+        if (idx >= 0) {
+            existing[idx] = item;
+        }
+        else {
+            existing.push(item);
+        }
+        this.writeCategory(category, existing);
+    }
+    /**
+     * 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, updates) {
+        for (const category of ALL_CATEGORIES) {
+            const items = this.readCategory(category);
+            const idx = items.findIndex((i) => i.id === id);
+            if (idx >= 0) {
+                items[idx] = {
+                    ...items[idx],
+                    ...updates,
+                    // Always bump updated_at when the caller hasn't supplied it.
+                    updated_at: updates.updated_at ?? Date.now(),
+                };
+                this.writeCategory(category, items);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Remove an item by id across all category files.
+     * Returns true if an item was found and removed, false otherwise.
+     */
+    removeItem(id) {
+        for (const category of ALL_CATEGORIES) {
+            const items = this.readCategory(category);
+            const filtered = items.filter((i) => i.id !== id);
+            if (filtered.length < items.length) {
+                this.writeCategory(category, filtered);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * 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() {
+        this._ensureDir();
+        for (const category of ALL_CATEGORIES) {
+            const filePath = this._filePath(category);
+            if (!existsSync(filePath)) {
+                // Write an empty YAML array so the file is valid YAML from the start.
+                writeFileSync(filePath, '[]\n', 'utf8');
+            }
+        }
+    }
+    /**
+     * 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() {
+        const hash = createHash('sha256');
+        for (const category of ALL_CATEGORIES) {
+            const filePath = this._filePath(category);
+            if (existsSync(filePath)) {
+                const content = readFileSync(filePath, 'utf8');
+                hash.update(content);
+            }
+            else {
+                hash.update('');
+            }
+        }
+        return hash.digest('hex');
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /** Absolute path to the YAML file for a given category. */
+    _filePath(category) {
+        return join(this.knowledgeDir, CATEGORY_FILES[category]);
+    }
+    /** Ensure the knowledge directory exists. */
+    _ensureDir() {
+        if (!existsSync(this.knowledgeDir)) {
+            mkdirSync(this.knowledgeDir, { recursive: true });
+        }
+    }
+    /**
+     * 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).
+     */
+    _readFile(filePath) {
+        if (!existsSync(filePath)) {
+            return [];
+        }
+        // Guard against zero-byte files — parse('') returns null in the yaml
+        // package, not an empty array.
+        const stat = statSync(filePath);
+        if (stat.size === 0) {
+            return [];
+        }
+        const content = readFileSync(filePath, 'utf8');
+        const parsed = parse(content);
+        if (parsed === null || parsed === undefined) {
+            return [];
+        }
+        if (!Array.isArray(parsed)) {
+            throw new Error(`KnowledgeYamlStore: expected array at ${filePath}, got ${typeof parsed}`);
+        }
+        // Cast: the YAML is authoritative. Callers writing items go through our
+        // typed addItem/writeCategory methods so the shape is always correct.
+        return parsed;
+    }
+    /**
+     * 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.
+     */
+    _categoryFromItem(item) {
+        const id = item.id.toLowerCase();
+        if (id.startsWith('gotcha'))
+            return 'gotcha';
+        if (id.startsWith('pattern'))
+            return 'pattern';
+        if (id.startsWith('decision'))
+            return 'decision';
+        if (id.startsWith('convention'))
+            return 'convention';
+        return 'pattern';
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/knowledge/store.js.map

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

package/dist/learning/confidence.d.ts

@@ -0,0 +1,30 @@
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+export declare class ConfidenceManager {
+    /**
+     * Apply time-based confidence decay to all knowledge items in Qdrant.
+     *
+     * Algorithm:
+     * 1. Scroll through all knowledge items in pages of SCROLL_PAGE_SIZE.
+     * 2. For each item whose accessed_at is older than DECAY_GRACE_PERIOD_MS:
+     *    a. Compute new_confidence = max(MIN_CONFIDENCE, confidence - decayRate).
+     *    b. If new_confidence != confidence, call setPayload to update.
+     * 3. Return the total count of items whose confidence was updated.
+     *
+     * This method is intentionally slow (one HTTP call per decayed item) because
+     * it is designed to run as a background task, not in the hot path. A batch
+     * update path can be optimised once the volume of knowledge items justifies it.
+     */
+    decayAll(vectorStore: QdrantVectorStore, decayRate?: number): Promise<number>;
+    /**
+     * Boost the confidence of a specific knowledge item.
+     *
+     * Updates:
+     *   confidence  += amount (capped at MAX_CONFIDENCE)
+     *   accessed_at  = now
+     *   access_count += 1
+     *
+     * Fails silently on Qdrant errors — boosting is a best-effort operation.
+     */
+    boost(vectorStore: QdrantVectorStore, knowledgeId: string, amount?: number): Promise<void>;
+}
+//# sourceMappingURL=confidence.d.ts.map

package/dist/learning/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../../src/learning/confidence.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAwBpE,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;OAaG;IACG,QAAQ,CACZ,WAAW,EAAE,iBAAiB,EAC9B,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,MAAM,CAAC;IAoElB;;;;;;;;;OASG;IACG,KAAK,CACT,WAAW,EAAE,iBAAiB,EAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,MAAa,GACpB,OAAO,CAAC,IAAI,CAAC;CA0CjB"}

package/dist/learning/confidence.js

@@ -0,0 +1,165 @@
+// ConfidenceManager — B12
+//
+// Manages confidence score lifecycle for knowledge items stored in Qdrant.
+//
+// Confidence represents how well-validated a knowledge item is:
+//   0.0  – pure speculation, has never proven useful
+//   0.5  – moderate confidence, has been seen in a couple of contexts
+//   1.0  – very high confidence, validated across many projects
+//
+// Two operations:
+//
+//   decayAll(vectorStore, decayRate)
+//     Applies time-based confidence decay to all items that have not been
+//     accessed recently. Items accessed within the last 30 days are not
+//     decayed. The default decay rate is 0.01 per run (about 1 percentage
+//     point). Items whose confidence would fall below MIN_CONFIDENCE (0.1)
+//     are floored there rather than deleted — deletion is a policy decision
+//     for operators, not an automatic side effect of decay.
+//
+//   boost(vectorStore, knowledgeId, amount)
+//     Increases the confidence of a specific item by `amount` (default 0.05).
+//     Also bumps accessed_at and access_count. Capped at 1.0.
+//
+// Both methods are async and fail silently on Qdrant errors — confidence
+// management is best-effort. It must never block the pipeline.
+import { logger } from '../util/logger.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Items accessed within this window (ms) are not decayed. */
+const DECAY_GRACE_PERIOD_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/** Items whose confidence falls at or below this value are not decayed further. */
+const MIN_CONFIDENCE = 0.1;
+/** Maximum confidence a single boost can reach. */
+const MAX_CONFIDENCE = 1.0;
+/** How many knowledge items to scroll per Qdrant page during decay. */
+const SCROLL_PAGE_SIZE = 100;
+// ---------------------------------------------------------------------------
+// ConfidenceManager
+// ---------------------------------------------------------------------------
+export class ConfidenceManager {
+    /**
+     * Apply time-based confidence decay to all knowledge items in Qdrant.
+     *
+     * Algorithm:
+     * 1. Scroll through all knowledge items in pages of SCROLL_PAGE_SIZE.
+     * 2. For each item whose accessed_at is older than DECAY_GRACE_PERIOD_MS:
+     *    a. Compute new_confidence = max(MIN_CONFIDENCE, confidence - decayRate).
+     *    b. If new_confidence != confidence, call setPayload to update.
+     * 3. Return the total count of items whose confidence was updated.
+     *
+     * This method is intentionally slow (one HTTP call per decayed item) because
+     * it is designed to run as a background task, not in the hot path. A batch
+     * update path can be optimised once the volume of knowledge items justifies it.
+     */
+    async decayAll(vectorStore, decayRate = 0.01) {
+        const healthy = await vectorStore.isHealthy();
+        if (!healthy) {
+            logger.warn('ConfidenceManager.decayAll: Qdrant unavailable, skipping decay');
+            return 0;
+        }
+        const now = Date.now();
+        const graceCutoff = now - DECAY_GRACE_PERIOD_MS;
+        let decayedCount = 0;
+        // Use filterKnowledge (scroll with empty filter) to paginate through all
+        // knowledge items. setKnowledgePayload is used to patch confidence values.
+        // Both methods are real exports on QdrantVectorStore.
+        let page;
+        try {
+            page = await vectorStore.filterKnowledge({}, SCROLL_PAGE_SIZE);
+        }
+        catch (err) {
+            logger.warn('ConfidenceManager.decayAll: initial scroll failed, stopping', {
+                error: String(err),
+            });
+            return 0;
+        }
+        for (const point of page) {
+            const p = point.payload;
+            const accessedAt = p.accessed_at ?? 0;
+            const confidence = p.confidence ?? 0;
+            // Skip recently accessed items
+            if (accessedAt >= graceCutoff)
+                continue;
+            // Skip items already at floor
+            if (confidence <= MIN_CONFIDENCE)
+                continue;
+            const newConfidence = Math.max(MIN_CONFIDENCE, confidence - decayRate);
+            // Round to 4 decimal places to avoid floating-point drift
+            const rounded = Math.round(newConfidence * 10000) / 10000;
+            if (rounded === confidence)
+                continue; // No change needed
+            try {
+                await vectorStore.setKnowledgePayload(point.id, { confidence: rounded });
+                decayedCount++;
+                logger.debug('ConfidenceManager.decayAll: item decayed', {
+                    id: point.id,
+                    oldConfidence: confidence,
+                    newConfidence: rounded,
+                });
+            }
+            catch (err) {
+                // Non-fatal — log and continue to next item
+                logger.debug('ConfidenceManager.decayAll: failed to update item', {
+                    id: point.id,
+                    error: String(err),
+                });
+            }
+        }
+        logger.info('ConfidenceManager.decayAll: complete', {
+            decayedCount,
+            decayRate,
+        });
+        return decayedCount;
+    }
+    /**
+     * Boost the confidence of a specific knowledge item.
+     *
+     * Updates:
+     *   confidence  += amount (capped at MAX_CONFIDENCE)
+     *   accessed_at  = now
+     *   access_count += 1
+     *
+     * Fails silently on Qdrant errors — boosting is a best-effort operation.
+     */
+    async boost(vectorStore, knowledgeId, amount = 0.05) {
+        const healthy = await vectorStore.isHealthy();
+        if (!healthy) {
+            logger.debug('ConfidenceManager.boost: Qdrant unavailable, skip', { knowledgeId });
+            return;
+        }
+        try {
+            let currentConfidence = 0.5;
+            let currentAccessCount = 0;
+            const existing = await vectorStore.getKnowledge(knowledgeId);
+            if (!existing) {
+                logger.debug('ConfidenceManager.boost: item not found', { knowledgeId });
+                return;
+            }
+            const payload = existing;
+            currentConfidence = (typeof payload.confidence === 'number' ? payload.confidence : null) ?? 0.5;
+            currentAccessCount = (typeof payload.access_count === 'number' ? payload.access_count : null) ?? 0;
+            const newConfidence = Math.min(MAX_CONFIDENCE, currentConfidence + amount);
+            const rounded = Math.round(newConfidence * 10000) / 10000;
+            await vectorStore.setKnowledgePayload(knowledgeId, {
+                confidence: rounded,
+                accessed_at: Date.now(),
+                access_count: currentAccessCount + 1,
+            });
+            logger.debug('ConfidenceManager.boost: boosted', {
+                knowledgeId,
+                oldConfidence: currentConfidence,
+                newConfidence: rounded,
+                newAccessCount: currentAccessCount + 1,
+            });
+        }
+        catch (err) {
+            logger.warn('ConfidenceManager.boost: failed (non-fatal)', {
+                knowledgeId,
+                error: String(err),
+            });
+        }
+    }
+}
+//# sourceMappingURL=confidence.js.map

package/dist/learning/confidence.js.map

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

package/dist/learning/patterns.d.ts

@@ -0,0 +1,52 @@
+import type { PipelineDB } from '../storage/sqlite.js';
+import type { KnowledgeYamlStore } from '../knowledge/store.js';
+import type { KnowledgeSearch } from '../knowledge/search.js';
+import type { KnowledgeItem, KnowledgeCategory, Phase, PipelinePhase } from '../util/types.js';
+import { embedText } from '../ingestion/embedder.js';
+/** Minimum quality score for a step to be considered a candidate. */
+declare const QUALITY_THRESHOLD = 0.7;
+/** Words that strongly suggest a step contains a gotcha / pain point. */
+declare const GOTCHA_KEYWORDS: string[];
+/** Words that suggest a step contains a positive pattern. */
+declare const PATTERN_KEYWORDS: string[];
+export declare class PatternExtractor {
+    private readonly db;
+    private readonly knowledgeStore;
+    private readonly knowledgeSearch;
+    private readonly embedder;
+    constructor(db: PipelineDB, knowledgeStore: KnowledgeYamlStore, knowledgeSearch: KnowledgeSearch, embedder: typeof embedText);
+    /**
+     * Extract knowledge from all trajectory steps of a completed project.
+     *
+     * Algorithm:
+     * 1. Load all trajectories + their steps for the project.
+     * 2. Collect steps that are either:
+     *    a. High quality (qualityScore >= QUALITY_THRESHOLD), or
+     *    b. Contain gotcha-like language in action/result text.
+     * 3. For each candidate step, determine whether it looks like a gotcha
+     *    or a pattern (keyword matching).
+     * 4. Deduplicate against existing knowledge (semantic similarity check).
+     * 5. Promote unique candidates to KnowledgeItem records.
+     * 6. Return the list of newly created items.
+     */
+    extractFromProject(projectId: string): Promise<KnowledgeItem[]>;
+    /**
+     * Promote a raw observation string to a full KnowledgeItem.
+     *
+     * Steps:
+     * 1. Synthesise a title from the first sentence of the observation.
+     * 2. Build a KnowledgeItem with appropriate defaults.
+     * 3. Add to the YAML store (the git-tracked source of truth).
+     * 4. Embed and upsert to Qdrant via hydrateItem() (if available).
+     * 5. Return the new item.
+     */
+    promoteToKnowledge(observation: string, category: KnowledgeCategory, repoId: string, phase?: Phase | PipelinePhase, agent?: string): Promise<KnowledgeItem>;
+    /**
+     * Check whether the observation text is semantically too close to an
+     * existing knowledge item (similarity > 0.92). If so, we skip promotion
+     * to avoid building up near-duplicate entries over many projects.
+     */
+    private isDuplicateKnowledge;
+}
+export { GOTCHA_KEYWORDS, PATTERN_KEYWORDS, QUALITY_THRESHOLD };
+//# sourceMappingURL=patterns.d.ts.map

package/dist/learning/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../src/learning/patterns.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,KAAK,EACL,aAAa,EAGd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAOrD,qEAAqE;AACrE,QAAA,MAAM,iBAAiB,MAAM,CAAC;AAE9B,yEAAyE;AACzE,QAAA,MAAM,eAAe,UAgBpB,CAAC;AAEF,6DAA6D;AAC7D,QAAA,MAAM,gBAAgB,UAWrB,CAAC;AAMF,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAHR,EAAE,EAAE,UAAU,EACd,cAAc,EAAE,kBAAkB,EAClC,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,OAAO,SAAS;IAG7C;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA2FrE;;;;;;;;;OASG;IACG,kBAAkB,CACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,KAAK,GAAG,aAAa,EAC7B,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC;IAgFzB;;;;OAIG;YACW,oBAAoB;CAiBnC;AAkDD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC"}