claude-code-workflow 6.2.7 → 6.3.0

package/ccw/src/tools/context-cache.ts

@@ -0,0 +1,393 @@
+/**
+ * Context Cache MCP Tool
+ * Pack files by @patterns, cache in memory, paginated read by session ID
+ *
+ * Operations:
+ * - pack: Parse @patterns and cache file contents
+ * - read: Paginated read from cache by session ID
+ * - status: Get cache/session status
+ * - release: Release session cache
+ * - cleanup: Cleanup expired caches
+ */
+
+import { z } from 'zod';
+import type { ToolSchema, ToolResult } from '../types/tool.js';
+import { parseAndPack } from './pattern-parser.js';
+import {
+  getContextCacheStore,
+  type CacheMetadata,
+  type PagedReadResult,
+  type CacheStatus,
+  type SessionStatus,
+} from './context-cache-store.js';
+
+// Zod schema for parameter validation
+const OperationEnum = z.enum(['pack', 'read', 'status', 'release', 'cleanup']);
+
+const ParamsSchema = z.object({
+  operation: OperationEnum,
+  // Pack parameters
+  patterns: z.array(z.string()).optional(),
+  content: z.string().optional(), // Direct text content to cache
+  session_id: z.string().optional(),
+  cwd: z.string().optional(),
+  include_dirs: z.array(z.string()).optional(),
+  ttl: z.number().optional(),
+  include_metadata: z.boolean().optional().default(true),
+  max_file_size: z.number().optional(),
+  // Read parameters
+  offset: z.number().optional().default(0),
+  limit: z.number().optional().default(65536), // 64KB default
+});
+
+type Params = z.infer<typeof ParamsSchema>;
+
+// Result types
+interface PackResult {
+  operation: 'pack';
+  session_id: string;
+  files_packed: number;
+  files_skipped: number;
+  total_bytes: number;
+  patterns_matched: number;
+  patterns_failed: number;
+  expires_at: string;
+  errors?: string[];
+}
+
+interface ReadResult {
+  operation: 'read';
+  session_id: string;
+  content: string;
+  offset: number;
+  limit: number;
+  total_bytes: number;
+  has_more: boolean;
+  next_offset: number | null;
+}
+
+interface StatusResult {
+  operation: 'status';
+  session_id?: string;
+  session?: SessionStatus;
+  cache?: CacheStatus;
+}
+
+interface ReleaseResult {
+  operation: 'release';
+  session_id: string;
+  released: boolean;
+  freed_bytes: number;
+}
+
+interface CleanupResult {
+  operation: 'cleanup';
+  removed: number;
+  remaining: number;
+}
+
+type OperationResult = PackResult | ReadResult | StatusResult | ReleaseResult | CleanupResult;
+
+/**
+ * Generate session ID if not provided
+ */
+function generateSessionId(): string {
+  return `ctx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Operation: pack
+ * Parse @patterns and/or cache text content directly
+ */
+async function executePack(params: Params): Promise<PackResult> {
+  const {
+    patterns,
+    content,
+    session_id,
+    cwd,
+    include_dirs,
+    ttl,
+    include_metadata,
+    max_file_size,
+  } = params;
+
+  // Require at least patterns or content
+  if ((!patterns || patterns.length === 0) && !content) {
+    throw new Error('Either "patterns" or "content" is required for pack operation');
+  }
+
+  const sessionId = session_id || generateSessionId();
+  const store = getContextCacheStore();
+
+  let finalContent = '';
+  let filesPacked = 0;
+  let filesSkipped = 0;
+  let totalBytes = 0;
+  let patternsMatched = 0;
+  let patternsFailed = 0;
+  let errors: string[] = [];
+  let files: string[] = [];
+  let parsedPatterns: string[] = [];
+
+  // Pack files from patterns if provided
+  if (patterns && patterns.length > 0) {
+    const result = await parseAndPack(patterns, {
+      cwd: cwd || process.cwd(),
+      includeDirs: include_dirs,
+      includeMetadata: include_metadata,
+      maxFileSize: max_file_size,
+    });
+
+    finalContent = result.content;
+    filesPacked = result.packedFiles.length;
+    filesSkipped = result.skippedFiles.length;
+    totalBytes = result.totalBytes;
+    patternsMatched = result.parseResult.stats.matched_patterns;
+    patternsFailed = result.parseResult.stats.total_patterns - patternsMatched;
+    errors = result.parseResult.errors;
+    files = result.packedFiles;
+    parsedPatterns = result.parseResult.patterns;
+  }
+
+  // Append direct content if provided
+  if (content) {
+    if (finalContent) {
+      finalContent += '\n\n=== ADDITIONAL CONTENT ===\n' + content;
+    } else {
+      finalContent = content;
+    }
+    totalBytes += Buffer.byteLength(content, 'utf-8');
+  }
+
+  // Store in cache
+  const metadata: CacheMetadata = {
+    files,
+    patterns: parsedPatterns,
+    total_bytes: totalBytes,
+    file_count: filesPacked,
+  };
+
+  const entry = store.set(sessionId, finalContent, metadata, ttl);
+  const expiresAt = new Date(entry.created_at + entry.ttl).toISOString();
+
+  return {
+    operation: 'pack',
+    session_id: sessionId,
+    files_packed: filesPacked,
+    files_skipped: filesSkipped,
+    total_bytes: totalBytes,
+    patterns_matched: patternsMatched,
+    patterns_failed: patternsFailed,
+    expires_at: expiresAt,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Operation: read
+ * Paginated read from cache
+ */
+function executeRead(params: Params): ReadResult {
+  const { session_id, offset, limit } = params;
+
+  if (!session_id) {
+    throw new Error('Parameter "session_id" is required for read operation');
+  }
+
+  const store = getContextCacheStore();
+  const result = store.read(session_id, offset, limit);
+
+  if (!result) {
+    throw new Error(`Session "${session_id}" not found or expired`);
+  }
+
+  return {
+    operation: 'read',
+    session_id,
+    content: result.content,
+    offset: result.offset,
+    limit: result.limit,
+    total_bytes: result.total_bytes,
+    has_more: result.has_more,
+    next_offset: result.next_offset,
+  };
+}
+
+/**
+ * Operation: status
+ * Get session or overall cache status
+ */
+function executeStatus(params: Params): StatusResult {
+  const { session_id } = params;
+  const store = getContextCacheStore();
+
+  if (session_id) {
+    // Session-specific status
+    const sessionStatus = store.getSessionStatus(session_id);
+    return {
+      operation: 'status',
+      session_id,
+      session: sessionStatus,
+    };
+  }
+
+  // Overall cache status
+  const cacheStatus = store.getStatus();
+  return {
+    operation: 'status',
+    cache: cacheStatus,
+  };
+}
+
+/**
+ * Operation: release
+ * Release session cache
+ */
+function executeRelease(params: Params): ReleaseResult {
+  const { session_id } = params;
+
+  if (!session_id) {
+    throw new Error('Parameter "session_id" is required for release operation');
+  }
+
+  const store = getContextCacheStore();
+  const result = store.release(session_id);
+
+  return {
+    operation: 'release',
+    session_id,
+    released: result.released,
+    freed_bytes: result.freed_bytes,
+  };
+}
+
+/**
+ * Operation: cleanup
+ * Cleanup expired caches
+ */
+function executeCleanup(): CleanupResult {
+  const store = getContextCacheStore();
+  const result = store.cleanupExpired();
+  const status = store.getStatus();
+
+  return {
+    operation: 'cleanup',
+    removed: result.removed,
+    remaining: status.entries,
+  };
+}
+
+/**
+ * Route to operation handler
+ */
+async function execute(params: Params): Promise<OperationResult> {
+  const { operation } = params;
+
+  switch (operation) {
+    case 'pack':
+      return executePack(params);
+    case 'read':
+      return executeRead(params);
+    case 'status':
+      return executeStatus(params);
+    case 'release':
+      return executeRelease(params);
+    case 'cleanup':
+      return executeCleanup();
+    default:
+      throw new Error(
+        `Unknown operation: ${operation}. Valid operations: pack, read, status, release, cleanup`
+      );
+  }
+}
+
+// MCP Tool Schema
+export const schema: ToolSchema = {
+  name: 'context_cache',
+  description: `Context file cache with @pattern and text content support, paginated reading.
+
+Usage:
+  context_cache(operation="pack", patterns=["@src/**/*.ts"], session_id="...")
+  context_cache(operation="pack", content="text to cache", session_id="...")
+  context_cache(operation="pack", patterns=["@src/**/*.ts"], content="extra text")
+  context_cache(operation="read", session_id="...", offset=0, limit=65536)
+  context_cache(operation="status", session_id="...")
+  context_cache(operation="release", session_id="...")
+  context_cache(operation="cleanup")
+
+Pattern syntax:
+  @src/**/*.ts     - All TypeScript files in src
+  @CLAUDE.md       - Specific file
+  @../shared/**/*  - Sibling directory (needs include_dirs)`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      operation: {
+        type: 'string',
+        enum: ['pack', 'read', 'status', 'release', 'cleanup'],
+        description: 'Operation to perform',
+      },
+      patterns: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '@patterns to pack (e.g., ["@src/**/*.ts"]). Either patterns or content required for pack.',
+      },
+      content: {
+        type: 'string',
+        description: 'Direct text content to cache. Either patterns or content required for pack.',
+      },
+      session_id: {
+        type: 'string',
+        description: 'Cache session ID. Auto-generated for pack if not provided.',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory for pattern resolution (default: process.cwd())',
+      },
+      include_dirs: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Additional directories to include for pattern matching',
+      },
+      ttl: {
+        type: 'number',
+        description: 'Cache TTL in milliseconds (default: 1800000 = 30min)',
+      },
+      include_metadata: {
+        type: 'boolean',
+        description: 'Include file metadata headers in packed content (default: true)',
+      },
+      max_file_size: {
+        type: 'number',
+        description: 'Max file size in bytes to include (default: 1MB). Larger files are skipped.',
+      },
+      offset: {
+        type: 'number',
+        description: 'Byte offset for paginated read (default: 0)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max bytes to read (default: 65536 = 64KB)',
+      },
+    },
+    required: ['operation'],
+  },
+};
+
+// Handler function
+export async function handler(
+  params: Record<string, unknown>
+): Promise<ToolResult<OperationResult>> {
+  const parsed = ParamsSchema.safeParse(params);
+
+  if (!parsed.success) {
+    return { success: false, error: `Invalid params: ${parsed.error.message}` };
+  }
+
+  try {
+    const result = await execute(parsed.data);
+    return { success: true, result };
+  } catch (error) {
+    return { success: false, error: (error as Error).message };
+  }
+}

package/ccw/src/tools/core-memory.ts

@@ -16,6 +16,8 @@ const OperationEnum = z.enum(['list', 'import', 'export', 'summary', 'embed', 's
 
 const ParamsSchema = z.object({
   operation: OperationEnum,
+  // Path parameter - highest priority for project resolution
+  path: z.string().optional(),
   text: z.string().optional(),
   id: z.string().optional(),
   tool: z.enum(['gemini', 'qwen']).optional().default('gemini'),
@@ -106,17 +108,21 @@ interface EmbedStatusResult {
 type OperationResult = ListResult | ImportResult | ExportResult | SummaryResult | EmbedResult | SearchResult | EmbedStatusResult;
 
 /**
- * Get project path from current working directory
+ * Get project path - uses explicit path if provided, otherwise falls back to current working directory
+ * Priority: path parameter > getProjectRoot()
  */
-function getProjectPath(): string {
+function getProjectPath(explicitPath?: string): string {
+  if (explicitPath) {
+    return explicitPath;
+  }
   return getProjectRoot();
 }
 
 /**
- * Get database path for current project
+ * Get database path for project
  */
-function getDatabasePath(): string {
-  const projectPath = getProjectPath();
+function getDatabasePath(explicitPath?: string): string {
+  const projectPath = getProjectPath(explicitPath);
   const paths = StoragePaths.project(projectPath);
   return join(paths.root, 'core-memory', 'core_memory.db');
 }
@@ -129,8 +135,8 @@ const PREVIEW_MAX_LENGTH = 100;
  * List all memories with compact output
  */
 function executeList(params: Params): ListResult {
-  const { limit } = params;
-  const store = getCoreMemoryStore(getProjectPath());
+  const { limit, path } = params;
+  const store = getCoreMemoryStore(getProjectPath(path));
   const memories = store.getMemories({ limit }) as CoreMemory[];
 
   // Convert to compact format with truncated preview
@@ -160,13 +166,13 @@ function executeList(params: Params): ListResult {
  * Import text as a new memory
  */
 function executeImport(params: Params): ImportResult {
-  const { text } = params;
+  const { text, path } = params;
 
   if (!text || text.trim() === '') {
     throw new Error('Parameter "text" is required for import operation');
   }
 
-  const store = getCoreMemoryStore(getProjectPath());
+  const store = getCoreMemoryStore(getProjectPath(path));
   const memory = store.upsertMemory({
     content: text.trim(),
   });
@@ -184,14 +190,14 @@ function executeImport(params: Params): ImportResult {
  * Searches current project first, then all projects if not found
  */
 function executeExport(params: Params): ExportResult {
-  const { id } = params;
+  const { id, path } = params;
 
   if (!id) {
     throw new Error('Parameter "id" is required for export operation');
   }
 
-  // Try current project first
-  const store = getCoreMemoryStore(getProjectPath());
+  // Try current project first (or explicit path if provided)
+  const store = getCoreMemoryStore(getProjectPath(path));
   let memory = store.getMemory(id);
 
   // If not found, search across all projects
@@ -218,13 +224,13 @@ function executeExport(params: Params): ExportResult {
  * Generate AI summary for a memory
  */
 async function executeSummary(params: Params): Promise<SummaryResult> {
-  const { id, tool = 'gemini' } = params;
+  const { id, tool = 'gemini', path } = params;
 
   if (!id) {
     throw new Error('Parameter "id" is required for summary operation');
   }
 
-  const store = getCoreMemoryStore(getProjectPath());
+  const store = getCoreMemoryStore(getProjectPath(path));
   const memory = store.getMemory(id);
 
   if (!memory) {
@@ -245,8 +251,8 @@ async function executeSummary(params: Params): Promise<SummaryResult> {
  * Generate embeddings for memory chunks
  */
 async function executeEmbed(params: Params): Promise<EmbedResult> {
-  const { source_id, batch_size = 8, force = false } = params;
-  const dbPath = getDatabasePath();
+  const { source_id, batch_size = 8, force = false, path } = params;
+  const dbPath = getDatabasePath(path);
 
   const result = await MemoryEmbedder.generateEmbeddings(dbPath, {
     sourceId: source_id,
@@ -272,13 +278,13 @@ async function executeEmbed(params: Params): Promise<EmbedResult> {
  * Search memory chunks using semantic search
  */
 async function executeSearch(params: Params): Promise<SearchResult> {
-  const { query, top_k = 10, min_score = 0.3, source_type } = params;
+  const { query, top_k = 10, min_score = 0.3, source_type, path } = params;
 
   if (!query) {
     throw new Error('Parameter "query" is required for search operation');
   }
 
-  const dbPath = getDatabasePath();
+  const dbPath = getDatabasePath(path);
 
   const result = await MemoryEmbedder.searchMemories(dbPath, query, {
     topK: top_k,
@@ -309,7 +315,8 @@ async function executeSearch(params: Params): Promise<SearchResult> {
  * Get embedding status statistics
  */
 async function executeEmbedStatus(params: Params): Promise<EmbedStatusResult> {
-  const dbPath = getDatabasePath();
+  const { path } = params;
+  const dbPath = getDatabasePath(path);
 
   const result = await MemoryEmbedder.getEmbeddingStatus(dbPath);
 
@@ -368,6 +375,9 @@ Usage:
   core_memory(operation="search", query="authentication")    # Search memories semantically
   core_memory(operation="embed_status")                      # Check embedding status
 
+Path parameter (highest priority):
+  core_memory(operation="list", path="/path/to/project")     # Use specific project path
+
 Memory IDs use format: CMEM-YYYYMMDD-HHMMSS`,
   inputSchema: {
     type: 'object',
@@ -377,6 +387,10 @@ Memory IDs use format: CMEM-YYYYMMDD-HHMMSS`,
         enum: ['list', 'import', 'export', 'summary', 'embed', 'search', 'embed_status'],
         description: 'Operation to perform',
       },
+      path: {
+        type: 'string',
+        description: 'Project path (highest priority - overrides auto-detected project root)',
+      },
       text: {
         type: 'string',
         description: 'Text content to import (required for import operation)',

package/ccw/src/tools/index.ts

@@ -22,6 +22,7 @@ import { executeInitWithProgress } from './smart-search.js';
 // codex_lens removed - functionality integrated into smart_search
 import * as readFileMod from './read-file.js';
 import * as coreMemoryMod from './core-memory.js';
+import * as contextCacheMod from './context-cache.js';
 import type { ProgressInfo } from './codex-lens.js';
 
 // Import legacy JS tools
@@ -357,6 +358,7 @@ registerTool(toLegacyTool(smartSearchMod));
 // codex_lens removed - functionality integrated into smart_search
 registerTool(toLegacyTool(readFileMod));
 registerTool(toLegacyTool(coreMemoryMod));
+registerTool(toLegacyTool(contextCacheMod));
 
 // Register legacy JS tools
 registerTool(uiGeneratePreviewTool);