@mnemonik/shared 1.0.0

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @mnemonik/shared - Shared constants and utilities
+ *
+ * This package provides a single source of truth for constants
+ * that need to be shared across Mnemonik packages.
+ */
+export { MCP_INSTRUCTIONS, MCP_INSTRUCTIONS_RAW, getMcpInstructions } from './instructions.js';
+export { USAGE_GUIDE } from './usageGuide.js';
+export { CodeScanner } from './codeScanner.js';
+export { FileSystemReader, getFileSystemReader, } from './FileSystemReader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAoC,MAAM,kBAAkB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,mBAAmB,GAIpB,MAAM,uBAAuB,CAAC"}

package/dist/instructions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP Instructions - Persistent agent guidance
+ *
+ * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
+ * Shared instruction content imported by the server.
+ *
+ * Version: 2.92
+ * Updated: 2026-02-24
+ *
+ * v2.93: Code mode permanent — all memory operations via memory_tools sandbox.
+ *        memory_add, file_context etc. are now mnemonik.* methods, not standalone tools.
+ *
+ * v2.92: Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
+ *        Session summaries are auto-saved if agent doesn't call mnemonik.memory_add().
+ *        Instructions drastically simplified — the server handles the workflow now.
+ *
+ * v2.80: Token-optimised rewrite (superseded by v2.92).
+ */
+/**
+ * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.
+ */
+export declare function getMcpInstructions(): string;
+/**
+ * Raw instructions content (always returns the content, ignores env var).
+ * Use getMcpInstructions() for production code.
+ */
+export declare const MCP_INSTRUCTIONS_RAW = "You have Mnemonik, a persistent memory system for this project.\n\nFirst call, every session: session_bootstrap. Read the mnemonik skill (from available_skills) for the full workflow.\nAfter bootstrap: execute _directive.message actions immediately (scanner daemon check is mandatory).\n\nProactively call memory_search before starting new work \u2014 avoids rediscovering known patterns and contradicting past decisions.\nProactively call file_context before editing any file \u2014 loads past bugs, decisions, and gotchas for that file.\nProactively call checkpoint after making changes or decisions worth keeping \u2014 your context is ephemeral and checkpoint is the only way decisions survive across sessions and context compaction. Do not wait for the user to say \"done\" or \"thanks\".\n\nWhen mnemonik.file_context({ filePaths, cwd }) returns linkedDocs with driftStatus 'stale', update docs then call mnemonik.docs({ action: 'resolve', docPath, cwd }).\n\nSkip: formatting-only, trivial one-line, mechanical refactors, git ops, tests.\nSave: architectural decisions, bug root causes, user preferences, discovered patterns, multi-file changes.";
+/**
+ * Default export for convenience.
+ * Note: This respects the MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ */
+export declare const MCP_INSTRUCTIONS: string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAK3C;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,qoCAAuB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAuB,CAAC"}

package/dist/instructions.js

