@geminilight/mindos 0.5.20 → 0.5.22

package/app/lib/core/csv.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolveSafe } from './security';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Appends a single row to a CSV file with RFC 4180 escaping.
@@ -9,7 +10,7 @@ import { resolveSafe } from './security';
  */
 export function appendCsvRow(mindRoot: string, filePath: string, row: string[]): { newRowCount: number } {
   const resolved = resolveSafe(mindRoot, filePath);
-  if (!filePath.endsWith('.csv')) throw new Error('Only .csv files support row append');
+  if (!filePath.endsWith('.csv')) throw new MindOSError(ErrorCodes.INVALID_FILE_TYPE, 'Only .csv files support row append', { filePath });
 
   const escaped = row.map((cell) => {
     if (cell.includes(',') || cell.includes('"') || cell.includes('\n')) {

package/app/lib/core/fs-ops.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolveSafe, assertWithinRoot } from './security';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Reads the content of a file given a relative path from mindRoot.
@@ -35,7 +36,7 @@ export function writeFile(mindRoot: string, filePath: string, content: string):
 export function createFile(mindRoot: string, filePath: string, initialContent = ''): void {
   const resolved = resolveSafe(mindRoot, filePath);
   if (fs.existsSync(resolved)) {
-    throw new Error(`File already exists: ${filePath}`);
+    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `File already exists: ${filePath}`, { filePath });
   }
   fs.mkdirSync(path.dirname(resolved), { recursive: true });
   fs.writeFileSync(resolved, initialContent, 'utf-8');
@@ -47,7 +48,7 @@ export function createFile(mindRoot: string, filePath: string, initialContent =
 export function deleteFile(mindRoot: string, filePath: string): void {
   const resolved = resolveSafe(mindRoot, filePath);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`File not found: ${filePath}`);
+    throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `File not found: ${filePath}`, { filePath });
   }
   fs.unlinkSync(resolved);
 }
@@ -59,7 +60,7 @@ export function deleteFile(mindRoot: string, filePath: string): void {
  */
 export function renameFile(mindRoot: string, oldPath: string, newName: string): string {
   if (newName.includes('/') || newName.includes('\\')) {
-    throw new Error('Invalid filename: must not contain path separators');
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Invalid filename: must not contain path separators', { newName });
   }
   const root = path.resolve(mindRoot);
   const oldResolved = path.resolve(path.join(root, oldPath));
@@ -70,7 +71,7 @@ export function renameFile(mindRoot: string, oldPath: string, newName: string):
   assertWithinRoot(newResolved, root);
 
   if (fs.existsSync(newResolved)) {
-    throw new Error('A file with that name already exists');
+    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, 'A file with that name already exists', { newName });
   }
   fs.renameSync(oldResolved, newResolved);
   return path.relative(root, newResolved);
@@ -88,8 +89,8 @@ export function moveFile(
 ): { newPath: string; affectedFiles: string[] } {
   const fromResolved = resolveSafe(mindRoot, fromPath);
   const toResolved = resolveSafe(mindRoot, toPath);
-  if (!fs.existsSync(fromResolved)) throw new Error(`Source not found: ${fromPath}`);
-  if (fs.existsSync(toResolved)) throw new Error(`Destination already exists: ${toPath}`);
+  if (!fs.existsSync(fromResolved)) throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `Source not found: ${fromPath}`, { fromPath });
+  if (fs.existsSync(toResolved)) throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `Destination already exists: ${toPath}`, { toPath });
   fs.mkdirSync(path.dirname(toResolved), { recursive: true });
   fs.renameSync(fromResolved, toResolved);
   const backlinks = findBacklinksFn(mindRoot, fromPath);

package/app/lib/core/index.ts

@@ -36,7 +36,7 @@ export {
 export type { TreeOptions } from './tree';
 
 // Search
-export { searchFiles } from './search';
+export { searchFiles, invalidateSearchIndex } from './search';
 
 // Line-level operations
 export {

package/app/lib/core/lines.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile } from './fs-ops';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Reads a file and returns its content split into lines.
@@ -11,9 +12,9 @@ export function readLines(mindRoot: string, filePath: string): string[] {
  * Validates line indices are within bounds.
  */
 function validateLineRange(totalLines: number, start: number, end: number): void {
-  if (start < 0 || end < 0) throw new Error('Invalid line index: indices must be >= 0');
-  if (start > end) throw new Error(`Invalid range: start (${start}) > end (${end})`);
-  if (start >= totalLines) throw new Error(`Invalid line index: start (${start}) >= total lines (${totalLines})`);
+  if (start < 0 || end < 0) throw new MindOSError(ErrorCodes.INVALID_RANGE, 'Invalid line index: indices must be >= 0', { start, end });
+  if (start > end) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid range: start (${start}) > end (${end})`, { start, end });
+  if (start >= totalLines) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid line index: start (${start}) >= total lines (${totalLines})`, { start, totalLines });
 }
 
 /**
@@ -23,7 +24,7 @@ function validateLineRange(totalLines: number, start: number, end: number): void
 export function insertLines(mindRoot: string, filePath: string, afterIndex: number, lines: string[]): void {
   const existing = readLines(mindRoot, filePath);
   if (afterIndex >= existing.length) {
-    throw new Error(`Invalid after_index: ${afterIndex} >= total lines (${existing.length})`);
+    throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid after_index: ${afterIndex} >= total lines (${existing.length})`, { afterIndex, totalLines: existing.length });
   }
   const insertAt = afterIndex < 0 ? 0 : afterIndex + 1;
   existing.splice(insertAt, 0, ...lines);
@@ -58,7 +59,7 @@ export function insertAfterHeading(mindRoot: string, filePath: string, heading:
     const trimmed = l.trim();
     return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
   });
-  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+  if (idx === -1) throw new MindOSError(ErrorCodes.HEADING_NOT_FOUND, `Heading not found: "${heading}"`, { heading });
   let insertAt = idx + 1;
   while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
   insertLines(mindRoot, filePath, insertAt - 1, ['', content]);
@@ -73,7 +74,7 @@ export function updateSection(mindRoot: string, filePath: string, heading: strin
     const trimmed = l.trim();
     return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
   });
-  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+  if (idx === -1) throw new MindOSError(ErrorCodes.HEADING_NOT_FOUND, `Heading not found: "${heading}"`, { heading });
 
   const headingLevel = (lines[idx].match(/^#+/) ?? [''])[0].length;
   let sectionEnd = lines.length - 1;

package/app/lib/core/search-index.ts

@@ -0,0 +1,174 @@
+import { collectAllFiles } from './tree';
+import { readFile } from './fs-ops';
+
+const MAX_CONTENT_LENGTH = 50_000;
+
+// CJK Unicode ranges: Chinese, Japanese Hiragana/Katakana, Korean
+const CJK_REGEX = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/;
+
+/**
+ * Tokenize text for indexing: split on word boundaries + CJK bigrams.
+ *
+ * Latin/ASCII: split on non-alphanumeric characters, lowercased.
+ * CJK: generate character-level bigrams (overlapping pairs).
+ * Mixed text: both strategies applied, tokens merged.
+ */
+function tokenize(text: string): Set<string> {
+  const tokens = new Set<string>();
+  const lower = text.toLowerCase();
+
+  // Latin/ASCII word tokens.
+  // Single Latin chars (e.g. "a") are noise and excluded; CJK unigrams
+  // carry meaning and are handled separately below.
+  const words = lower.match(/[a-z0-9_$@#]+/g);
+  if (words) {
+    for (const w of words) {
+      if (w.length >= 2) tokens.add(w);
+    }
+  }
+
+  // CJK bigrams + single chars (unigrams carry meaning in CJK scripts)
+  if (CJK_REGEX.test(lower)) {
+    const cjkChars: string[] = [];
+    for (const ch of lower) {
+      if (CJK_REGEX.test(ch)) {
+        cjkChars.push(ch);
+      } else {
+        // Emit bigrams for accumulated CJK run
+        if (cjkChars.length > 0) {
+          emitCjkTokens(cjkChars, tokens);
+          cjkChars.length = 0;
+        }
+      }
+    }
+    if (cjkChars.length > 0) emitCjkTokens(cjkChars, tokens);
+  }
+
+  return tokens;
+}
+
+function emitCjkTokens(chars: string[], tokens: Set<string>): void {
+  for (let i = 0; i < chars.length; i++) {
+    tokens.add(chars[i]); // unigram
+    if (i + 1 < chars.length) {
+      tokens.add(chars[i] + chars[i + 1]); // bigram
+    }
+  }
+}
+
+/**
+ * In-memory inverted index for core search acceleration.
+ *
+ * The index maps tokens → Set<filePath>. When a search query arrives,
+ * we tokenize the query and intersect candidate sets from the index,
+ * dramatically reducing the number of files that need full-text scanning.
+ *
+ * Lifecycle:
+ * - `rebuild(mindRoot)` — full build from disk (called lazily on first search)
+ * - `invalidate()` — mark stale (next search triggers rebuild)
+ * - `getCandidates(query)` — return candidate file set, or null if no index / no tokens
+ */
+export class SearchIndex {
+  private invertedIndex: Map<string, Set<string>> | null = null;
+  private builtForRoot: string | null = null;
+  private fileCount = 0;
+
+  /** Full rebuild: read all files and build inverted index. */
+  rebuild(mindRoot: string): void {
+    const allFiles = collectAllFiles(mindRoot);
+    const inverted = new Map<string, Set<string>>();
+
+    for (const filePath of allFiles) {
+      let content: string;
+      try {
+        content = readFile(mindRoot, filePath);
+      } catch {
+        continue;
+      }
+
+      if (content.length > MAX_CONTENT_LENGTH) {
+        content = content.slice(0, MAX_CONTENT_LENGTH);
+      }
+
+      // Also index the file path itself
+      const allText = filePath + '\n' + content;
+      const tokens = tokenize(allText);
+
+      for (const token of tokens) {
+        let set = inverted.get(token);
+        if (!set) {
+          set = new Set<string>();
+          inverted.set(token, set);
+        }
+        set.add(filePath);
+      }
+    }
+
+    this.invertedIndex = inverted;
+    this.builtForRoot = mindRoot;
+    this.fileCount = allFiles.length;
+  }
+
+  /** Clear the index. Next search will trigger a lazy rebuild. */
+  invalidate(): void {
+    this.invertedIndex = null;
+    this.builtForRoot = null;
+    this.fileCount = 0;
+  }
+
+  /** Whether the index has been built for the given mindRoot. */
+  isBuiltFor(mindRoot: string): boolean {
+    return this.invertedIndex !== null && this.builtForRoot === mindRoot;
+  }
+
+  /** Whether the index has been built (for any root). */
+  isBuilt(): boolean {
+    return this.invertedIndex !== null;
+  }
+
+  /** Number of files in the index. */
+  getFileCount(): number {
+    return this.fileCount;
+  }
+
+  /**
+   * Get candidate file paths for a query (single or multi-word).
+   *
+   * Tokenizes the query and intersects candidate sets from the inverted index.
+   *
+   * Returns:
+   * - `null` if the index is not built, query is empty, or query produces no
+   *   tokens (e.g. substring shorter than 2 chars). Callers should fall back
+   *   to a full scan when null is returned.
+   * - `string[]` (possibly empty) if the index can answer definitively.
+   */
+  getCandidates(query: string): string[] | null {
+    if (!query.trim()) return null;
+    if (!this.invertedIndex) return null;
+
+    const tokens = tokenize(query.toLowerCase().trim());
+    // No tokens produced → query is a substring/single-char that the index
+    // cannot resolve. Return null so the caller falls back to full scan,
+    // preserving pre-index indexOf behavior for partial-word queries.
+    if (tokens.size === 0) return null;
+
+    let result: Set<string> | null = null;
+
+    for (const token of tokens) {
+      const set = this.invertedIndex.get(token);
+      if (!set) return []; // No files have this token → intersection is empty
+
+      if (result === null) {
+        result = new Set(set);
+      } else {
+        // Intersect
+        for (const path of result) {
+          if (!set.has(path)) result.delete(path);
+        }
+        if (result.size === 0) return [];
+      }
+    }
+
+    return result ? Array.from(result) : [];
+  }
+}

package/app/lib/core/search.ts

@@ -1,16 +1,31 @@
 import fs from 'fs';
 import path from 'path';
-import { resolveSafe } from './security';
 import { collectAllFiles } from './tree';
 import { readFile } from './fs-ops';
+import { SearchIndex } from './search-index';
 import type { SearchResult, SearchOptions } from './types';
 
+/**
+ * Module-level search index singleton.
+ * Lazily built on first search, invalidated by `invalidateSearchIndex()`.
+ */
+const searchIndex = new SearchIndex();
+
+/** Invalidate the core search index. Called from `lib/fs.ts` on write operations. */
+export function invalidateSearchIndex(): void {
+  searchIndex.invalidate();
+}
+
 /**
  * Core literal search — used by MCP tools via REST API.
  *
  * This is a **case-insensitive literal string match** with occurrence-density scoring.
  * It supports scope, file_type, and modified_after filters that MCP tools expose.
  *
+ * Performance: uses an in-memory inverted index to narrow the candidate file set
+ * before doing full-text scanning. The index is built lazily on the first query
+ * and invalidated on any write operation.
+ *
  * NOTE: The App also has a separate Fuse.js fuzzy search in `lib/fs.ts` for the
  * browser `⌘K` search overlay. The two coexist intentionally:
  * - Core search (here): exact literal match, supports filters, used by MCP/API
@@ -20,6 +35,15 @@ export function searchFiles(mindRoot: string, query: string, opts: SearchOptions
   if (!query.trim()) return [];
   const { limit = 20, scope, file_type = 'all', modified_after } = opts;
 
+  // Ensure search index is built for this mindRoot
+  if (!searchIndex.isBuiltFor(mindRoot)) {
+    searchIndex.rebuild(mindRoot);
+  }
+
+  // Use index to get candidate files (or null if index unavailable → full scan)
+  const candidates = searchIndex.getCandidates(query);
+  const candidateSet = candidates ? new Set(candidates) : null;
+
   let allFiles = collectAllFiles(mindRoot);
 
   // Filter by scope (directory prefix)
@@ -34,6 +58,11 @@ export function searchFiles(mindRoot: string, query: string, opts: SearchOptions
     allFiles = allFiles.filter(f => f.endsWith(ext));
   }
 
+  // Narrow by index candidates (if available)
+  if (candidateSet) {
+    allFiles = allFiles.filter(f => candidateSet.has(f));
+  }
+
   // Filter by modification time
   let mtimeThreshold = 0;
   if (modified_after) {

package/app/lib/core/security.ts

@@ -1,11 +1,12 @@
 import path from 'path';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Asserts that a resolved path is within the given root.
  */
 export function assertWithinRoot(resolved: string, root: string): void {
   if (!resolved.startsWith(root + path.sep) && resolved !== root) {
-    throw new Error('Access denied: path outside MIND_ROOT');
+    throw new MindOSError(ErrorCodes.PATH_OUTSIDE_ROOT, 'Access denied: path outside MIND_ROOT', { resolved, root });
   }
 }
 
@@ -35,9 +36,11 @@ export function isRootProtected(filePath: string): boolean {
  */
 export function assertNotProtected(filePath: string, operation: string): void {
   if (isRootProtected(filePath)) {
-    throw new Error(
+    throw new MindOSError(
+      ErrorCodes.PROTECTED_FILE,
       `Protected file: root "${filePath}" cannot be ${operation} via MCP. ` +
-      `This is a system kernel file (§7 of INSTRUCTION.md). Edit it manually or use a dedicated confirmation workflow.`
+      `This is a system kernel file (§7 of INSTRUCTION.md). Edit it manually or use a dedicated confirmation workflow.`,
+      { filePath, operation },
     );
   }
 }

package/app/lib/errors.ts

@@ -0,0 +1,108 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * Centralized error class for MindOS backend business logic.
+ *
+ * Every throw in `lib/core/` should use this class so that:
+ * 1. API routes can detect it in catch blocks and return structured JSON.
+ * 2. Callers can switch on `code` for programmatic handling.
+ * 3. `userMessage` provides a translatable, user-safe description.
+ */
+export class MindOSError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public context?: Record<string, unknown>,
+    public userMessage?: string,
+  ) {
+    super(message);
+    this.name = 'MindOSError';
+  }
+}
+
+export const ErrorCodes = {
+  // File operations
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FILE_ALREADY_EXISTS: 'FILE_ALREADY_EXISTS',
+  PATH_OUTSIDE_ROOT: 'PATH_OUTSIDE_ROOT',
+  PROTECTED_FILE: 'PROTECTED_FILE',
+  INVALID_PATH: 'INVALID_PATH',
+  INVALID_RANGE: 'INVALID_RANGE',
+  HEADING_NOT_FOUND: 'HEADING_NOT_FOUND',
+  INVALID_FILE_TYPE: 'INVALID_FILE_TYPE',
+  // API
+  INVALID_REQUEST: 'INVALID_REQUEST',
+  MODEL_INIT_FAILED: 'MODEL_INIT_FAILED',
+  // Generic
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/** Standardized API error response envelope. */
+export interface ApiErrorResponse {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+/** Extract a human-readable message from an unknown thrown value. */
+export function toErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === 'string') return err;
+  return String(err);
+}
+
+/** Map an ErrorCode to an HTTP status code. */
+function mapCodeToStatus(code: ErrorCode): number {
+  switch (code) {
+    case ErrorCodes.FILE_NOT_FOUND:
+    case ErrorCodes.HEADING_NOT_FOUND:
+      return 404;
+    case ErrorCodes.FILE_ALREADY_EXISTS:
+      return 409;
+    case ErrorCodes.PATH_OUTSIDE_ROOT:
+    case ErrorCodes.PROTECTED_FILE:
+    case ErrorCodes.PERMISSION_DENIED:
+      return 403;
+    case ErrorCodes.INVALID_PATH:
+    case ErrorCodes.INVALID_RANGE:
+    case ErrorCodes.INVALID_FILE_TYPE:
+    case ErrorCodes.INVALID_REQUEST:
+      return 400;
+    case ErrorCodes.MODEL_INIT_FAILED:
+    case ErrorCodes.INTERNAL_ERROR:
+    default:
+      return 500;
+  }
+}
+
+/**
+ * Build a NextResponse with the standard `{ ok, error }` envelope.
+ *
+ * If `status` is omitted it is derived from the error code.
+ */
+export function apiError(code: ErrorCode, message: string, status?: number): NextResponse<ApiErrorResponse> {
+  const effectiveStatus = status ?? mapCodeToStatus(code);
+  return NextResponse.json({ ok: false as const, error: { code, message } }, { status: effectiveStatus });
+}
+
+/**
+ * Convenience: catch an unknown error and return a structured API response.
+ *
+ * Usage in route handlers:
+ * ```ts
+ * catch (err) {
+ *   return handleRouteError(err);
+ * }
+ * ```
+ */
+export function handleRouteError(err: unknown): NextResponse<ApiErrorResponse> {
+  if (err instanceof MindOSError) {
+    return apiError(err.code, err.message);
+  }
+  return apiError(ErrorCodes.INTERNAL_ERROR, 'Internal server error', 500);
+}

package/app/lib/fs.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import Fuse, { FuseResultMatch } from 'fuse.js';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 import {
   readFile as coreReadFile,
   writeFile as coreWriteFile,
@@ -19,6 +20,7 @@ import {
   isGitRepo as coreIsGitRepo,
   gitLog as coreGitLog,
   gitShowFile as coreGitShowFile,
+  invalidateSearchIndex,
 } from './core';
 import { FileNode } from './core/types';
 import { SearchMatch } from './types';
@@ -53,6 +55,7 @@ function isCacheValid(): boolean {
 export function invalidateCache(): void {
   _cache = null;
   _searchIndex = null;
+  invalidateSearchIndex();
 }
 
 function ensureCache(): FileTreeCache {
@@ -266,9 +269,9 @@ export function updateLines(filePath: string, startIndex: number, endIndex: numb
 
 export function deleteLines(filePath: string, startIndex: number, endIndex: number): void {
   const existing = readLines(filePath);
-  if (startIndex < 0 || endIndex < 0) throw new Error('Invalid line index: indices must be >= 0');
-  if (startIndex > endIndex) throw new Error(`Invalid range: start (${startIndex}) > end (${endIndex})`);
-  if (startIndex >= existing.length) throw new Error(`Invalid line index: start (${startIndex}) >= total lines (${existing.length})`);
+  if (startIndex < 0 || endIndex < 0) throw new MindOSError(ErrorCodes.INVALID_RANGE, 'Invalid line index: indices must be >= 0', { startIndex, endIndex });
+  if (startIndex > endIndex) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid range: start (${startIndex}) > end (${endIndex})`, { startIndex, endIndex });
+  if (startIndex >= existing.length) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid line index: start (${startIndex}) >= total lines (${existing.length})`, { startIndex, totalLines: existing.length });
   existing.splice(startIndex, endIndex - startIndex + 1);
   saveFileContent(filePath, existing.join('\n'));
 }