bluera-knowledge 0.17.1 → 0.18.0

package/dist/mcp/bootstrap.js

@@ -14,7 +14,8 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-var logDir = join(homedir(), ".bluera", "bluera-knowledge", "logs");
+var envProjectRoot = process.env["PROJECT_ROOT"];
+var logDir = envProjectRoot !== void 0 && envProjectRoot !== "" ? join(envProjectRoot, ".bluera", "bluera-knowledge", "logs") : join(homedir(), ".bluera", "bluera-knowledge", "logs");
 var logFile = join(logDir, "app.log");
 var log = (level, msg, data) => {
   try {
@@ -57,8 +58,26 @@ function installWithPackageManager() {
   })();
   const cmd = hasBun ? "bun install --frozen-lockfile" : "npm ci --silent";
   log("info", "Installing dependencies with package manager", { hasBun, cmd });
-  execSync(cmd, { cwd: pluginRoot, stdio: "inherit" });
-  log("info", "Dependencies installed via package manager");
+  try {
+    const output = execSync(cmd, { cwd: pluginRoot, stdio: "pipe" });
+    if (output.length > 0) {
+      log("debug", "Install output", { output: output.toString().trim() });
+    }
+    log("info", "Dependencies installed via package manager");
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorDetails = { message: errorMessage };
+    if (typeof error === "object" && error !== null) {
+      if ("stdout" in error && Buffer.isBuffer(error.stdout)) {
+        errorDetails["stdout"] = error.stdout.toString().trim();
+      }
+      if ("stderr" in error && Buffer.isBuffer(error.stderr)) {
+        errorDetails["stderr"] = error.stderr.toString().trim();
+      }
+    }
+    log("error", "Dependency installation failed", errorDetails);
+    throw error;
+  }
 }
 function ensureDependencies() {
   const nodeModulesPath = join(pluginRoot, "node_modules");

package/dist/mcp/bootstrap.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/mcp/bootstrap.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * MCP Server Bootstrap - installs dependencies before starting server.\n *\n * Uses only Node.js built-ins (no external dependencies required).\n * Self-locates plugin root via import.meta.url (doesn't rely on CLAUDE_PLUGIN_ROOT).\n *\n * Dependency installation strategy:\n * 1. Fast path: node_modules already exists → skip\n * 2. Package manager: Run bun install or npm ci\n *\n * IMPORTANT: MCP servers must NOT log to stderr - Claude Code treats stderr output\n * as an error and may mark the MCP server as failed. All logging goes to file.\n */\nimport { execSync } from 'node:child_process';\nimport {\n  appendFileSync,\n  existsSync,\n  mkdirSync,\n  readFileSync,\n  rmSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// Logging helper - writes to file since MCP servers must NOT use stderr\n// (Claude Code treats stderr as error and may fail the server)\n// JSON format matches pino output for consistency\nconst logDir = join(homedir(), '.bluera', 'bluera-knowledge', 'logs');\nconst logFile = join(logDir, 'app.log');\n\nconst log = (\n  level: 'info' | 'error' | 'debug',\n  msg: string,\n  data?: Record<string, unknown>\n): void => {\n  try {\n    mkdirSync(logDir, { recursive: true });\n    const entry = {\n      time: new Date().toISOString(),\n      level,\n      module: 'bootstrap',\n      msg,\n      ...data,\n    };\n    appendFileSync(logFile, `${JSON.stringify(entry)}\\n`);\n  } catch {\n    // Silently fail - we cannot use stderr for MCP servers\n  }\n};\n\n// Self-locate plugin root from this file's path\n// dist/mcp/bootstrap.js -> plugin root (two directories up)\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst pluginRoot = join(__dirname, '..', '..');\n\n// Lock file to detect interrupted installs\nconst installLockFile = join(pluginRoot, '.node_modules_installing');\n\n// Get version from package.json for logging\nconst getVersion = (): string => {\n  try {\n    const pkg: unknown = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf-8'));\n    if (\n      typeof pkg === 'object' &&\n      pkg !== null &&\n      'version' in pkg &&\n      typeof pkg.version === 'string'\n    ) {\n      return `v${pkg.version}`;\n    }\n    return 'unknown';\n  } catch {\n    return 'unknown';\n  }\n};\n\n/**\n * Install dependencies using bun or npm.\n */\nfunction installWithPackageManager(): void {\n  const hasBun = ((): boolean => {\n    try {\n      execSync('which bun', { stdio: 'ignore' });\n      return true;\n    } catch {\n      return false;\n    }\n  })();\n\n  const cmd = hasBun ? 'bun install --frozen-lockfile' : 'npm ci --silent';\n  log('info', 'Installing dependencies with package manager', { hasBun, cmd });\n  execSync(cmd, { cwd: pluginRoot, stdio: 'inherit' });\n  log('info', 'Dependencies installed via package manager');\n}\n\n/**\n * Ensure dependencies are available.\n * Uses a lock file to detect and recover from interrupted installs.\n */\nfunction ensureDependencies(): void {\n  const nodeModulesPath = join(pluginRoot, 'node_modules');\n\n  // Check for interrupted install - lock file exists means previous install was killed\n  if (existsSync(installLockFile)) {\n    log('info', 'Detected interrupted install, cleaning up');\n    rmSync(nodeModulesPath, { recursive: true, force: true });\n    unlinkSync(installLockFile);\n  }\n\n  // Fast path: already installed\n  if (existsSync(nodeModulesPath)) {\n    log('info', 'Dependencies already installed');\n    return;\n  }\n\n  // Create lock file before install (left behind if install interrupted/fails)\n  writeFileSync(installLockFile, new Date().toISOString());\n\n  installWithPackageManager();\n\n  // Remove lock file on success\n  unlinkSync(installLockFile);\n}\n\n// Main entry point\nconst VERSION = getVersion();\nlog('info', 'Bootstrap starting', { pluginRoot, version: VERSION });\n\nensureDependencies();\n\n// Now that dependencies are installed, import and run the server\n// Dynamic import required because @modelcontextprotocol/sdk wouldn't be available before install\nlog('info', 'Loading server module');\nconst { runMCPServer } = await import('./server.js');\n\nconst projectRoot = process.env['PROJECT_ROOT'];\nif (projectRoot === undefined) {\n  throw new Error('PROJECT_ROOT environment variable is required');\n}\n\nlog('info', 'Starting MCP server', {\n  projectRoot,\n  dataDir: process.env['DATA_DIR'],\n});\n\nawait runMCPServer({\n  dataDir: process.env['DATA_DIR'],\n  config: process.env['CONFIG_PATH'],\n  projectRoot,\n});\n"],"mappings":";;;AAcA,SAAS,gBAAgB;AACzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe;AACxB,SAAS,SAAS,YAAY;AAC9B,SAAS,qBAAqB;AAK9B,IAAM,SAAS,KAAK,QAAQ,GAAG,WAAW,oBAAoB,MAAM;AACpE,IAAM,UAAU,KAAK,QAAQ,SAAS;AAEtC,IAAM,MAAM,CACV,OACA,KACA,SACS;AACT,MAAI;AACF,cAAU,QAAQ,EAAE,WAAW,KAAK,CAAC;AACrC,UAAM,QAAQ;AAAA,MACZ,OAAM,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA,GAAG;AAAA,IACL;AACA,mBAAe,SAAS,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,CAAI;AAAA,EACtD,QAAQ;AAAA,EAER;AACF;AAIA,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,QAAQ,UAAU;AACpC,IAAM,aAAa,KAAK,WAAW,MAAM,IAAI;AAG7C,IAAM,kBAAkB,KAAK,YAAY,0BAA0B;AAGnE,IAAM,aAAa,MAAc;AAC/B,MAAI;AACF,UAAM,MAAe,KAAK,MAAM,aAAa,KAAK,YAAY,cAAc,GAAG,OAAO,CAAC;AACvF,QACE,OAAO,QAAQ,YACf,QAAQ,QACR,aAAa,OACb,OAAO,IAAI,YAAY,UACvB;AACA,aAAO,IAAI,IAAI,OAAO;AAAA,IACxB;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAKA,SAAS,4BAAkC;AACzC,QAAM,UAAU,MAAe;AAC7B,QAAI;AACF,eAAS,aAAa,EAAE,OAAO,SAAS,CAAC;AACzC,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,QAAM,MAAM,SAAS,kCAAkC;AACvD,MAAI,QAAQ,gDAAgD,EAAE,QAAQ,IAAI,CAAC;AAC3E,WAAS,KAAK,EAAE,KAAK,YAAY,OAAO,UAAU,CAAC;AACnD,MAAI,QAAQ,4CAA4C;AAC1D;AAMA,SAAS,qBAA2B;AAClC,QAAM,kBAAkB,KAAK,YAAY,cAAc;AAGvD,MAAI,WAAW,eAAe,GAAG;AAC/B,QAAI,QAAQ,2CAA2C;AACvD,WAAO,iBAAiB,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACxD,eAAW,eAAe;AAAA,EAC5B;AAGA,MAAI,WAAW,eAAe,GAAG;AAC/B,QAAI,QAAQ,gCAAgC;AAC5C;AAAA,EACF;AAGA,gBAAc,kBAAiB,oBAAI,KAAK,GAAE,YAAY,CAAC;AAEvD,4BAA0B;AAG1B,aAAW,eAAe;AAC5B;AAGA,IAAM,UAAU,WAAW;AAC3B,IAAI,QAAQ,sBAAsB,EAAE,YAAY,SAAS,QAAQ,CAAC;AAElE,mBAAmB;AAInB,IAAI,QAAQ,uBAAuB;AACnC,IAAM,EAAE,aAAa,IAAI,MAAM,OAAO,aAAa;AAEnD,IAAM,cAAc,QAAQ,IAAI,cAAc;AAC9C,IAAI,gBAAgB,QAAW;AAC7B,QAAM,IAAI,MAAM,+CAA+C;AACjE;AAEA,IAAI,QAAQ,uBAAuB;AAAA,EACjC;AAAA,EACA,SAAS,QAAQ,IAAI,UAAU;AACjC,CAAC;AAED,MAAM,aAAa;AAAA,EACjB,SAAS,QAAQ,IAAI,UAAU;AAAA,EAC/B,QAAQ,QAAQ,IAAI,aAAa;AAAA,EACjC;AACF,CAAC;","names":[]}
+{"version":3,"sources":["../../src/mcp/bootstrap.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * MCP Server Bootstrap - installs dependencies before starting server.\n *\n * Uses only Node.js built-ins (no external dependencies required).\n * Self-locates plugin root via import.meta.url (doesn't rely on CLAUDE_PLUGIN_ROOT).\n *\n * Dependency installation strategy:\n * 1. Fast path: node_modules already exists → skip\n * 2. Package manager: Run bun install or npm ci\n *\n * IMPORTANT: MCP servers must NOT log to stderr - Claude Code treats stderr output\n * as an error and may mark the MCP server as failed. All logging goes to file.\n */\nimport { execSync } from 'node:child_process';\nimport {\n  appendFileSync,\n  existsSync,\n  mkdirSync,\n  readFileSync,\n  rmSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { homedir } from 'node:os';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// Logging helper - writes to file since MCP servers must NOT use stderr\n// (Claude Code treats stderr as error and may fail the server)\n// JSON format matches pino output for consistency\n// Use PROJECT_ROOT if available (set by Claude Code), else fall back to home dir\nconst envProjectRoot = process.env['PROJECT_ROOT'];\nconst logDir =\n  envProjectRoot !== undefined && envProjectRoot !== ''\n    ? join(envProjectRoot, '.bluera', 'bluera-knowledge', 'logs')\n    : join(homedir(), '.bluera', 'bluera-knowledge', 'logs');\nconst logFile = join(logDir, 'app.log');\n\nconst log = (\n  level: 'info' | 'error' | 'debug',\n  msg: string,\n  data?: Record<string, unknown>\n): void => {\n  try {\n    mkdirSync(logDir, { recursive: true });\n    const entry = {\n      time: new Date().toISOString(),\n      level,\n      module: 'bootstrap',\n      msg,\n      ...data,\n    };\n    appendFileSync(logFile, `${JSON.stringify(entry)}\\n`);\n  } catch {\n    // Silently fail - we cannot use stderr for MCP servers\n  }\n};\n\n// Self-locate plugin root from this file's path\n// dist/mcp/bootstrap.js -> plugin root (two directories up)\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst pluginRoot = join(__dirname, '..', '..');\n\n// Lock file to detect interrupted installs\nconst installLockFile = join(pluginRoot, '.node_modules_installing');\n\n// Get version from package.json for logging\nconst getVersion = (): string => {\n  try {\n    const pkg: unknown = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf-8'));\n    if (\n      typeof pkg === 'object' &&\n      pkg !== null &&\n      'version' in pkg &&\n      typeof pkg.version === 'string'\n    ) {\n      return `v${pkg.version}`;\n    }\n    return 'unknown';\n  } catch {\n    return 'unknown';\n  }\n};\n\n/**\n * Install dependencies using bun or npm.\n * Uses stdio: 'pipe' to capture output and avoid corrupting MCP stdio transport.\n */\nfunction installWithPackageManager(): void {\n  const hasBun = ((): boolean => {\n    try {\n      execSync('which bun', { stdio: 'ignore' });\n      return true;\n    } catch {\n      return false;\n    }\n  })();\n\n  const cmd = hasBun ? 'bun install --frozen-lockfile' : 'npm ci --silent';\n  log('info', 'Installing dependencies with package manager', { hasBun, cmd });\n\n  try {\n    // Use stdio: 'pipe' to capture output - 'inherit' would corrupt MCP stdio transport\n    const output = execSync(cmd, { cwd: pluginRoot, stdio: 'pipe' });\n    if (output.length > 0) {\n      log('debug', 'Install output', { output: output.toString().trim() });\n    }\n    log('info', 'Dependencies installed via package manager');\n  } catch (error) {\n    // Log installation failure details before re-throwing\n    // execSync throws an object with stdout/stderr buffers on failure\n    const errorMessage = error instanceof Error ? error.message : String(error);\n    const errorDetails: Record<string, unknown> = { message: errorMessage };\n\n    if (typeof error === 'object' && error !== null) {\n      if ('stdout' in error && Buffer.isBuffer(error.stdout)) {\n        errorDetails['stdout'] = error.stdout.toString().trim();\n      }\n      if ('stderr' in error && Buffer.isBuffer(error.stderr)) {\n        errorDetails['stderr'] = error.stderr.toString().trim();\n      }\n    }\n\n    log('error', 'Dependency installation failed', errorDetails);\n    throw error;\n  }\n}\n\n/**\n * Ensure dependencies are available.\n * Uses a lock file to detect and recover from interrupted installs.\n */\nfunction ensureDependencies(): void {\n  const nodeModulesPath = join(pluginRoot, 'node_modules');\n\n  // Check for interrupted install - lock file exists means previous install was killed\n  if (existsSync(installLockFile)) {\n    log('info', 'Detected interrupted install, cleaning up');\n    rmSync(nodeModulesPath, { recursive: true, force: true });\n    unlinkSync(installLockFile);\n  }\n\n  // Fast path: already installed\n  if (existsSync(nodeModulesPath)) {\n    log('info', 'Dependencies already installed');\n    return;\n  }\n\n  // Create lock file before install (left behind if install interrupted/fails)\n  writeFileSync(installLockFile, new Date().toISOString());\n\n  installWithPackageManager();\n\n  // Remove lock file on success\n  unlinkSync(installLockFile);\n}\n\n// Main entry point\nconst VERSION = getVersion();\nlog('info', 'Bootstrap starting', { pluginRoot, version: VERSION });\n\nensureDependencies();\n\n// Now that dependencies are installed, import and run the server\n// Dynamic import required because @modelcontextprotocol/sdk wouldn't be available before install\nlog('info', 'Loading server module');\nconst { runMCPServer } = await import('./server.js');\n\nconst projectRoot = process.env['PROJECT_ROOT'];\nif (projectRoot === undefined) {\n  throw new Error('PROJECT_ROOT environment variable is required');\n}\n\nlog('info', 'Starting MCP server', {\n  projectRoot,\n  dataDir: process.env['DATA_DIR'],\n});\n\nawait runMCPServer({\n  dataDir: process.env['DATA_DIR'],\n  config: process.env['CONFIG_PATH'],\n  projectRoot,\n});\n"],"mappings":"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","names":[]}

package/dist/mcp/server.d.ts

@@ -156,6 +156,22 @@ type DocumentId = string & {
     readonly [DocumentIdBrand]: typeof DocumentIdBrand;
 };
 
+/**
+ * Events emitted when cached data becomes stale.
+ * Used to notify dependent services (e.g., SearchService) when
+ * source data (e.g., code graphs) has been updated or deleted.
+ */
+interface CacheInvalidationEvent {
+    /** Type of invalidation */
+    type: 'graph-updated' | 'graph-deleted';
+    /** The store whose data changed */
+    storeId: StoreId;
+}
+/**
+ * Listener function for cache invalidation events.
+ */
+type CacheInvalidationListener = (event: CacheInvalidationEvent) => void;
+
 /**
  * Service for building, persisting, and querying code graphs.
  * Code graphs track relationships between code elements (functions, classes, etc.)
@@ -166,7 +182,17 @@ declare class CodeGraphService {
     private readonly parser;
     private readonly parserFactory;
     private readonly graphCache;
+    private readonly cacheListeners;
     constructor(dataDir: string, pythonBridge?: PythonBridge);
+    /**
+     * Subscribe to cache invalidation events.
+     * Returns an unsubscribe function.
+     */
+    onCacheInvalidation(listener: CacheInvalidationListener): () => void;
+    /**
+     * Emit a cache invalidation event to all listeners.
+     */
+    private emitCacheInvalidation;
     /**
      * Build a code graph from source files.
      */
@@ -232,7 +258,6 @@ declare class CodeGraphService {
 interface EmbeddingConfig {
     readonly model: string;
     readonly batchSize: number;
-    readonly dimensions: number;
 }
 interface IndexingConfig {
     readonly concurrency: number;
@@ -243,12 +268,6 @@ interface IndexingConfig {
 interface SearchConfig {
     readonly defaultMode: 'vector' | 'fts' | 'hybrid';
     readonly defaultLimit: number;
-    readonly minScore: number;
-    readonly rrf: {
-        readonly k: number;
-        readonly vectorWeight: number;
-        readonly ftsWeight: number;
-    };
 }
 interface CrawlConfig {
     readonly userAgent: string;
@@ -272,8 +291,13 @@ interface AppConfig {
 declare class ConfigService {
     private readonly configPath;
     private readonly dataDir;
+    private readonly projectRoot;
     private config;
     constructor(configPath?: string, dataDir?: string, projectRoot?: string);
+    /**
+     * Get the resolved project root directory.
+     */
+    resolveProjectRoot(): string;
     load(): Promise<AppConfig>;
     save(config: AppConfig): Promise<void>;
     resolveDataDir(): string;
@@ -281,15 +305,87 @@ declare class ConfigService {
     private expandPath;
 }
 
+/**
+ * Type-safe manifest with branded StoreId.
+ * Use this in service code for proper type safety.
+ */
+interface TypedStoreManifest {
+    version: 1;
+    storeId: StoreId;
+    indexedAt: string;
+    files: Record<string, TypedFileState>;
+}
+/**
+ * Type-safe file state with branded DocumentIds.
+ */
+interface TypedFileState {
+    mtime: number;
+    size: number;
+    hash: string;
+    documentIds: DocumentId[];
+}
+
+/**
+ * Service for managing store manifests.
+ *
+ * Manifests track the state of indexed files to enable incremental re-indexing.
+ * They are stored in the data directory under manifests/{storeId}.manifest.json.
+ */
+declare class ManifestService {
+    private readonly manifestsDir;
+    constructor(dataDir: string);
+    /**
+     * Initialize the manifests directory.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the file path for a store's manifest.
+     */
+    getManifestPath(storeId: StoreId): string;
+    /**
+     * Load a store's manifest.
+     * Returns an empty manifest if one doesn't exist.
+     * Throws on parse/validation errors (fail fast).
+     */
+    load(storeId: StoreId): Promise<TypedStoreManifest>;
+    /**
+     * Save a store's manifest atomically.
+     */
+    save(manifest: TypedStoreManifest): Promise<void>;
+    /**
+     * Delete a store's manifest.
+     * Called when a store is deleted or during full re-index.
+     */
+    delete(storeId: StoreId): Promise<void>;
+    /**
+     * Check if a file exists.
+     */
+    private fileExists;
+    /**
+     * Convert a parsed manifest to a typed manifest with branded types.
+     */
+    private toTypedManifest;
+}
+
 declare class EmbeddingEngine {
     private extractor;
+    private _dimensions;
     private readonly modelName;
-    private readonly dimensions;
-    constructor(modelName?: string, dimensions?: number);
+    private readonly batchSize;
+    constructor(modelName?: string, batchSize?: number);
     initialize(): Promise<void>;
     embed(text: string): Promise<number[]>;
     embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Get cached embedding dimensions. Throws if embed() hasn't been called yet.
+     * Use ensureDimensions() if you need to guarantee dimensions are available.
+     */
     getDimensions(): number;
+    /**
+     * Ensure dimensions are available, initializing the model if needed.
+     * Returns the embedding dimensions for the current model.
+     */
+    ensureDimensions(): Promise<number>;
     /**
      * Dispose the embedding pipeline to free resources.
      * Should be called before process exit to prevent ONNX runtime cleanup issues on macOS.
@@ -308,7 +404,7 @@ interface DocumentMetadata {
     readonly url?: string | undefined;
     readonly type: DocumentType;
     readonly storeId: StoreId;
-    readonly indexedAt: Date;
+    readonly indexedAt: string;
     readonly fileHash?: string | undefined;
     readonly chunkIndex?: number | undefined;
     readonly totalChunks?: number | undefined;
@@ -325,10 +421,18 @@ declare class LanceStore {
     private connection;
     private readonly tables;
     private readonly dataDir;
+    private _dimensions;
     constructor(dataDir: string);
+    /**
+     * Set the embedding dimensions. Must be called before initialize().
+     * This allows dimensions to be derived from the embedding model at runtime.
+     * Idempotent: subsequent calls are ignored if dimensions are already set.
+     */
+    setDimensions(dimensions: number): void;
     initialize(storeId: StoreId): Promise<void>;
     addDocuments(storeId: StoreId, documents: Document[]): Promise<void>;
     deleteDocuments(storeId: StoreId, documentIds: DocumentId[]): Promise<void>;
+    clearAllDocuments(storeId: StoreId): Promise<void>;
     search(storeId: StoreId, vector: number[], limit: number, _threshold?: number): Promise<Array<{
         id: DocumentId;
         content: string;
@@ -391,17 +495,20 @@ interface RepoStore extends BaseStore {
     readonly path: string;
     readonly url?: string | undefined;
     readonly branch?: string | undefined;
+    readonly depth?: number | undefined;
 }
 interface WebStore extends BaseStore {
     readonly type: 'web';
     readonly url: string;
     readonly depth: number;
     readonly maxPages?: number | undefined;
+    readonly crawlInstructions?: string | undefined;
+    readonly extractInstructions?: string | undefined;
 }
 type Store = FileStore | RepoStore | WebStore;
 
 interface IndexResult {
-    documentsIndexed: number;
+    filesIndexed: number;
     chunksCreated: number;
     timeMs: number;
 }
@@ -410,15 +517,36 @@ interface IndexOptions {
     chunkOverlap?: number;
     codeGraphService?: CodeGraphService;
     concurrency?: number;
+    manifestService?: ManifestService;
+    ignorePatterns?: readonly string[];
+}
+interface IncrementalIndexResult extends IndexResult {
+    filesAdded: number;
+    filesModified: number;
+    filesDeleted: number;
+    filesUnchanged: number;
 }
 declare class IndexService {
     private readonly lanceStore;
     private readonly embeddingEngine;
     private readonly chunker;
     private readonly codeGraphService;
+    private readonly manifestService;
+    private readonly driftService;
     private readonly concurrency;
+    private readonly ignoreDirs;
+    private readonly ignoreFilePatterns;
     constructor(lanceStore: LanceStore, embeddingEngine: EmbeddingEngine, options?: IndexOptions);
     indexStore(store: Store, onProgress?: ProgressCallback): Promise<Result<IndexResult>>;
+    /**
+     * Incrementally index a store, only processing changed files.
+     * Requires manifestService to be configured.
+     *
+     * @param store - The store to index
+     * @param onProgress - Optional progress callback
+     * @returns Result with incremental index statistics
+     */
+    indexStoreIncremental(store: Store, onProgress?: ProgressCallback): Promise<Result<IncrementalIndexResult>>;
     private indexFileStore;
     /**
      * Process a single file: read, chunk, embed, and return documents.
@@ -440,6 +568,11 @@ declare class IndexService {
 }
 
 type SearchMode = 'vector' | 'fts' | 'hybrid';
+/**
+ * Search intent hints for context-aware ranking.
+ * These align with the MCP API contract.
+ */
+type SearchIntent = 'find-pattern' | 'find-implementation' | 'find-usage' | 'find-definition' | 'find-documentation';
 interface CodeUnit {
     type: 'function' | 'class' | 'interface' | 'type' | 'const' | 'documentation' | 'example';
     name: string;
@@ -484,9 +617,7 @@ interface SearchQuery {
     readonly limit?: number | undefined;
     readonly threshold?: number | undefined;
     readonly minRelevance?: number | undefined;
-    readonly filter?: Record<string, unknown> | undefined;
-    readonly includeContent?: boolean | undefined;
-    readonly contextLines?: number | undefined;
+    readonly intent?: SearchIntent | undefined;
     readonly detail?: DetailLevel | undefined;
 }
 interface SearchResult {
@@ -529,7 +660,14 @@ declare class SearchService {
     private readonly codeUnitService;
     private readonly codeGraphService;
     private readonly graphCache;
-    constructor(lanceStore: LanceStore, embeddingEngine: EmbeddingEngine, codeGraphService?: CodeGraphService);
+    private readonly searchConfig;
+    private readonly unsubscribeCacheInvalidation;
+    constructor(lanceStore: LanceStore, embeddingEngine: EmbeddingEngine, codeGraphService?: CodeGraphService, searchConfig?: SearchConfig);
+    /**
+     * Clean up resources (unsubscribe from events).
+     * Call this when destroying the service.
+     */
+    cleanup(): void;
     /**
      * Load code graph for a store, with caching.
      * Returns null if no graph is available.
@@ -565,7 +703,6 @@ declare class SearchService {
      * Returns results with raw cosine similarity scores [0-1].
      */
     private vectorSearchRaw;
-    private vectorSearch;
     private ftsSearch;
     /**
      * Internal hybrid search result with additional metadata for confidence calculation.
@@ -671,7 +808,7 @@ declare const StoreDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     type: z.ZodLiteral<"repo">;
-    url: z.ZodURL;
+    url: z.ZodString;
     branch: z.ZodOptional<z.ZodString>;
     depth: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
@@ -703,7 +840,7 @@ declare const StoreDefinitionsConfigSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
         type: z.ZodLiteral<"repo">;
-        url: z.ZodURL;
+        url: z.ZodString;
         branch: z.ZodOptional<z.ZodString>;
         depth: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
@@ -800,12 +937,17 @@ interface CreateStoreInput {
     tags?: string[] | undefined;
     branch?: string | undefined;
     depth?: number | undefined;
+    maxPages?: number | undefined;
+    crawlInstructions?: string | undefined;
+    extractInstructions?: string | undefined;
 }
 interface StoreServiceOptions {
     /** Optional definition service for auto-updating git-committable config */
     definitionService?: StoreDefinitionService;
     /** Optional gitignore service for ensuring .gitignore patterns */
     gitignoreService?: GitignoreService;
+    /** Optional project root for resolving relative paths */
+    projectRoot?: string;
 }
 interface OperationOptions {
     /** Skip syncing to store definitions (used by stores:sync command) */
@@ -815,13 +957,21 @@ declare class StoreService {
     private readonly dataDir;
     private readonly definitionService;
     private readonly gitignoreService;
+    private readonly projectRoot;
     private registry;
     constructor(dataDir: string, options?: StoreServiceOptions);
     initialize(): Promise<void>;
     /**
      * Convert a Store and CreateStoreInput to a StoreDefinition for persistence.
+     * Returns undefined for stores that shouldn't be persisted (e.g., local repo stores).
      */
     private createDefinitionFromStore;
+    /**
+     * Create a StoreDefinition from an existing store (without original input).
+     * Used when updating/renaming stores where we don't have the original input.
+     * Returns undefined for stores that shouldn't be persisted (e.g., local repo stores).
+     */
+    private createDefinitionFromExistingStore;
     create(input: CreateStoreInput, options?: OperationOptions): Promise<Result<Store>>;
     list(type?: StoreType): Promise<Store[]>;
     get(id: StoreId): Promise<Store | undefined>;
@@ -842,6 +992,7 @@ interface ServiceContainer {
     embeddings: EmbeddingEngine;
     codeGraph: CodeGraphService;
     pythonBridge: PythonBridge;
+    manifest: ManifestService;
 }
 
 /**

package/dist/mcp/server.js

@@ -1,9 +1,10 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-ZGEQCLOZ.js";
-import "../chunk-VKTVMW45.js";
-import "../chunk-HRQD3MPH.js";
+} from "../chunk-EZXJ3W5X.js";
+import "../chunk-RDDGZIDL.js";
+import "../chunk-CLIMKLTW.js";
+import "../chunk-HXBIIMYL.js";
 export {
   createMCPServer,
   runMCPServer

package/dist/watch.service-VDSUQ72Z.js

@@ -0,0 +1,7 @@
+import {
+  WatchService
+} from "./chunk-HXBIIMYL.js";
+export {
+  WatchService
+};
+//# sourceMappingURL=watch.service-VDSUQ72Z.js.map

package/dist/watch.service-VDSUQ72Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/workers/background-worker-cli.js

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-RAXRD23K.js";
+} from "../chunk-VUGQ7HAR.js";
 import {
   JobService,
-  createDocumentId,
   createLogger,
   createServices,
-  createStoreId,
   destroyServices,
   shutdownLogger
-} from "../chunk-VKTVMW45.js";
-import "../chunk-HRQD3MPH.js";
+} from "../chunk-RDDGZIDL.js";
+import {
+  createDocumentId,
+  createStoreId
+} from "../chunk-CLIMKLTW.js";
+import "../chunk-HXBIIMYL.js";
 
 // src/workers/background-worker-cli.ts
 import { platform } from "os";
@@ -24,12 +26,13 @@ function calculateIndexProgress(current, total, scale = 100) {
   return current / total * scale;
 }
 var BackgroundWorker = class {
-  constructor(jobService, storeService, indexService, lanceStore, embeddingEngine) {
+  constructor(jobService, storeService, indexService, lanceStore, embeddingEngine, crawlConfig) {
     this.jobService = jobService;
     this.storeService = storeService;
     this.indexService = indexService;
     this.lanceStore = lanceStore;
     this.embeddingEngine = embeddingEngine;
+    this.crawlConfig = crawlConfig;
   }
   /**
    * Execute a job based on its type
@@ -104,6 +107,8 @@ var BackgroundWorker = class {
       message: "Repository cloned, starting indexing...",
       progress: 30
     });
+    this.lanceStore.setDimensions(await this.embeddingEngine.ensureDimensions());
+    await this.lanceStore.initialize(store.id);
     const result = await this.indexService.indexStore(
       store,
       (event) => {
@@ -140,6 +145,8 @@ var BackgroundWorker = class {
     if (!store) {
       throw new Error(`Store ${storeId} not found`);
     }
+    this.lanceStore.setDimensions(await this.embeddingEngine.ensureDimensions());
+    await this.lanceStore.initialize(store.id);
     const result = await this.indexService.indexStore(
       store,
       (event) => {
@@ -179,7 +186,7 @@ var BackgroundWorker = class {
       throw new Error(`Web store ${storeId} not found`);
     }
     const resolvedMaxPages = typeof maxPages === "number" ? maxPages : 50;
-    const crawler = new IntelligentCrawler();
+    const crawler = new IntelligentCrawler(this.crawlConfig);
     crawler.on("progress", (progress) => {
       const currentJob = this.jobService.getJob(job.id);
       if (currentJob?.status === "cancelled") {
@@ -193,6 +200,7 @@ var BackgroundWorker = class {
       });
     });
     try {
+      this.lanceStore.setDimensions(await this.embeddingEngine.ensureDimensions());
       await this.lanceStore.initialize(store.id);
       const docs = [];
       const crawlOptions = {
@@ -225,7 +233,7 @@ var BackgroundWorker = class {
             title: result.title,
             extracted: result.extracted !== void 0,
             depth: result.depth,
-            indexedAt: /* @__PURE__ */ new Date()
+            indexedAt: (/* @__PURE__ */ new Date()).toISOString()
           }
         });
       }
@@ -234,6 +242,7 @@ var BackgroundWorker = class {
           message: "Indexing crawled documents...",
           progress: 85
         });
+        await this.lanceStore.clearAllDocuments(store.id);
         await this.lanceStore.addDocuments(store.id, docs);
         await this.lanceStore.createFtsIndex(store.id);
       }
@@ -330,12 +339,14 @@ async function main() {
     }
     void shutdownLogger().finally(() => process.exit(0));
   });
+  const appConfig = await services.config.load();
   const worker = new BackgroundWorker(
     jobService,
     services.store,
     services.index,
     services.lance,
-    services.embeddings
+    services.embeddings,
+    appConfig.crawl
   );
   try {
     await worker.executeJob(jobId);