@@ -0,0 +1,52 @@
+/**
+ * MCP Instructions - Persistent agent guidance
+ *
+ * This is the SINGLE SOURCE OF TRUTH for MCP instructions.
+ * Shared instruction content imported by the server.
+ *
+ * Version: 2.92
+ * Updated: 2026-02-24
+ *
+ * v2.93: Code mode permanent — all memory operations via memory_tools sandbox.
+ *        memory_add, file_context etc. are now mnemonik.* methods, not standalone tools.
+ *
+ * v2.92: Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
+ *        Session summaries are auto-saved if agent doesn't call mnemonik.memory_add().
+ *        Instructions drastically simplified — the server handles the workflow now.
+ *
+ * v2.80: Token-optimised rewrite (superseded by v2.92).
+ */
+const INSTRUCTIONS_CONTENT = `You have Mnemonik, a persistent memory system for this project.
+
+First call, every session: session_bootstrap. Read the mnemonik skill (from available_skills) for the full workflow.
+After bootstrap: execute _directive.message actions immediately (scanner daemon check is mandatory).
+
+Proactively call memory_search before starting new work — avoids rediscovering known patterns and contradicting past decisions.
+Proactively call file_context before editing any file — loads past bugs, decisions, and gotchas for that file.
+Proactively call checkpoint after making changes or decisions worth keeping — your context is ephemeral and checkpoint is the only way decisions survive across sessions and context compaction. Do not wait for the user to say "done" or "thanks".
+
+When mnemonik.file_context({ filePaths, cwd }) returns linkedDocs with driftStatus 'stale', update docs then call mnemonik.docs({ action: 'resolve', docPath, cwd }).
+
+Skip: formatting-only, trivial one-line, mechanical refactors, git ops, tests.
+Save: architectural decisions, bug root causes, user preferences, discovered patterns, multi-file changes.`;
+/**
+ * Get MCP instructions, respecting MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ * Set MNEMONIK_INSTRUCTIONS_ENABLED=false to disable for testing.
+ */
+export function getMcpInstructions() {
+    if (typeof process !== 'undefined' && process.env?.MNEMONIK_INSTRUCTIONS_ENABLED === 'false') {
+        return '';
+    }
+    return INSTRUCTIONS_CONTENT;
+}
+/**
+ * Raw instructions content (always returns the content, ignores env var).
+ * Use getMcpInstructions() for production code.
+ */
+export const MCP_INSTRUCTIONS_RAW = INSTRUCTIONS_CONTENT;
+/**
+ * Default export for convenience.
+ * Note: This respects the MNEMONIK_INSTRUCTIONS_ENABLED env var.
+ */
+export const MCP_INSTRUCTIONS = getMcpInstructions();
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,oBAAoB,GAAG;;;;;;;;;;;;2GAY8E,CAAC;AAE5G;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,6BAA6B,KAAK,OAAO,EAAE,CAAC;QAC7F,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,EAAE,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,4 @@
+export declare const debug: (_msg: string, _ctx?: Record<string, unknown>) => void;
+export declare const info: (msg: string, ctx?: Record<string, unknown>) => void;
+export declare const warn: (msg: string, ctx?: Record<string, unknown>) => void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAU,CAAC;AAChF,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAEjE,CAAC;AACF,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAEjE,CAAC"}

package/dist/logger.js

