forge-server 0.1.0

package/dist/knowledge/hydrator.d.ts

@@ -0,0 +1,37 @@
+import type { KnowledgeYamlStore } from './store.js';
+import type { QdrantVectorStore } from '../storage/qdrant-store.js';
+import type { KnowledgeItem } from '../util/types.js';
+import { embedText } from '../ingestion/embedder.js';
+export declare class KnowledgeHydrator {
+    private readonly yamlStore;
+    private readonly vectorStore;
+    private readonly embedder;
+    constructor(yamlStore: KnowledgeYamlStore, vectorStore: QdrantVectorStore, embedder?: typeof embedText);
+    /**
+     * Hydrate the Qdrant knowledge collection from all YAML files for a given
+     * repo. Deletes any existing points for this repo first (handles removals),
+     * then upserts all current items.
+     *
+     * Returns the count of items successfully loaded.
+     * Returns 0 and logs a warning if Qdrant is unavailable.
+     */
+    hydrate(repoId: string, sharing: string): Promise<number>;
+    /**
+     * Hydrate a single knowledge item into Qdrant.
+     * Used for incremental updates (e.g. after a single item is added via the
+     * knowledge-keeper agent) without re-hydrating the entire corpus.
+     */
+    hydrateItem(item: KnowledgeItem, repoId: string, sharing: string): Promise<void>;
+    /**
+     * Remove all knowledge items for a repo from Qdrant.
+     * Called by hydrate() before re-upserting, and by RepoRegistry.removeRepo().
+     * Silently succeeds if Qdrant is unavailable.
+     */
+    removeRepo(repoId: string): Promise<void>;
+    /**
+     * Derive category string from item id prefix.
+     * Mirrors the logic in KnowledgeYamlStore._categoryFromItem().
+     */
+    private _categoryFromId;
+}
+//# sourceMappingURL=hydrator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hydrator.d.ts","sourceRoot":"","sources":["../../src/knowledge/hydrator.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAc,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEjE,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAG5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAJR,SAAS,EAAE,kBAAkB,EAC7B,WAAW,EAAE,iBAAiB,EAG9B,QAAQ,GAAE,OAAO,SAAqB;IAOzD;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsF/D;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDtF;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C/C;;;OAGG;IACH,OAAO,CAAC,eAAe;CAQxB"}

package/dist/knowledge/hydrator.js

