@syntesseraai/opencode-feature-factory 0.3.0 → 0.3.1

package/dist/local-recall/vector/orama-index.js

@@ -0,0 +1,379 @@
+import { create, insert, search as oramaSearch } from '@orama/orama';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const INDEX_VERSION = 1;
+const EMBED_BATCH_SIZE = 16;
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function isVector(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'number');
+}
+function matchesFilters(document, criteria) {
+    if (criteria.category && document.category !== criteria.category) {
+        return false;
+    }
+    if (criteria.sessionID && document.sessionID !== criteria.sessionID) {
+        return false;
+    }
+    if (criteria.minImportance !== undefined && document.importance < criteria.minImportance) {
+        return false;
+    }
+    if (criteria.tags && criteria.tags.length > 0) {
+        const expected = new Set(criteria.tags.map((tag) => tag.toLowerCase()));
+        const actual = new Set(document.tags.map((tag) => tag.toLowerCase()));
+        const hasAnyTag = Array.from(expected).some((tag) => actual.has(tag));
+        if (!hasAnyTag) {
+            return false;
+        }
+    }
+    return true;
+}
+function toSearchResult(document, relevance) {
+    return {
+        id: document.id,
+        sessionID: document.sessionID,
+        category: document.category,
+        title: document.title,
+        tags: document.tags,
+        importance: document.importance,
+        createdAt: document.createdAt,
+        relevance,
+    };
+}
+function validateDocument(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const candidate = raw;
+    if (typeof candidate.id !== 'string' ||
+        typeof candidate.sessionID !== 'string' ||
+        typeof candidate.messageID !== 'string' ||
+        typeof candidate.category !== 'string' ||
+        typeof candidate.title !== 'string' ||
+        typeof candidate.body !== 'string' ||
+        !Array.isArray(candidate.tags) ||
+        !candidate.tags.every((tag) => typeof tag === 'string') ||
+        typeof candidate.importance !== 'number' ||
+        typeof candidate.createdAt !== 'number' ||
+        !isVector(candidate.embedding)) {
+        return null;
+    }
+    return {
+        id: candidate.id,
+        sessionID: candidate.sessionID,
+        messageID: candidate.messageID,
+        category: candidate.category,
+        title: candidate.title,
+        body: candidate.body,
+        tags: candidate.tags,
+        importance: candidate.importance,
+        createdAt: candidate.createdAt,
+        embedding: candidate.embedding,
+    };
+}
+export class OramaMemoryIndex {
+    directory;
+    provider;
+    db = null;
+    documents = new Map();
+    dimensions = null;
+    updatedAt = null;
+    constructor(directory, provider) {
+        this.directory = directory;
+        this.provider = provider;
+    }
+    async initialize() {
+        await mkdir(this.indexDir, { recursive: true });
+        await this.loadSnapshot();
+        if (this.documents.size > 0 && this.dimensions) {
+            await this.ensureDB(this.dimensions);
+            await this.hydrateDB();
+        }
+    }
+    getStatus() {
+        return {
+            documents: this.documents.size,
+            dimensions: this.dimensions,
+            provider: this.provider.name,
+            model: this.provider.model,
+            updatedAt: this.updatedAt,
+        };
+    }
+    async search(criteria) {
+        const limit = clamp(criteria.limit ?? 10, 1, 50);
+        if (this.documents.size === 0) {
+            return [];
+        }
+        const query = criteria.query.trim();
+        if (!query) {
+            const filtered = Array.from(this.documents.values())
+                .filter((document) => matchesFilters(document, criteria))
+                .sort((a, b) => b.importance - a.importance || b.createdAt - a.createdAt)
+                .slice(0, limit)
+                .map((document) => toSearchResult(document, 0));
+            return filtered;
+        }
+        const [queryEmbedding] = await this.provider.embed([query]);
+        if (!queryEmbedding) {
+            return [];
+        }
+        await this.ensureDB(queryEmbedding.length);
+        if (!this.db) {
+            return [];
+        }
+        const response = (await oramaSearch(this.db, {
+            mode: 'hybrid',
+            term: query,
+            vector: {
+                property: 'embedding',
+                value: queryEmbedding,
+            },
+            limit: Math.max(limit * 4, 10),
+        }));
+        const matches = [];
+        for (const hit of response.hits ?? []) {
+            const document = hit.document ?? (hit.id ? this.documents.get(hit.id) : undefined);
+            if (!document || !matchesFilters(document, criteria)) {
+                continue;
+            }
+            matches.push(toSearchResult(document, hit.score ?? 0));
+        }
+        matches.sort((a, b) => {
+            const scoreA = a.relevance * a.importance;
+            const scoreB = b.relevance * b.importance;
+            return scoreB - scoreA;
+        });
+        return matches.slice(0, limit);
+    }
+    async upsertMemories(memories) {
+        if (memories.length === 0) {
+            return 0;
+        }
+        const inputs = memories.map((memory) => this.memoryToEmbeddingInput(memory));
+        const embeddings = await this.embedBatch(inputs);
+        const dimensions = this.assertEmbeddingDimensions(embeddings);
+        for (let index = 0; index < memories.length; index++) {
+            const memory = memories[index];
+            const embedding = embeddings[index];
+            if (!memory || !embedding) {
+                continue;
+            }
+            const document = this.toDocument(memory, embedding);
+            this.documents.set(document.id, document);
+        }
+        await this.rebuildDatabaseFromDocuments(dimensions);
+        this.updatedAt = new Date().toISOString();
+        await this.persistSnapshot();
+        return memories.length;
+    }
+    async removeMemories(memoryIDs) {
+        if (memoryIDs.length === 0) {
+            return 0;
+        }
+        let removedCount = 0;
+        for (const memoryID of memoryIDs) {
+            if (!this.documents.has(memoryID)) {
+                continue;
+            }
+            this.documents.delete(memoryID);
+            removedCount++;
+        }
+        if (removedCount > 0) {
+            await this.rebuildDatabaseFromDocuments();
+            this.updatedAt = new Date().toISOString();
+            await this.persistSnapshot();
+        }
+        return removedCount;
+    }
+    async rebuild(memories) {
+        this.documents.clear();
+        if (memories.length === 0) {
+            this.db = null;
+            this.dimensions = this.provider.dimensions ?? null;
+            this.updatedAt = new Date().toISOString();
+            await this.persistSnapshot();
+            return 0;
+        }
+        const inputs = memories.map((memory) => this.memoryToEmbeddingInput(memory));
+        const embeddings = await this.embedBatch(inputs);
+        const dimensions = this.assertEmbeddingDimensions(embeddings);
+        for (let index = 0; index < memories.length; index++) {
+            const memory = memories[index];
+            const embedding = embeddings[index];
+            if (!memory || !embedding) {
+                continue;
+            }
+            const document = this.toDocument(memory, embedding);
+            this.documents.set(document.id, document);
+        }
+        await this.rebuildDatabaseFromDocuments(dimensions);
+        this.updatedAt = new Date().toISOString();
+        await this.persistSnapshot();
+        return memories.length;
+    }
+    get indexDir() {
+        return path.join(this.directory, '.feature-factory', 'local-recall', 'index');
+    }
+    get manifestPath() {
+        return path.join(this.indexDir, 'manifest.json');
+    }
+    get documentsPath() {
+        return path.join(this.indexDir, 'documents.json');
+    }
+    buildSchema(dimensions) {
+        return {
+            id: 'string',
+            sessionID: 'string',
+            messageID: 'string',
+            category: 'string',
+            title: 'string',
+            body: 'string',
+            tags: 'string[]',
+            importance: 'number',
+            createdAt: 'number',
+            embedding: `vector[${dimensions}]`,
+        };
+    }
+    async ensureDB(dimensions) {
+        if (this.db && this.dimensions === dimensions) {
+            return;
+        }
+        this.dimensions = dimensions;
+        this.db = await create({
+            schema: this.buildSchema(dimensions),
+        });
+        await this.hydrateDB();
+    }
+    async rebuildDatabaseFromDocuments(dimensions) {
+        if (this.documents.size === 0) {
+            this.db = null;
+            if (dimensions) {
+                this.dimensions = dimensions;
+            }
+            return;
+        }
+        const inferredDimensions = dimensions ??
+            this.dimensions ??
+            Array.from(this.documents.values())[0]?.embedding.length ??
+            0;
+        if (inferredDimensions <= 0) {
+            throw new Error('Cannot rebuild vector index without known embedding dimensions');
+        }
+        this.dimensions = inferredDimensions;
+        this.db = await create({
+            schema: this.buildSchema(inferredDimensions),
+        });
+        for (const document of this.documents.values()) {
+            if (document.embedding.length !== inferredDimensions) {
+                continue;
+            }
+            await insert(this.db, document);
+        }
+    }
+    async hydrateDB() {
+        if (!this.db) {
+            return;
+        }
+        for (const document of this.documents.values()) {
+            if (this.dimensions && document.embedding.length !== this.dimensions) {
+                continue;
+            }
+            await insert(this.db, document);
+        }
+    }
+    async loadSnapshot() {
+        let manifest = null;
+        let documents = [];
+        try {
+            const rawManifest = await readFile(this.manifestPath, 'utf-8');
+            manifest = JSON.parse(rawManifest);
+        }
+        catch {
+            manifest = null;
+        }
+        try {
+            const rawDocuments = await readFile(this.documentsPath, 'utf-8');
+            documents = JSON.parse(rawDocuments);
+        }
+        catch {
+            documents = [];
+        }
+        for (const raw of documents) {
+            const document = validateDocument(raw);
+            if (!document) {
+                continue;
+            }
+            this.documents.set(document.id, document);
+        }
+        const inferredDimensions = Array.from(this.documents.values())[0]?.embedding.length ?? null;
+        this.dimensions =
+            manifest && typeof manifest.dimensions === 'number' && manifest.dimensions > 0
+                ? manifest.dimensions
+                : inferredDimensions;
+        this.updatedAt = manifest?.updatedAt ?? null;
+    }
+    async persistSnapshot() {
+        await mkdir(this.indexDir, { recursive: true });
+        const manifest = {
+            version: INDEX_VERSION,
+            provider: this.provider.name,
+            model: this.provider.model,
+            dimensions: this.dimensions ?? this.provider.dimensions ?? 0,
+            documents: this.documents.size,
+            updatedAt: this.updatedAt ?? new Date().toISOString(),
+        };
+        await this.writeAtomic(this.manifestPath, manifest);
+        await this.writeAtomic(this.documentsPath, Array.from(this.documents.values()));
+    }
+    async writeAtomic(filePath, value) {
+        const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(value, null, 2), 'utf-8');
+        await rename(tmpPath, filePath);
+    }
+    memoryToEmbeddingInput(memory) {
+        return `${memory.title}\n\n${memory.body}`.trim();
+    }
+    toDocument(memory, embedding) {
+        return {
+            id: memory.id,
+            sessionID: memory.sessionID,
+            messageID: memory.messageID,
+            category: memory.category,
+            title: memory.title,
+            body: memory.body,
+            tags: memory.tags,
+            importance: memory.importance,
+            createdAt: memory.createdAt,
+            embedding,
+        };
+    }
+    assertEmbeddingDimensions(vectors) {
+        const first = vectors[0];
+        if (!first) {
+            throw new Error('Embedding provider returned no vectors');
+        }
+        const dimensions = first.length;
+        if (dimensions === 0) {
+            throw new Error('Embedding provider returned empty vectors');
+        }
+        for (const vector of vectors) {
+            if (vector.length !== dimensions) {
+                throw new Error('Embedding provider returned mixed dimensions');
+            }
+        }
+        if (this.dimensions && this.dimensions !== dimensions) {
+            throw new Error(`Embedding dimensions changed from ${this.dimensions} to ${dimensions}; rebuild required`);
+        }
+        return dimensions;
+    }
+    async embedBatch(input) {
+        const embeddings = [];
+        for (let index = 0; index < input.length; index += EMBED_BATCH_SIZE) {
+            const chunk = input.slice(index, index + EMBED_BATCH_SIZE);
+            const chunkEmbeddings = await this.provider.embed(chunk);
+            embeddings.push(...chunkEmbeddings);
+        }
+        return embeddings;
+    }
+}