@@ -0,0 +1,8 @@
+export const debug = (_msg, _ctx) => { };
+export const info = (msg, ctx) => {
+    console.log(`[info] ${msg}`, ctx ? JSON.stringify(ctx) : '');
+};
+export const warn = (msg, ctx) => {
+    console.warn(`[warn] ${msg}`, ctx ? JSON.stringify(ctx) : '');
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,IAA8B,EAAQ,EAAE,GAAE,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;IACvE,OAAO,CAAC,GAAG,CAAC,UAAU,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC,CAAC;AACF,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,GAA6B,EAAQ,EAAE;IACvE,OAAO,CAAC,IAAI,CAAC,UAAU,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC,CAAC"}

package/dist/usageGuide.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Mnemonik Usage Guide - Procedural workflow guidance for agents
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the usage guide.
+ * Shared usage guide content imported by the server.
+ *
+ * Version: 2.80
+ * Updated: 2026-02-20 - Aligned with instructions/rules/skill v2.80
+ *
+ * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
+ * Tool schemas already tell agents what's available - they need the workflow.
+ */
+export declare const USAGE_GUIDE = "# Mnemonik Workflow Guide (v2.80)\n\n## Workflow\n\nsession_bootstrap \u2192 memory_search \u2192 file_context \u2192 [work] \u2192 memory_add \u2192 memory_state\n\n## Tool Selection by Stage\n\n### Session start\n- session_bootstrap: loads context, policies, pending tasks (call once, first thing)\n- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)\n- projects: resolve project IDs if context unclear\n- policy: review safety rules\n\n### Before editing files\n- file_context: fetch memories for the file \u2014 call for EVERY file you edit\n- memory_search: second search scoped to file/module if needed\n- docs(action: 'links'): check doc couplings for the file\n\n### During implementation\n- memory_get: retrieve specific memory by id\n- memory_update: refine memory created this session\n- memory_info: query history, provenance, confidence breakdown, links, graph\n- assist: get tool guidance if uncertain\n\n### After significant work\n- memory_add: save decisions, outcomes, patterns, bug root causes\n- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute\n- tasks: mark tasks in progress or complete\n- docs(action: 'drift'): check for stale documentation after code changes\n- docs(action: 'resolve'): mark stale docs as fixed after updating them\n\n### Diagnostics\n- doctor: when tool calls fail or behavior is inconsistent\n- scanner: refresh embeddings, trigger scans, check drift\n\n## Skip conditions\n\nSkip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.\n\n## Completion gate\n\nNever tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. \"Progress updates\" count.\n\n## Memory search tips\n\n- Query should include task intent + key entities\n- Set workflowContext when you know the phase\n- Use currentFile to boost file-linked memories\n- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)\n\n## Proactive heuristics\n\n- Long sessions: re-run memory_search after switching topics\n- Conflicting info: use memory_state to supersede/dispute\n- High-impact changes: save memory immediately after verification\n- When file_context returns linkedDocs with driftStatus 'stale': update docs then docs(action: 'resolve')\n\n## Anti-fade (every ~10 tool calls)\n\nCheck: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.\n";
+//# sourceMappingURL=usageGuide.d.ts.map

package/dist/usageGuide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageGuide.d.ts","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,wkFA6DvB,CAAC"}

package/dist/usageGuide.js

@@ -0,0 +1,75 @@
+/**
+ * Mnemonik Usage Guide - Procedural workflow guidance for agents
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the usage guide.
+ * Shared usage guide content imported by the server.
+ *
+ * Version: 2.80
+ * Updated: 2026-02-20 - Aligned with instructions/rules/skill v2.80
+ *
+ * This guide focuses on HOW to use Mnemonik effectively, not WHAT tools exist.
+ * Tool schemas already tell agents what's available - they need the workflow.
+ */
+export const USAGE_GUIDE = `# Mnemonik Workflow Guide (v2.80)
+
+## Workflow
+
+session_bootstrap → memory_search → file_context → [work] → memory_add → memory_state
+
+## Tool Selection by Stage
+
+### Session start
+- session_bootstrap: loads context, policies, pending tasks (call once, first thing)
+- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)
+- projects: resolve project IDs if context unclear
+- policy: review safety rules
+
+### Before editing files
+- file_context: fetch memories for the file — call for EVERY file you edit
+- memory_search: second search scoped to file/module if needed
+- docs(action: 'links'): check doc couplings for the file
+
+### During implementation
+- memory_get: retrieve specific memory by id
+- memory_update: refine memory created this session
+- memory_info: query history, provenance, confidence breakdown, links, graph
+- assist: get tool guidance if uncertain
+
+### After significant work
+- memory_add: save decisions, outcomes, patterns, bug root causes
+- memory_state: reinforce (memory helped), supersede (replace outdated), deprecate, penalize, dispute
+- tasks: mark tasks in progress or complete
+- docs(action: 'drift'): check for stale documentation after code changes
+- docs(action: 'resolve'): mark stale docs as fixed after updating them
+
+### Diagnostics
+- doctor: when tool calls fail or behavior is inconsistent
+- scanner: refresh embeddings, trigger scans, check drift
+
+## Skip conditions
+
+Skip memory tools for: formatting-only edits, trivial one-line changes, mechanical refactors, git operations, running tests.
+
+## Completion gate
+
+Never tell the user significant work is done without calling memory_add first in the same response. Changes made + responding next = completion. "Progress updates" count.
+
+## Memory search tips
+
+- Query should include task intent + key entities
+- Set workflowContext when you know the phase
+- Use currentFile to boost file-linked memories
+- Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)
+
+## Proactive heuristics
+
+- Long sessions: re-run memory_search after switching topics
+- Conflicting info: use memory_state to supersede/dispute
+- High-impact changes: save memory immediately after verification
+- When file_context returns linkedDocs with driftStatus 'stale': update docs then docs(action: 'resolve')
+
+## Anti-fade (every ~10 tool calls)
+
+Check: (1) memory_search before work? (2) file_context before edit? (3) memory_add after completing? No session_bootstrap? Call it now.
+`;
+//# sourceMappingURL=usageGuide.js.map

package/dist/usageGuide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageGuide.js","sourceRoot":"","sources":["../src/usageGuide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D1B,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mnemonik/shared",
+  "version": "1.0.0",
+  "description": "Shared constants and utilities for Mnemonik packages",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mnemonik",
+    "shared",
+    "constants"
+  ],
+  "author": "Anthony",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/FileSystemReader.ts