@@ -0,0 +1,220 @@
+// KnowledgeHydrator — syncs knowledge from YAML files into Qdrant's knowledge collection.
+//
+// The YAML files in .forge/knowledge/ are the source of truth. Qdrant is the
+// search index. The hydrator reads all items from the YAML store, embeds them,
+// and upserts into Qdrant. On re-hydration (after a manifest hash change) it
+// first deletes all Qdrant points for the repo to handle removals cleanly.
+//
+// Design notes:
+// - embedBatch() is used for bulk hydration instead of embedText() per item
+//   to amortise model inference overhead across all items.
+// - If Qdrant is unavailable the method logs a warning and returns 0 — the
+//   caller (RepoRegistry) treats this as a non-fatal result and records the
+//   item count as 0 in the registration response.
+// - The class accepts `embedder` as a constructor parameter (a reference to
+//   the embedBatch function) so tests can substitute a deterministic fake
+//   without dynamic import mocking.
+import { logger } from '../util/logger.js';
+import { embedBatch, embedText } from '../ingestion/embedder.js';
+export class KnowledgeHydrator {
+    yamlStore;
+    vectorStore;
+    embedder;
+    constructor(yamlStore, vectorStore, 
+    // Accept embedder as a parameter for testability. Defaults to the real embedBatch.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    embedder = embedText) {
+        this.yamlStore = yamlStore;
+        this.vectorStore = vectorStore;
+        this.embedder = embedder;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Hydrate the Qdrant knowledge collection from all YAML files for a given
+     * repo. Deletes any existing points for this repo first (handles removals),
+     * then upserts all current items.
+     *
+     * Returns the count of items successfully loaded.
+     * Returns 0 and logs a warning if Qdrant is unavailable.
+     */
+    async hydrate(repoId, sharing) {
+        const items = this.yamlStore.readAll();
+        if (items.length === 0) {
+            logger.debug('KnowledgeHydrator: no items to hydrate', { repoId });
+            return 0;
+        }
+        // Check Qdrant availability before attempting any operations.
+        const qdrantHealthy = await this.vectorStore.isHealthy();
+        if (!qdrantHealthy) {
+            logger.warn('KnowledgeHydrator: Qdrant unavailable, skipping hydration', { repoId });
+            return 0;
+        }
+        try {
+            // Remove all existing Qdrant points for this repo so that deletions
+            // in the YAML are reflected — a simple upsert-only approach would leave
+            // orphaned points for removed items.
+            await this.removeRepo(repoId);
+            // Embed all items in one batch call to amortise model init cost.
+            const texts = items.map((item) => `${item.title} ${item.content}`);
+            let vectors;
+            // embedBatch returns parallel arrays; embedText (the embedder param)
+            // is a single-text function. When the injected embedder is embedText
+            // we upgrade to batch mode internally. This gives tests a simple stub
+            // interface while production uses the efficient batch path.
+            if (this.embedder === embedText) {
+                vectors = await embedBatch(texts);
+            }
+            else {
+                // Fallback: call the injected embedder once per item. Used in tests.
+                vectors = await Promise.all(texts.map((t) => this.embedder(t)));
+            }
+            // Upsert each item with its vector and full KnowledgePayload.
+            const now = Date.now();
+            let loadedCount = 0;
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const vector = vectors[i];
+                const payload = {
+                    id: item.id,
+                    repo_id: repoId,
+                    category: this._categoryFromId(item.id),
+                    title: item.title,
+                    content: item.content,
+                    stack_tags: item.stack_tags,
+                    confidence: item.confidence,
+                    source: item.source,
+                    source_phase: item.source_phase,
+                    source_agent: item.source_agent,
+                    sharing,
+                    created_at: item.created_at,
+                    updated_at: item.updated_at,
+                    accessed_at: now,
+                    access_count: 0,
+                };
+                await this.vectorStore.upsertKnowledge(item.id, vector, payload);
+                loadedCount++;
+            }
+            logger.info('KnowledgeHydrator: hydration complete', {
+                repoId,
+                itemCount: loadedCount,
+                sharing,
+            });
+            return loadedCount;
+        }
+        catch (err) {
+            logger.warn('KnowledgeHydrator: hydration failed', {
+                repoId,
+                error: String(err),
+            });
+            return 0;
+        }
+    }
+    /**
+     * Hydrate a single knowledge item into Qdrant.
+     * Used for incremental updates (e.g. after a single item is added via the
+     * knowledge-keeper agent) without re-hydrating the entire corpus.
+     */
+    async hydrateItem(item, repoId, sharing) {
+        const qdrantHealthy = await this.vectorStore.isHealthy();
+        if (!qdrantHealthy) {
+            logger.warn('KnowledgeHydrator.hydrateItem: Qdrant unavailable', { id: item.id, repoId });
+            return;
+        }
+        try {
+            const text = `${item.title} ${item.content}`;
+            const vector = await this.embedder(text);
+            const now = Date.now();
+            const payload = {
+                id: item.id,
+                repo_id: repoId,
+                category: this._categoryFromId(item.id),
+                title: item.title,
+                content: item.content,
+                stack_tags: item.stack_tags,
+                confidence: item.confidence,
+                source: item.source,
+                source_phase: item.source_phase,
+                source_agent: item.source_agent,
+                sharing,
+                created_at: item.created_at,
+                updated_at: item.updated_at,
+                accessed_at: now,
+                access_count: 0,
+            };
+            await this.vectorStore.upsertKnowledge(item.id, vector, payload);
+            logger.debug('KnowledgeHydrator.hydrateItem: item hydrated', {
+                id: item.id,
+                repoId,
+            });
+        }
+        catch (err) {
+            logger.warn('KnowledgeHydrator.hydrateItem: failed', {
+                id: item.id,
+                repoId,
+                error: String(err),
+            });
+            throw err;
+        }
+    }
+    /**
+     * Remove all knowledge items for a repo from Qdrant.
+     * Called by hydrate() before re-upserting, and by RepoRegistry.removeRepo().
+     * Silently succeeds if Qdrant is unavailable.
+     */
+    async removeRepo(repoId) {
+        try {
+            // QdrantVectorStore.deleteKnowledge deletes by point ID.
+            // To delete ALL points for a repo we use the scroll+delete pattern via
+            // the Qdrant client's filter-based delete which the QdrantVectorStore
+            // exposes as deleteKnowledgeByRepo.
+            //
+            // The QdrantVectorStore may not have a deleteKnowledgeByRepo method yet.
+            // We call it if present; otherwise we fall through to the no-op with a
+            // log so the caller knows why old points were not removed.
+            const store = this.vectorStore;
+            if (typeof store.deleteKnowledgeByRepo === 'function') {
+                await store.deleteKnowledgeByRepo(repoId);
+                logger.debug('KnowledgeHydrator.removeRepo: deleted existing points', { repoId });
+            }
+            else {
+                // Fallback: the store does not yet expose bulk-delete-by-repo for the
+                // knowledge collection. Log so the operator is aware that stale items
+                // may accumulate. This is non-fatal — upserts will overwrite matching
+                // IDs and only truly removed items will remain as orphans.
+                logger.debug('KnowledgeHydrator.removeRepo: deleteKnowledgeByRepo not available, ' +
+                    'orphaned points may remain for removed items. Upserts will overwrite matching IDs.', { repoId });
+            }
+        }
+        catch (err) {
+            // Graceful degradation: if Qdrant is down or the delete fails, hydration
+            // should still proceed with upserts — better to have stale items than
+            // to completely block registration.
+            logger.warn('KnowledgeHydrator.removeRepo: delete failed (continuing)', {
+                repoId,
+                error: String(err),
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Derive category string from item id prefix.
+     * Mirrors the logic in KnowledgeYamlStore._categoryFromItem().
+     */
+    _categoryFromId(id) {
+        const lower = id.toLowerCase();
+        if (lower.startsWith('gotcha'))
+            return 'gotcha';
+        if (lower.startsWith('pattern'))
+            return 'pattern';
+        if (lower.startsWith('decision'))
+            return 'decision';
+        if (lower.startsWith('convention'))
+            return 'convention';
+        return 'pattern';
+    }
+}
+//# sourceMappingURL=hydrator.js.map

package/dist/knowledge/hydrator.js.map

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

package/dist/knowledge/registry.d.ts

@@ -0,0 +1,129 @@
+import type { PipelineDB } from '../storage/sqlite.js';
+import { KnowledgeHydrator } from './hydrator.js';
+import type { Repo, ForgeManifest, SharingMode } from '../util/types.js';
+export interface RegisterOptions {
+    auto?: boolean;
+}
+/**
+ * Matches the spec B5 return shape (snake_case for MCP tool compat).
+ */
+export interface RegisterResult {
+    repo_id: string;
+    name: string;
+    path: string;
+    remote?: string;
+    stack: string[];
+    sharing: string;
+    newly_registered: boolean;
+    knowledge_items_loaded: number;
+}
+export interface InitOptions {
+    name: string;
+    stack: string[];
+    sharing?: SharingMode;
+    org?: string;
+}
+export interface RegisterResultCamel {
+    repoId: string;
+    name: string;
+    path: string;
+    remote?: string;
+    stack: string[];
+    sharing: SharingMode;
+    newlyRegistered: boolean;
+    knowledgeItemsLoaded: number;
+}
+export declare class RepoRegistry {
+    private readonly db;
+    private readonly hydrator?;
+    constructor(db: PipelineDB, hydrator?: KnowledgeHydrator | undefined);
+    /**
+     * Register (or update) a repo at `path`.
+     *
+     * Requires a .forge/manifest.yaml to exist at <path>/.forge/manifest.yaml.
+     * If the manifest is absent, throws an error describing the fix.
+     *
+     * Steps:
+     *   1. Read manifest from .forge/manifest.yaml
+     *   2. Resolve git origin URL
+     *   3. Generate repo_id from origin URL (or path hash if no remote)
+     *   4. Upsert into SQLite repos table
+     *   5. Compute knowledge content hash and compare with stored hash
+     *   6. If hash changed (or newly registered), hydrate Qdrant knowledge collection
+     *   7. Return RegisterResult
+     */
+    register(path: string, options?: RegisterOptions): Promise<RegisterResult>;
+    /**
+     * Initialize the .forge/ directory in a repo at `repoPath`.
+     * Creates:
+     *   .forge/manifest.yaml          — from provided manifest
+     *   .forge/knowledge/gotchas.yaml
+     *   .forge/knowledge/patterns.yaml
+     *   .forge/knowledge/decisions.yaml
+     *   .forge/knowledge/conventions.yaml
+     *   .forge/.gitignore             — excludes .forge.db
+     *
+     * All files are created only if they do not already exist.
+     * Returns { forgePath, filesCreated } listing the paths that were created.
+     */
+    initForge(repoPath: string, manifest: ForgeManifest): {
+        forgePath: string;
+        filesCreated: string[];
+    };
+    /**
+     * Read and parse .forge/manifest.yaml from `forgePath` (the .forge/ directory).
+     * Returns null if the file is absent or unparseable.
+     *
+     * NOTE: This method takes the .forge/ directory path, NOT the repo root.
+     * Callers that have the repo root should pass join(repoPath, '.forge').
+     */
+    readManifest(forgePath: string): ForgeManifest | null;
+    /**
+     * Resolve the git remote origin URL for the repo at `repoPath`.
+     * Uses `git -C <repoPath> config --get remote.origin.url`.
+     * Returns null if the path is not a git repo or has no origin.
+     */
+    resolveGitOrigin(repoPath: string): string | null;
+    /**
+     * Generate a stable repo ID from a remote URL or local path.
+     * Uses SHA-256, returns first 12 hex characters.
+     *
+     * For remote URLs: normalises to strip .git suffix and trailing slashes
+     * before hashing so that git@github.com:org/repo and
+     * https://github.com/org/repo.git produce the same ID.
+     */
+    generateRepoId(remoteOrPath: string): string;
+    /**
+     * Get a registered repo by ID.
+     * Returns null if not found.
+     */
+    getRepo(repoId: string): Repo | null;
+    /**
+     * List all registered repos sorted by last_seen_at descending.
+     * Returns repos augmented with knowledge_count (total items in Qdrant).
+     * knowledge_count is always 0 when Qdrant is not available — it is a
+     * best-effort annotation, not a blocking query.
+     */
+    listRepos(): Array<Repo & {
+        knowledge_count: number;
+    }>;
+    /**
+     * Update the last_seen_at timestamp for a repo.
+     * Called on session-start to record that the repo is actively being used.
+     */
+    touch(repoId: string): void;
+    /**
+     * Remove a repo from the registry.
+     * Does NOT remove Qdrant knowledge items — call hydrator.removeRepo() separately
+     * if you want to clean up vector data.
+     */
+    removeRepo(repoId: string): void;
+    /** Whether a .forge/ directory exists in the given repo path. */
+    forgeDirectoryExists(repoPath?: string): boolean;
+    /** Find a registered repo by its filesystem path. */
+    findRepoByPath(repoPath: string): Repo | null;
+    private _parseManifestFile;
+    private _repoNameFromPath;
+    private _rowToRepo;
+}
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/knowledge/registry.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAW,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAoBlF,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAMD,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBADT,EAAE,EAAE,UAAU,EACd,QAAQ,CAAC,EAAE,iBAAiB,YAAA;IAO/C;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC;IA0G1B;;;;;;;;;;;;OAYG;IACH,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,aAAa,GACtB;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE;IAsDhD;;;;;;OAMG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAUrD;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAqBjD;;;;;;;OAOG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAa5C;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKpC;;;;;OAKG;IACH,SAAS,IAAI,KAAK,CAAC,IAAI,GAAG;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAWtD;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO3B;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAShC,iEAAiE;IACjE,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAKhD,qDAAqD;IACrD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAU7C,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,UAAU;CAoBnB"}