kotadb 2.0.0

package/README.md

@@ -0,0 +1,79 @@
+# KotaDB Application Layer
+
+This directory contains the TypeScript/Bun HTTP API service for indexing and searching code repositories.
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.1+
+
+### Install Dependencies
+
+```bash
+bun install
+```
+
+### Run the Server
+
+```bash
+# Development mode with watch
+bun --watch src/index.ts
+
+# Production mode
+bun run src/index.ts
+
+# Custom port
+PORT=4000 bun run src/index.ts
+```
+
+The server will start on port 3000 by default. Data is stored in `.kotadb/kota.db` within your project directory.
+
+## Development Commands
+
+### Type Checking and Linting
+
+```bash
+bunx tsc --noEmit    # Type-check without emitting files
+bun run lint         # Biome linting
+```
+
+### Testing
+
+```bash
+# Run tests
+bun test
+```
+
+## Project Structure
+
+```
+src/
+  api/          # HTTP routes and database queries
+  db/           # SQLite client and database utilities
+  indexer/      # Git repository indexing logic
+  mcp/          # Model Context Protocol implementation
+  types/        # Shared TypeScript types
+
+tests/          # Test suite
+  api/          # API endpoint tests
+  indexer/      # Indexer tests
+  mcp/          # MCP protocol tests
+  helpers/      # Test utilities
+
+scripts/        # Bash scripts for development
+```
+
+## API Endpoints
+
+- `GET /health` - Health check
+- `POST /index` - Index a repository
+- `GET /search?term=query` - Search indexed files
+- `GET /files/recent` - List recently indexed files
+- `POST /mcp` - Model Context Protocol endpoint
+
+## Learn More
+
+- [Repository Overview](../README.md)
+- [Architecture Documentation](../CLAUDE.md)
+- [Database Schema](../docs/schema.md)

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "kotadb",
+  "version": "2.0.0",
+  "description": "Local-only code intelligence tool for CLI agents. SQLite-backed repository indexing and code search via MCP.",
+  "type": "module",
+  "module": "src/index.ts",
+  "bin": {
+    "kotadb": "./src/cli.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.js",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ],
+  "keywords": [
+    "mcp",
+    "code-search",
+    "code-intelligence",
+    "sqlite",
+    "cli",
+    "claude-code",
+    "model-context-protocol"
+  ],
+  "author": "Jaymin West",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayminwest/kotadb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jayminwest/kotadb/issues"
+  },
+  "homepage": "https://github.com/jayminwest/kotadb#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "test": "bun test --preload ./tests/setup.ts",
+    "check": "bun run typecheck",
+    "typecheck": "bunx tsc --noEmit",
+    "build": "bun run typecheck",
+    "lint": "bunx biome lint",
+    "test:validate-env": "! grep -rn 'process\\.env\\.\\(SUPABASE_URL\\|DATABASE_URL\\)\\s*=\\s*[\"\\x27]' tests/ || (echo 'ERROR: Found hardcoded environment variable string assignments in tests/' && exit 1)",
+    "prepare": "husky || true",
+    "prepublishOnly": "bun run typecheck && bun run lint"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.2.0",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@sentry/node": "^10.25.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/types": "^8.0.0",
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "express": "^4.18.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@biomejs/biome": "^1.7.3",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.9.0",
+    "@types/supertest": "^6.0.3",
+    "bun-types": "^1.1.10",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.4",
+    "supertest": "^7.1.4",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api/auto-reindex.ts

@@ -0,0 +1,55 @@
+/**
+ * Auto-reindex trigger logic for session-based repository synchronization.
+ *
+ * NOTE: Queue system removed for local-only v2.0.0 (Issue #591)
+ * This module is now a stub that returns "not available" responses.
+ * Auto-reindex functionality requires async queue processing which is not
+ * available in local-only mode.
+ *
+ * TODO: For cloud mode restoration, re-implement with pg-boss queue
+ */
+
+import type { AuthContext } from "@shared/types";
+import { createLogger } from "@logging/logger.js";
+
+const logger = createLogger({ module: "api-auto-reindex" });
+
+/**
+ * Auto-reindex result containing triggered job information.
+ */
+export interface AutoReindexResult {
+	triggered: boolean;
+	jobCount: number;
+	jobIds: string[];
+	rateLimited?: boolean;
+	reason?: string;
+}
+
+/**
+ * Trigger auto-reindex for authenticated user's project repositories.
+ *
+ * NOTE: Queue system removed for local-only v2.0.0 (Issue #591)
+ * This function now returns a "not available" response.
+ * Use MCP tools for synchronous indexing instead.
+ *
+ * @param context - Authentication context with user ID and key ID
+ * @returns Auto-reindex result indicating feature is unavailable
+ */
+export async function triggerAutoReindex(
+	context: AuthContext,
+): Promise<AutoReindexResult> {
+	const { userId } = context;
+
+	logger.info("Auto-reindex requested but unavailable in local-only mode", {
+		user_id: userId,
+	});
+
+	// Queue system removed - auto-reindex requires async job processing
+	// Return a response indicating the feature is unavailable
+	return {
+		triggered: false,
+		jobCount: 0,
+		jobIds: [],
+		reason: "Auto-reindex unavailable - queue system removed for local-only mode. Use MCP index_repository tool for synchronous indexing.",
+	};
+}

package/src/api/openapi/builder.ts