@@ -0,0 +1,299 @@
+/**
+ * FileSystemReader — Encapsulates all filesystem operations for scanning.
+ *
+ * This module is the boundary between disk I/O and the rest of the system.
+ * In a cloud deployment, a lightweight client-side agent uses this module
+ * locally and pushes results to the server's indexing API; the server
+ * itself never touches the filesystem.
+ */
+
+import { readdir, readFile, stat } from 'fs/promises';
+import { join, relative, isAbsolute } from 'path';
+import { createHash } from 'crypto';
+import { debug as logDebug, warn as logWarn, info as logInfo } from './logger.js';
+import { withTimeout } from './asyncUtils.js';
+import { CodeScanner, CodeChunk } from './codeScanner.js';
+
+const FILE_OP_TIMEOUT_MS = 5000;
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  'venv',
+  '.venv',
+  'env',
+  '.env',
+  '__pycache__',
+  '.cache',
+  'target',
+  '.tox',
+  '.mypy_cache',
+  '.pytest_cache',
+]);
+
+const TEXT_EXTENSIONS = new Set([
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'py',
+  'java',
+  'cpp',
+  'c',
+  'h',
+  'hpp',
+  'go',
+  'rs',
+  'php',
+  'rb',
+  'swift',
+  'kt',
+  'scala',
+  'sh',
+  'bash',
+  'sql',
+  'html',
+  'css',
+  'scss',
+  'sass',
+  'less',
+  'json',
+  'yaml',
+  'yml',
+  'toml',
+  'xml',
+  'md',
+  'txt',
+  'vue',
+  'svelte',
+  'astro',
+]);
+
+const SKIP_PATTERNS = ['.min.js', '.min.css', '.bundle.js', '.legacy.js', '.map'];
+
+export interface FileData {
+  /** Relative path from project root */
+  path: string;
+  /** SHA-256 hash (content + size + mtime) */
+  hash: string;
+}
+
+export interface ScanFilesResult {
+  files: FileData[];
+  chunks: CodeChunk[];
+}
+
+export interface ChangedFilesResult {
+  changed: FileData[];
+  chunks: CodeChunk[];
+  skipped: number;
+}
+
+export class FileSystemReader {
+  /**
+   * Recursively list all scannable text files in a project directory.
+   * Returns absolute paths.
+   */
+  async readProjectFiles(dirPath: string): Promise<string[]> {
+    const files: string[] = [];
+    await this.traverseDirectory(dirPath, files);
+    return files;
+  }
+
+  /**
+   * Compute SHA-256 hash for a file (content + size + mtime).
+   * Returns empty string on error or if the file exceeds MAX_FILE_SIZE.
+   */
+  async calculateFileHash(filePath: string): Promise<string> {
+    try {
+      const stats = await withTimeout(
+        stat(filePath),
+        FILE_OP_TIMEOUT_MS,
+        `stat timed out: ${filePath}`
+      );
+
+      if (stats.size > MAX_FILE_SIZE) {
+        logDebug('Skipping file hash — exceeds size limit', {
+          file: filePath,
+          size: stats.size,
+        });
+        return '';
+      }
+
+      const content = await withTimeout(
+        readFile(filePath, 'utf-8'),
+        FILE_OP_TIMEOUT_MS,
+        `readFile timed out: ${filePath}`
+      );
+
+      const hashInput = `${content}\n${stats.size}\n${stats.mtime.getTime()}`;
+      return createHash('sha256').update(hashInput).digest('hex');
+    } catch (error) {
+      logWarn('Failed to calculate file hash', {
+        file: filePath,
+        error: (error as Error).message,
+      });
+      return '';
+    }
+  }
+
+  /**
+   * Scan a directory and return files + extracted code chunks.
+   */
+  async scanDirectory(projectPath: string): Promise<ScanFilesResult> {
+    const scanner = new CodeScanner();
+    const chunks = await scanner.scanDirectory(projectPath);
+
+    const files: FileData[] = [];
+    const seen = new Set<string>();
+    for (const chunk of chunks) {
+      if (!seen.has(chunk.filePath)) {
+        seen.add(chunk.filePath);
+        const absPath = isAbsolute(chunk.filePath)
+          ? chunk.filePath
+          : join(projectPath, chunk.filePath);
+        const hash = await this.calculateFileHash(absPath);
+        files.push({ path: chunk.filePath, hash });
+      }
+    }
+
+    return { files, chunks };
+  }
+
+  /**
+   * Determine which files have changed compared to known hashes.
+   * Returns changed files plus their extracted code chunks.
+   */
+  async detectChangedFiles(
+    projectPath: string,
+    knownHashes: Map<string, string>
+  ): Promise<ChangedFilesResult> {
+    const allFiles = await this.readProjectFiles(projectPath);
+    const changed: FileData[] = [];
+    let skipped = 0;
+
+    for (const absPath of allFiles) {
+      try {
+        const hash = await this.calculateFileHash(absPath);
+        const relPath = relative(projectPath, absPath);
+        const known = knownHashes.get(absPath) ?? knownHashes.get(relPath);
+        if (!known || known !== hash) {
+          changed.push({ path: absPath, hash });
+        } else {
+          skipped++;
+        }
+      } catch (error) {
+        logWarn('Failed to process file for incremental scan', {
+          file: absPath,
+          error: (error as Error).message,
+        });
+      }
+    }
+
+    logInfo('Incremental scan analysis', {
+      totalFiles: allFiles.length,
+      filesToScan: changed.length,
+      filesSkipped: skipped,
+    });
+
+    if (changed.length === 0) {
+      return { changed: [], chunks: [], skipped };
+    }
+
+    const scanner = new CodeScanner();
+    const chunks = await scanner.scanFiles(
+      changed.map((f) => f.path),
+      projectPath
+    );
+
+    return { changed, chunks, skipped };
+  }
+
+  /**
+   * Read file content with timeout protection.
+   */
+  async readFileContent(filePath: string): Promise<string | null> {
+    try {
+      return await withTimeout(
+        readFile(filePath, 'utf-8'),
+        FILE_OP_TIMEOUT_MS,
+        `readFile timed out: ${filePath}`
+      );
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Stat a file with timeout protection.
+   */
+  async statFile(filePath: string): Promise<{ mtime: Date; size: number } | null> {
+    try {
+      const s = await withTimeout(
+        stat(filePath),
+        FILE_OP_TIMEOUT_MS,
+        `stat timed out: ${filePath}`
+      );
+      return { mtime: s.mtime, size: s.size };
+    } catch {
+      return null;
+    }
+  }
+
+  // ── private helpers ─────────────────────────────────────────────────
+
+  private async traverseDirectory(dirPath: string, files: string[]): Promise<void> {
+    try {
+      const entries = await withTimeout(
+        readdir(dirPath, { withFileTypes: true }),
+        FILE_OP_TIMEOUT_MS,
+        `readdir timed out: ${dirPath}`
+      );
+
+      for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          if (SKIP_DIRS.has(entry.name)) continue;
+          await this.traverseDirectory(fullPath, files);
+        } else if (entry.isFile() && this.isTextFile(entry.name)) {
+          try {
+            const fileStat = await withTimeout(
+              stat(fullPath),
+              FILE_OP_TIMEOUT_MS,
+              `stat timed out: ${fullPath}`
+            );
+            if (fileStat.size <= 100 * 1024) {
+              files.push(fullPath);
+            }
+          } catch {
+            // can't stat → skip
+          }
+        }
+      }
+    } catch (error) {
+      logWarn('Failed to read directory', {
+        path: dirPath,
+        error: (error as Error).message,
+      });
+    }
+  }
+
+  private isTextFile(filename: string): boolean {
+    if (SKIP_PATTERNS.some((p) => filename.endsWith(p))) return false;
+    const ext = filename.split('.').pop()?.toLowerCase();
+    return TEXT_EXTENSIONS.has(ext || '');
+  }
+}
+
+/** Singleton for convenience */
+let _instance: FileSystemReader | null = null;
+export function getFileSystemReader(): FileSystemReader {
+  if (!_instance) _instance = new FileSystemReader();
+  return _instance;
+}

package/src/asyncUtils.ts

@@ -0,0 +1,16 @@
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage?: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(timeoutMessage ?? `Operation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer);
+  });
+}