package/dist/local-recall/vector/types.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryCategory, MemorySearchResult } from '../types.js';
+export type EmbeddingProviderName = 'ollama' | 'openai';
+export interface EmbeddingProvider {
+    readonly name: EmbeddingProviderName;
+    readonly model: string;
+    readonly dimensions?: number;
+    embed(input: string[]): Promise<number[][]>;
+}
+export interface VectorIndexManifest {
+    version: number;
+    provider: EmbeddingProviderName;
+    model: string;
+    dimensions: number;
+    documents: number;
+    updatedAt: string;
+}
+export interface VectorIndexDocument {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    category: MemoryCategory;
+    title: string;
+    body: string;
+    tags: string[];
+    importance: number;
+    createdAt: number;
+    embedding: number[];
+}
+export interface VectorSearchResponse {
+    backend: 'vector' | 'lexical';
+    results: MemorySearchResult[];
+    fallbackReason?: string;
+}

package/dist/local-recall/vector/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp-config.d.ts

@@ -0,0 +1,63 @@
+type BunShell = any;
+/**
+ * Default MCP server configuration to be added by the plugin
+ * These servers will be merged into the project's opencode.json
+ */
+export declare const DEFAULT_MCP_SERVERS: {
+    readonly 'ff-local-recall': {
+        readonly type: "local";
+        readonly command: "ff-local-recall-mcp";
+        readonly enabled: true;
+    };
+    readonly 'jina-ai': {
+        readonly type: "remote";
+        readonly url: "https://mcp.jina.ai/v1";
+        readonly headers: {
+            readonly Authorization: "Bearer {env:JINAAI_API_KEY}";
+        };
+    };
+    readonly gh_grep: {
+        readonly type: "remote";
+        readonly url: "https://mcp.grep.app";
+    };
+    readonly context7: {
+        readonly type: "remote";
+        readonly url: "https://mcp.context7.com/mcp";
+        readonly headers: {
+            readonly CONTEXT7_API_KEY: "{env:CONTEXT7_API_KEY}";
+        };
+    };
+};
+export interface MCPServerConfig {
+    type: 'local' | 'remote';
+    command?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+}
+export interface MCPServers {
+    [serverName: string]: MCPServerConfig;
+}
+/**
+ * Merge MCP servers, preserving existing servers and adding new ones.
+ * Existing servers take precedence (we never overwrite them).
+ */
+export declare function mergeMCPServers(existing: MCPServers | undefined, defaults: typeof DEFAULT_MCP_SERVERS): MCPServers;
+/**
+ * Update the MCP servers configuration in opencode.json files.
+ *
+ * This function:
+ * 1. Reads existing config from both root and .opencode directories
+ * 2. Merges MCP servers from both configs (preserving all existing servers)
+ * 3. Adds default Feature Factory MCP servers that don't exist
+ * 4. Writes updated config to .opencode/opencode.json
+ *
+ * Note: Writing to .opencode/opencode.json keeps Feature Factory MCP config
+ * separate from the user's root opencode.json, following the same pattern
+ * as the quality gate configuration.
+ *
+ * @param $ - Bun shell instance
+ * @param directory - The project directory
+ */
+export declare function updateMCPConfig($: BunShell, directory: string): Promise<void>;
+export {};

