kotadb 2.1.0 → 2.2.0-next.20260204175832

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotadb",
-  "version": "2.1.0",
+  "version": "2.2.0-next.20260204175832",
   "description": "Local-only code intelligence tool for CLI agents. SQLite-backed repository indexing and code search via MCP.",
   "type": "module",
   "module": "src/index.ts",
@@ -54,8 +54,8 @@
     "@asteasolutions/zod-to-openapi": "^8.4.0",
     "@modelcontextprotocol/sdk": "^1.25.0",
     "@sentry/node": "^10.25.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@typescript-eslint/types": "^8.54.0",
+    "@typescript-eslint/parser": "8.54.0",
+    "@typescript-eslint/types": "8.54.0",
     "bcryptjs": "^2.4.3",
     "chokidar": "^5.0.0",
     "cors": "^2.8.6",
@@ -75,5 +75,8 @@
     "lint-staged": "^16.2.4",
     "supertest": "^7.1.4",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "@typescript-eslint/types": "8.54.0"
   }
 }

package/src/cli/args.ts

@@ -0,0 +1,105 @@
+/**
+ * CLI argument parsing utilities
+ *
+ * Extracted for testability. Used by main CLI entry point.
+ *
+ * @module cli/args
+ */
+
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
+export interface CliOptions {
+	port: number;
+	help: boolean;
+	version: boolean;
+	stdio: boolean;
+	toolset: ToolsetTier;
+}
+
+/**
+ * Type guard for valid toolset tier
+ */
+export function isValidToolsetTier(value: string): value is ToolsetTier {
+	return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
+/**
+ * Parse CLI arguments into options object
+ */
+export function parseArgs(args: string[]): CliOptions {
+	const options: CliOptions = {
+		port: Number(process.env.PORT ?? 3000),
+		help: false,
+		version: false,
+		stdio: false,
+		toolset: "default",
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === undefined) continue;
+
+		if (arg === "--help" || arg === "-h") {
+			options.help = true;
+		} else if (arg === "--version" || arg === "-v") {
+			options.version = true;
+		} else if (arg === "--stdio") {
+			options.stdio = true;
+		} else if (arg === "--port") {
+			const portStr = args[++i];
+			if (!portStr || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg.startsWith("--port=")) {
+			const portStr = arg.split("=")[1];
+			if (portStr === undefined || Number.isNaN(Number(portStr))) {
+				process.stderr.write("Error: --port requires a valid number\n");
+				process.exit(1);
+			}
+			options.port = Number(portStr);
+		} else if (arg === "--toolset") {
+			const tierStr = args[++i];
+			if (!tierStr) {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("--toolset=")) {
+			const tierStr = arg.split("=")[1];
+			if (tierStr === undefined || tierStr === "") {
+				process.stderr.write("Error: --toolset requires a tier value\n");
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			if (!isValidToolsetTier(tierStr)) {
+				process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+				process.stderr.write("Valid tiers: default, core, memory, full\n");
+				process.exit(1);
+			}
+			options.toolset = tierStr;
+		} else if (arg.startsWith("-") && arg !== "-") {
+			process.stderr.write(`Unknown option: ${arg}\n`);
+			process.stderr.write("Use --help for usage information\n");
+			process.exit(1);
+		}
+	}
+
+	return options;
+}

package/src/cli.ts

@@ -9,6 +9,7 @@
  *   kotadb              Start the MCP server (default port 3000)
  *   kotadb --stdio      Start in stdio mode (for Claude Code integration)
  *   kotadb --port 4000  Start on custom port
+ *   kotadb --toolset full  Select tool tier (default, core, memory, full)
  *   kotadb --version    Show version
  *   kotadb --help       Show help
  *   kotadb deps         Query dependency information for a file
@@ -25,11 +26,23 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
+const VALID_TOOLSET_TIERS: ToolsetTier[] = ["default", "core", "memory", "full"];
+
 interface CliOptions {
   port: number;
   help: boolean;
   version: boolean;
   stdio: boolean;
+  toolset: ToolsetTier;
 }
 
 function getVersion(): string {
@@ -70,6 +83,12 @@ COMMANDS:
 OPTIONS:
   --stdio           Use stdio transport (for Claude Code integration)
   --port <number>   Port to listen on (default: 3000, env: PORT)
+  --toolset <tier>  Select tool tier (default: default)
+                    Tiers:
+                      default  8 tools (core + sync)
+                      core     6 tools (search, index, deps, impact)
+                      memory   14 tools (core + sync + memory layer)
+                      full     20 tools (all available tools)
   --version, -v     Show version number
   --help, -h        Show this help message
 
@@ -81,6 +100,8 @@ ENVIRONMENT VARIABLES:
 
 EXAMPLES:
   kotadb --stdio                              Start in stdio mode (for Claude Code)
+  kotadb --stdio --toolset full               Start with all tools enabled
+  kotadb --stdio --toolset core               Start with minimal core tools
   kotadb                                      Start HTTP server on port 3000
   kotadb --port 4000                          Start HTTP server on port 4000
   kotadb deps --file src/db/client.ts         Query deps for a file (text)
@@ -99,6 +120,17 @@ MCP CONFIGURATION (stdio mode - RECOMMENDED):
     }
   }
 
+  With toolset selection:
+
+  {
+    "mcpServers": {
+      "kotadb": {
+        "command": "bunx",
+        "args": ["kotadb@next", "--stdio", "--toolset", "full"]
+      }
+    }
+  }
+
 MCP CONFIGURATION (HTTP mode - legacy):
   Add to your .mcp.json or Claude Code settings:
 
@@ -126,12 +158,17 @@ function printVersion(): void {
   process.stdout.write(`kotadb v${version}\n`);
 }
 
+function isValidToolsetTier(value: string): value is ToolsetTier {
+  return VALID_TOOLSET_TIERS.includes(value as ToolsetTier);
+}
+
 function parseArgs(args: string[]): CliOptions {
   const options: CliOptions = {
     port: Number(process.env.PORT ?? 3000),
     help: false,
     version: false,
     stdio: false,
+    toolset: "default",
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -158,6 +195,32 @@ function parseArgs(args: string[]): CliOptions {
         process.exit(1);
       }
       options.port = Number(portStr);
+    } else if (arg === "--toolset") {
+      const tierStr = args[++i];
+      if (!tierStr) {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
+    } else if (arg.startsWith("--toolset=")) {
+      const tierStr = arg.split("=")[1];
+      if (tierStr === undefined || tierStr === "") {
+        process.stderr.write("Error: --toolset requires a tier value\n");
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      if (!isValidToolsetTier(tierStr)) {
+        process.stderr.write(`Error: Invalid toolset tier '${tierStr}'\n`);
+        process.stderr.write("Valid tiers: default, core, memory, full\n");
+        process.exit(1);
+      }
+      options.toolset = tierStr;
     } else if (arg.startsWith("-") && arg !== "-") {
       process.stderr.write(`Unknown option: ${arg}\n`);
       process.stderr.write("Use --help for usage information\n");
@@ -168,7 +231,7 @@ function parseArgs(args: string[]): CliOptions {
   return options;
 }
 
-async function runStdioMode(): Promise<void> {
+async function runStdioMode(toolset: ToolsetTier): Promise<void> {
   // Redirect logger to stderr in stdio mode
   // This is CRITICAL - stdout is reserved for JSON-RPC protocol
   const logger = createLogger({
@@ -178,11 +241,13 @@ async function runStdioMode(): Promise<void> {
 
   logger.info("KotaDB MCP server starting in stdio mode", {
     version: getVersion(),
+    toolset,
   });
 
-  // Create MCP server with local-only context
+  // Create MCP server with local-only context and toolset
   const context: McpServerContext = {
     userId: "local", // Local-only mode uses fixed user ID
+    toolset,
   };
   const server = createMcpServer(context);
 
@@ -192,7 +257,7 @@ async function runStdioMode(): Promise<void> {
   // Connect server to transport
   await server.connect(transport);
 
-  logger.info("KotaDB MCP server connected via stdio");
+  logger.info("KotaDB MCP server connected via stdio", { toolset });
 
   // Server lifecycle is managed by the transport
   // Process will stay alive until stdin closes (when Claude Code terminates it)
@@ -234,7 +299,7 @@ async function main(): Promise<void> {
 
   // Handle stdio mode
   if (options.stdio) {
-    await runStdioMode();
+    await runStdioMode(options.toolset);
     return; // runStdioMode() keeps process alive
   }
 
@@ -247,6 +312,7 @@ async function main(): Promise<void> {
     mode: envConfig.mode,
     port: options.port,
     localDbPath: envConfig.localDbPath,
+    toolset: options.toolset,
   });
 
   const app = createExpressApp();
@@ -256,6 +322,7 @@ async function main(): Promise<void> {
       port: options.port,
       mcp_endpoint: `http://localhost:${options.port}/mcp`,
       health_endpoint: `http://localhost:${options.port}/health`,
+      toolset: options.toolset,
     });
 
     // Print user-friendly startup message
@@ -265,6 +332,7 @@ async function main(): Promise<void> {
     process.stdout.write(`  MCP Endpoint:    http://localhost:${options.port}/mcp\n`);
     process.stdout.write(`  Health Check:    http://localhost:${options.port}/health\n`);
     process.stdout.write(`  Database:        ${envConfig.localDbPath}\n`);
+    process.stdout.write(`  Toolset:         ${options.toolset}\n`);
     process.stdout.write(`\n`);
     process.stdout.write(`Press Ctrl+C to stop\n`);
     process.stdout.write(`\n`);

package/src/db/migrations/005_workflow_contexts.sql

@@ -0,0 +1,41 @@
+-- SQLite Migration: Workflow Context Accumulation
+--
+-- Migration: 005_workflow_contexts
+-- Issue: #144 - ADW context accumulation for inter-phase handoffs
+-- Author: Claude Code
+-- Date: 2026-02-04
+--
+-- This migration adds workflow context storage for ADW automation,
+-- enabling context accumulation between workflow phases (analysis -> plan -> build -> improve).
+-- Context is stored in the main KotaDB database for future MCP tool integration.
+
+-- ============================================================================
+-- 1. Workflow Contexts Table
+-- ============================================================================
+-- Stores curated context data for each workflow phase
+
+CREATE TABLE IF NOT EXISTS workflow_contexts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    workflow_id TEXT NOT NULL,           -- 'adw-123-20260204T120000'
+    phase TEXT NOT NULL,                 -- 'analysis' | 'plan' | 'build' | 'improve'
+    context_data TEXT NOT NULL,          -- JSON blob
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    
+    UNIQUE(workflow_id, phase),
+    CHECK (phase IN ('analysis', 'plan', 'build', 'improve'))
+);
+
+-- Index for workflow-scoped queries (primary access pattern)
+CREATE INDEX IF NOT EXISTS idx_workflow_contexts_workflow_id 
+ON workflow_contexts(workflow_id);
+
+-- Index for time-based queries (debugging/monitoring)
+CREATE INDEX IF NOT EXISTS idx_workflow_contexts_created_at 
+ON workflow_contexts(created_at DESC);
+
+-- ============================================================================
+-- 2. Record Migration
+-- ============================================================================
+
+INSERT OR IGNORE INTO schema_migrations (name) VALUES ('005_workflow_contexts');

package/src/indexer/ast-parser.ts

@@ -42,6 +42,24 @@ export interface ParseError {
 	column?: number;
 }
 
+/**
+ * Type guard to validate that an AST node is a valid Program.
+ * Provides runtime type validation to prevent version compatibility issues.
+ *
+ * @param ast - Unknown AST node to validate
+ * @returns true if ast is a valid Program node
+ */
+function isValidProgram(ast: unknown): ast is TSESTree.Program {
+	return (
+		ast !== null &&
+		typeof ast === "object" &&
+		"type" in ast &&
+		ast.type === "Program" &&
+		"body" in ast &&
+		Array.isArray(ast.body)
+	);
+}
+
 /**
  * Result of parsing a file, including partial AST recovery information.
  */
@@ -103,7 +121,7 @@ function createParseError(error: unknown): ParseError {
 
 /**
  * Parse a file with error-tolerant options enabled.
- * Uses allowInvalidAST to attempt partial recovery.
+ * Uses allowInvalidAST to attempt partial recovery and validates result.
  */
 function parseWithRecoveryOptions(filePath: string, content: string): TSESTree.Program | null {
 	try {
@@ -119,6 +137,18 @@ function parseWithRecoveryOptions(filePath: string, content: string): TSESTree.P
 			allowInvalidAST: true,
 			errorOnUnknownASTType: false,
 		});
+
+		// Validate the returned AST is actually a Program node
+		if (!isValidProgram(ast)) {
+			const astType = typeof ast === "object" && ast !== null && "type" in ast ? (ast as any).type : typeof ast;
+			logger.warn(`Parser returned invalid Program type for ${filePath}`, {
+				file_path: filePath,
+				ast_type: astType,
+				recovery: "failed_validation",
+			});
+			return null;
+		}
+
 		return ast;
 	} catch {
 		// Even with recovery options, parsing can still fail
@@ -159,6 +189,18 @@ export function parseFileWithRecovery(filePath: string, content: string): ParseR
 			tokens: true,
 			filePath,
 		});
+
+		// Validate the returned AST is actually a Program node
+		if (!isValidProgram(ast)) {
+			const astType = typeof ast === "object" && ast !== null && "type" in ast ? (ast as any).type : typeof ast;
+			logger.warn(`Parser returned invalid Program type for ${filePath}`, {
+				file_path: filePath,
+				ast_type: astType,
+				recovery: "failed_validation",
+			});
+			throw new Error(`Invalid AST type returned: expected Program, got ${astType}`);
+		}
+
 		return {
 			ast,
 			errors: [],

package/src/mcp/server.ts

@@ -18,17 +18,14 @@ import {
 	GENERATE_TASK_CONTEXT_TOOL,
 	INDEX_REPOSITORY_TOOL,
 	LIST_RECENT_FILES_TOOL,
-	SEARCH_CODE_TOOL,
+	SEARCH_TOOL,
 	SEARCH_DEPENDENCIES_TOOL,
 	SYNC_EXPORT_TOOL,
 	SYNC_IMPORT_TOOL,
 	VALIDATE_IMPLEMENTATION_SPEC_TOOL,
 	// Memory Layer tools
-	SEARCH_DECISIONS_TOOL,
 	RECORD_DECISION_TOOL,
-	SEARCH_FAILURES_TOOL,
 	RECORD_FAILURE_TOOL,
-	SEARCH_PATTERNS_TOOL,
 	RECORD_INSIGHT_TOOL,
 	// Dynamic Expertise tools
 	GET_DOMAIN_KEY_FILES_TOOL,
@@ -40,27 +37,35 @@ import {
 	executeGenerateTaskContext,
 	executeIndexRepository,
 	executeListRecentFiles,
-	executeSearchCode,
+	executeSearch,
 	executeSearchDependencies,
 	executeSyncExport,
 	executeSyncImport,
 	executeValidateImplementationSpec,
 	// Memory Layer execute functions
-	executeSearchDecisions,
 	executeRecordDecision,
-	executeSearchFailures,
 	executeRecordFailure,
-	executeSearchPatterns,
 	executeRecordInsight,
 	// Dynamic Expertise execute functions
 	executeGetDomainKeyFiles,
 	executeValidateExpertise,
 	executeSyncExpertise,
 	executeGetRecentPatterns,
+	// Tool filtering
+	filterToolsByTier,
 } from "./tools";
 
 const logger = createLogger({ module: "mcp-server" });
 
+/**
+ * Valid toolset tiers for MCP tool selection
+ * - default: 8 tools (core + sync)
+ * - core: 6 tools
+ * - memory: 14 tools (core + sync + memory)
+ * - full: 20 tools (all)
+ */
+export type ToolsetTier = "default" | "core" | "memory" | "full";
+
 /**
  * MCP Server context passed to tool handlers via closure
  *
@@ -68,6 +73,7 @@ const logger = createLogger({ module: "mcp-server" });
  */
 export interface McpServerContext {
 	userId: string;
+	toolset?: ToolsetTier;
 }
 
 /**
@@ -107,35 +113,20 @@ export function createMcpServer(context: McpServerContext): Server {
 		},
 	);
 
-	// Register tools/list handler - local-only tools
+	// Register tools/list handler - filter by toolset tier
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		const tier = context.toolset || "default";
+		const filteredTools = filterToolsByTier(tier);
+		
+		logger.debug("Listing MCP tools", { 
+			tier, 
+			tool_count: filteredTools.length 
+		});
+		
 		return {
-			tools: [
-				SEARCH_CODE_TOOL,
-				INDEX_REPOSITORY_TOOL,
-				LIST_RECENT_FILES_TOOL,
-				SEARCH_DEPENDENCIES_TOOL,
-				ANALYZE_CHANGE_IMPACT_TOOL,
-				VALIDATE_IMPLEMENTATION_SPEC_TOOL,
-				SYNC_EXPORT_TOOL,
-				SYNC_IMPORT_TOOL,
-				GENERATE_TASK_CONTEXT_TOOL,
-				// Memory Layer tools
-				SEARCH_DECISIONS_TOOL,
-				RECORD_DECISION_TOOL,
-				SEARCH_FAILURES_TOOL,
-				RECORD_FAILURE_TOOL,
-				SEARCH_PATTERNS_TOOL,
-				RECORD_INSIGHT_TOOL,
-				// Dynamic Expertise tools
-				GET_DOMAIN_KEY_FILES_TOOL,
-				VALIDATE_EXPERTISE_TOOL,
-				SYNC_EXPERTISE_TOOL,
-				GET_RECENT_PATTERNS_TOOL,
-			],
+			tools: filteredTools,
 		};
 	});
-
 	// Register tools/call handler
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const { name, arguments: toolArgs } = request.params;
@@ -146,8 +137,8 @@ export function createMcpServer(context: McpServerContext): Server {
 
 		try {
 			switch (name) {
-				case "search_code":
-					result = await executeSearchCode(
+				case "search":
+					result = await executeSearch(
 						toolArgs,
 						"", // requestId not used
 						context.userId,
@@ -202,13 +193,6 @@ export function createMcpServer(context: McpServerContext): Server {
 					);
 					break;
 				// Memory Layer tools
-				case "search_decisions":
-					result = await executeSearchDecisions(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_decision":
 					result = await executeRecordDecision(
 						toolArgs,
@@ -216,13 +200,6 @@ export function createMcpServer(context: McpServerContext): Server {
 						context.userId,
 					);
 					break;
-				case "search_failures":
-					result = await executeSearchFailures(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_failure":
 					result = await executeRecordFailure(
 						toolArgs,
@@ -230,13 +207,6 @@ export function createMcpServer(context: McpServerContext): Server {
 						context.userId,
 					);
 					break;
-				case "search_patterns":
-					result = await executeSearchPatterns(
-						toolArgs,
-						"", // requestId not used
-						context.userId,
-					);
-					break;
 				case "record_insight":
 					result = await executeRecordInsight(
 						toolArgs,