@@ -0,0 +1,209 @@
+/**
+ * OpenAPI 3.1 spec builder for KotaDB API.
+ * 
+ * Generates complete OpenAPI specification document with:
+ * - Info section (title, version, description)
+ * - Server definitions (production, staging, local)
+ * - Security schemes (API key, JWT bearer)
+ * - Path operations from paths.ts
+ * - Component schemas from schemas.ts
+ */
+
+import { OpenAPIRegistry, OpenApiGeneratorV31 } from '@asteasolutions/zod-to-openapi';
+import { registerPaths } from './paths.js';
+
+// Cache for pre-computed spec
+let cachedSpec: unknown | null = null;
+
+/**
+ * Build complete OpenAPI 3.1 specification document
+ */
+export function buildOpenAPISpec(): unknown {
+	// Return cached spec if available
+	if (cachedSpec) {
+		return cachedSpec;
+	}
+
+	const startTime = Date.now();
+
+	// Create registry
+	const registry = new OpenAPIRegistry();
+
+	// Register security schemes
+	registry.registerComponent('securitySchemes', 'apiKey', {
+		type: 'http',
+		scheme: 'bearer',
+		bearerFormat: 'API Key',
+		description: 'API key authentication using Bearer token. Format: `kota_<tier>_<prefix>_<secret>`. Example: `kota_free_key123_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`',
+	});
+
+	registry.registerComponent('securitySchemes', 'bearerAuth', {
+		type: 'http',
+		scheme: 'bearer',
+		bearerFormat: 'JWT',
+		description: 'JWT bearer token authentication. Obtained from Supabase Auth.',
+	});
+
+	// Register all path operations
+	registerPaths(registry);
+
+	// Generate OpenAPI spec
+	const generator = new OpenApiGeneratorV31(registry.definitions);
+	
+	const spec = generator.generateDocument({
+		openapi: '3.1.0',
+		info: {
+			title: 'KotaDB API',
+			version: '0.1.0', // Match package.json version
+			description: `
+# KotaDB API Documentation
+
+KotaDB provides a code intelligence API for indexing, searching, and analyzing code repositories.
+
+## Authentication
+
+KotaDB supports two authentication methods:
+
+### 1. API Key Authentication (Recommended for SDKs)
+
+Use Bearer token format with your API key:
+
+\`\`\`
+Authorization: Bearer kota_free_key123_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+\`\`\`
+
+API keys can be generated via the \`POST /api/keys/generate\` endpoint (requires JWT authentication first).
+
+### 2. JWT Bearer Token (For web applications)
+
+Use Supabase Auth JWT tokens:
+
+\`\`\`
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+\`\`\`
+
+## Rate Limiting
+
+All authenticated endpoints are rate-limited with dual limits enforced:
+
+- **Hourly limit**: 100 requests/hour (free tier)
+- **Daily limit**: 1000 requests/day (free tier)
+
+Both limits are checked on each request. Whichever limit is reached first will block the request.
+
+Rate limit headers are included in all authenticated endpoint responses:
+
+- \`X-RateLimit-Limit\`: Hourly threshold for the tier
+- \`X-RateLimit-Remaining\`: Remaining requests (minimum of hourly and daily remaining)
+- \`X-RateLimit-Reset\`: Unix timestamp when the hourly limit resets
+
+When rate limit is exceeded, the API returns HTTP 429 with a \`Retry-After\` header indicating seconds until the limit resets.
+
+## Error Responses
+
+All error responses follow a consistent format:
+
+\`\`\`json
+{
+  "error": "Error message",
+  "details": { /* optional additional context */ }
+}
+\`\`\`
+
+Common HTTP status codes:
+
+- \`400\`: Invalid request parameters
+- \`401\`: Unauthorized (missing/invalid authentication)
+- \`404\`: Resource not found
+- \`429\`: Rate limit exceeded
+- \`500\`: Internal server error
+
+## Endpoints Overview
+
+- **Health**: Service availability check
+- **Indexing**: Trigger repository indexing jobs
+- **Jobs**: Track indexing job status and progress
+- **Search**: Search indexed code content
+- **Files**: Retrieve recently indexed files
+- **Projects**: Manage multi-repository projects
+- **API Keys**: Generate and manage API keys
+
+			`.trim(),
+			contact: {
+				name: 'KotaDB Support',
+				url: 'https://kotadb.com/support',
+			},
+			license: {
+				identifier: 'LicenseRef-Proprietary',
+				name: 'Proprietary',
+			},
+		},
+		servers: [
+			{
+				url: 'https://api.kotadb.com',
+				description: 'Production server',
+			},
+			{
+				url: 'https://staging-api.kotadb.com',
+				description: 'Staging server',
+			},
+			{
+				url: 'http://localhost:3001',
+				description: 'Local development server',
+			},
+		],
+		tags: [
+			{
+				name: 'Health',
+				description: 'Service health and status endpoints',
+			},
+			{
+				name: 'Indexing',
+				description: 'Repository indexing operations',
+			},
+			{
+				name: 'Jobs',
+				description: 'Indexing job status and tracking',
+			},
+			{
+				name: 'Search',
+				description: 'Code search operations',
+			},
+			{
+				name: 'Files',
+				description: 'File listing and retrieval',
+			},
+			{
+				name: 'Projects',
+				description: 'Multi-repository project management',
+			},
+			{
+				name: 'API Keys',
+				description: 'API key generation and management',
+			},
+		],
+	});
+
+	const duration = Date.now() - startTime;
+	const pathCount = Object.keys(spec.paths || {}).length;
+
+	process.stdout.write(JSON.stringify({
+		level: 'info',
+		module: 'openapi-builder',
+		message: 'OpenAPI spec generated',
+		duration_ms: duration,
+		path_count: pathCount,
+	}) + '\n');
+
+	// Cache the spec
+	cachedSpec = spec;
+
+	return spec;
+}
+
+/**
+ * Clear cached spec (for testing or hot reload)
+ */
+export function clearSpecCache(): void {
+	cachedSpec = null;
+}