package/dist/mcp-config.js

@@ -0,0 +1,121 @@
+import { readJsonFile } from './quality-gate-config.js';
+/**
+ * Default MCP server configuration to be added by the plugin
+ * These servers will be merged into the project's opencode.json
+ */
+export const DEFAULT_MCP_SERVERS = {
+    'ff-local-recall': {
+        type: 'local',
+        command: 'ff-local-recall-mcp',
+        enabled: true,
+    },
+    'jina-ai': {
+        type: 'remote',
+        url: 'https://mcp.jina.ai/v1',
+        headers: {
+            Authorization: 'Bearer {env:JINAAI_API_KEY}',
+        },
+    },
+    gh_grep: {
+        type: 'remote',
+        url: 'https://mcp.grep.app',
+    },
+    context7: {
+        type: 'remote',
+        url: 'https://mcp.context7.com/mcp',
+        headers: {
+            CONTEXT7_API_KEY: '{env:CONTEXT7_API_KEY}',
+        },
+    },
+};
+/**
+ * Merge MCP servers, preserving existing servers and adding new ones.
+ * Existing servers take precedence (we never overwrite them).
+ */
+export function mergeMCPServers(existing, defaults) {
+    const existingServers = existing ?? {};
+    const result = { ...existingServers };
+    // Add default servers that don't exist yet
+    for (const [serverName, serverConfig] of Object.entries(defaults)) {
+        if (!result[serverName]) {
+            result[serverName] = serverConfig;
+        }
+    }
+    return result;
+}
+/**
+ * Update the MCP servers configuration in opencode.json files.
+ *
+ * This function:
+ * 1. Reads existing config from both root and .opencode directories
+ * 2. Merges MCP servers from both configs (preserving all existing servers)
+ * 3. Adds default Feature Factory MCP servers that don't exist
+ * 4. Writes updated config to .opencode/opencode.json
+ *
+ * Note: Writing to .opencode/opencode.json keeps Feature Factory MCP config
+ * separate from the user's root opencode.json, following the same pattern
+ * as the quality gate configuration.
+ *
+ * @param $ - Bun shell instance
+ * @param directory - The project directory
+ */
+export async function updateMCPConfig($, directory) {
+    const rootConfigPath = `${directory}/opencode.json`;
+    const dotOpencodeConfigPath = `${directory}/.opencode/opencode.json`;
+    const dotOpencodeDir = `${directory}/.opencode`;
+    // Read existing configs
+    const [rootJson, dotOpencodeJson] = await Promise.all([
+        readJsonFile($, rootConfigPath),
+        readJsonFile($, dotOpencodeConfigPath),
+    ]);
+    // Get existing MCP servers from both configs
+    const rootMcpServers = (rootJson?.mcp ?? {});
+    const dotOpencodeMcpServers = (dotOpencodeJson?.mcp ?? {});
+    // Merge existing servers (dotOpencode overrides root)
+    const existingMcpServers = {
+        ...rootMcpServers,
+        ...dotOpencodeMcpServers,
+    };
+    // Merge with default MCP servers
+    const updatedMcpServers = mergeMCPServers(existingMcpServers, DEFAULT_MCP_SERVERS);
+    // Check if any changes are needed
+    const hasChanges = Object.keys(DEFAULT_MCP_SERVERS).some((serverName) => !existingMcpServers[serverName]);
+    if (!hasChanges) {
+        // All default servers already exist, no need to update
+        return;
+    }
+    // Prepare updated config for .opencode/opencode.json
+    const updatedDotOpencodeConfig = {
+        ...(dotOpencodeJson ?? {}),
+        mcp: updatedMcpServers,
+    };
+    // Ensure .opencode directory exists
+    try {
+        await $ `mkdir -p ${dotOpencodeDir}`.quiet();
+    }
+    catch {
+        // Directory might already exist, ignore
+    }
+    // Backup existing .opencode/opencode.json if it exists and has content
+    if (dotOpencodeJson && Object.keys(dotOpencodeJson).length > 0) {
+        try {
+            const timestamp = new Date().toISOString().split('T')[0].replace(/-/g, '');
+            const backupPath = `${dotOpencodeConfigPath}.backup.${timestamp}`;
+            const backupContent = JSON.stringify(dotOpencodeJson, null, 2);
+            await $ `echo ${backupContent} > ${backupPath}`.quiet();
+        }
+        catch (error) {
+            // Backup failed, but continue anyway
+            console.warn('[feature-factory] Could not create backup:', error);
+        }
+    }
+    // Write updated config to .opencode/opencode.json
+    const configContent = JSON.stringify(updatedDotOpencodeConfig, null, 2);
+    try {
+        await $ `echo ${configContent} > ${dotOpencodeConfigPath}`.quiet();
+    }
+    catch (error) {
+        // Silently fail - don't block if we can't write the config
+        console.warn('[feature-factory] Could not update MCP config:', error);
+    }
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ff-deploy": "./bin/ff-deploy.js"
+    "ff-deploy": "./bin/ff-deploy.js",
+    "ff-local-recall-mcp": "./bin/ff-local-recall-mcp.js"
   },
   "files": [
     "dist",
@@ -32,7 +33,9 @@
   ],
   "scripts": {},
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@opencode-ai/plugin": "^1.1.48",
+    "@orama/orama": "^3.0.0",
     "glob": "^10.0.0",
     "uuid": "^9.0.0"
   },