@side-quest/kit 0.0.0 → 0.2.0

package/src/lib/commands/prime.ts

@@ -0,0 +1,271 @@
+/**
+ * Prime command - Generate or refresh PROJECT_INDEX.json
+ *
+ * Migrated from prime-reporter.ts to integrate with kit-index CLI.
+ * Supports dual output formats (markdown with colors, or JSON).
+ */
+
+import { join } from 'node:path'
+import { getFileAgeHours, getFileSizeMB } from '@side-quest/core/fs'
+import {
+	ensureCommandAvailable,
+	spawnWithTimeout,
+} from '@side-quest/core/spawn'
+import { color, OutputFormat } from '../formatters/output'
+import { getTargetDir, INDEX_FILE, MAX_AGE_HOURS } from '../utils/git.js'
+
+interface IndexStats {
+	files: number
+	symbols: number
+	hasTree: boolean
+}
+
+/**
+ * Parse index stats from PROJECT_INDEX.json
+ */
+async function parseIndexStats(indexPath: string): Promise<IndexStats> {
+	const file = Bun.file(indexPath)
+	const json = (await file.json()) as {
+		files: unknown[]
+		symbols: Record<string, unknown[]>
+		file_tree?: unknown
+	}
+
+	const symbolCount = Object.values(json.symbols).reduce(
+		(sum, arr) => sum + arr.length,
+		0,
+	)
+
+	return {
+		files: json.files.length,
+		symbols: symbolCount,
+		hasTree: json.file_tree !== undefined,
+	}
+}
+
+/**
+ * Generate the index using kit CLI
+ */
+async function generateIndex(
+	targetDir: string,
+	indexPath: string,
+): Promise<{ durationSec: number }> {
+	const kitCmd = ensureCommandAvailable('kit')
+	const startTime = Date.now()
+	const result = await spawnWithTimeout(
+		[kitCmd, 'index', targetDir, '-o', indexPath],
+		60_000,
+	)
+
+	if (result.timedOut) {
+		throw new Error('kit index timed out')
+	}
+
+	if (result.exitCode !== 0) {
+		throw new Error(`kit index failed: ${result.stderr}`)
+	}
+
+	const durationSec = (Date.now() - startTime) / 1000
+	return { durationSec }
+}
+
+/**
+ * Report existing index (markdown format)
+ */
+async function reportExistingMarkdown(
+	ageHours: number,
+	indexPath: string,
+	targetDir: string,
+): Promise<void> {
+	const stats = await parseIndexStats(indexPath)
+	const size = getFileSizeMB(indexPath)
+
+	console.log(color('cyan', '\n📊 PROJECT_INDEX.json exists\n'))
+	console.log(color('dim', `Location: ${targetDir}`))
+	console.log(color('dim', `Age: ${ageHours.toFixed(1)} hours`))
+	console.log(color('dim', `Files: ${stats.files}`))
+	console.log(color('dim', `Symbols: ${stats.symbols}`))
+	console.log(color('dim', `Size: ${size} MB`))
+	console.log(
+		color(
+			'yellow',
+			'\n⚠️  Index is less than 24 hours old. Use --force to regenerate.',
+		),
+	)
+}
+
+/**
+ * Report existing index (JSON format)
+ */
+async function reportExistingJSON(
+	ageHours: number,
+	indexPath: string,
+	targetDir: string,
+): Promise<void> {
+	const stats = await parseIndexStats(indexPath)
+	const sizeMB = getFileSizeMB(indexPath)
+
+	console.log(
+		JSON.stringify(
+			{
+				status: 'exists',
+				location: targetDir,
+				ageHours: Number.parseFloat(ageHours.toFixed(1)),
+				files: stats.files,
+				symbols: stats.symbols,
+				size: `${sizeMB} MB`,
+				message: 'Index is less than 24 hours old. Use --force to regenerate.',
+			},
+			null,
+			2,
+		),
+	)
+}
+
+/**
+ * Report successful generation (markdown format)
+ */
+async function reportSuccessMarkdown(
+	durationSec: number,
+	indexPath: string,
+	targetDir: string,
+): Promise<void> {
+	const stats = await parseIndexStats(indexPath)
+	const sizeMB = getFileSizeMB(indexPath)
+
+	console.log(
+		color('green', '\n✅ PROJECT_INDEX.json generated successfully\n'),
+	)
+
+	console.log(color('cyan', 'Stats:'))
+	console.log(`  ${color('dim', '•')} Location: ${color('blue', targetDir)}`)
+	console.log(
+		`  ${color('dim', '•')} Files indexed: ${color('blue', stats.files.toString())}`,
+	)
+	console.log(
+		`  ${color('dim', '•')} Symbols extracted: ${color('blue', stats.symbols.toString())}`,
+	)
+	console.log(
+		`  ${color('dim', '•')} Index size: ${color('blue', `${sizeMB} MB`)}`,
+	)
+	console.log(
+		`  ${color('dim', '•')} Time taken: ${color('blue', `${durationSec.toFixed(1)}s`)}`,
+	)
+
+	console.log(color('cyan', '\nYou can now use:'))
+	console.log(
+		`  ${color('dim', '•')} ${color('magenta', 'bun run src/cli.ts find <symbol>')} - Find symbol definitions`,
+	)
+	console.log(
+		`  ${color('dim', '•')} ${color('magenta', 'bun run src/cli.ts callers <fn>')} - Find who calls a function`,
+	)
+	console.log(
+		`  ${color('dim', '•')} ${color('magenta', 'bun run src/cli.ts overview <file>')} - Get file symbol summary`,
+	)
+	console.log(
+		`  ${color('dim', '•')} ${color('magenta', 'bun run src/cli.ts stats')} - Codebase overview`,
+	)
+}
+
+/**
+ * Report successful generation (JSON format)
+ */
+async function reportSuccessJSON(
+	durationSec: number,
+	indexPath: string,
+	targetDir: string,
+): Promise<void> {
+	const stats = await parseIndexStats(indexPath)
+	const sizeMB = getFileSizeMB(indexPath)
+
+	console.log(
+		JSON.stringify(
+			{
+				success: true,
+				location: targetDir,
+				stats: {
+					files: stats.files,
+					symbols: stats.symbols,
+					hasTree: stats.hasTree,
+					size: `${sizeMB} MB`,
+					durationSec: Number.parseFloat(durationSec.toFixed(1)),
+				},
+			},
+			null,
+			2,
+		),
+	)
+}
+
+/**
+ * Execute prime command
+ *
+ * @param force - Force regenerate even if index is fresh
+ * @param format - Output format (markdown or JSON)
+ * @param customPath - Optional custom path to index (defaults to git root or CWD)
+ */
+export async function executePrime(
+	force: boolean,
+	format: OutputFormat,
+	customPath?: string,
+): Promise<void> {
+	try {
+		// Determine target directory and index path
+		const targetDir = await getTargetDir(customPath)
+		const indexPath = join(targetDir, INDEX_FILE)
+
+		const ageHours = getFileAgeHours(indexPath)
+
+		// Check if index exists and is fresh
+		if (ageHours !== null && ageHours <= MAX_AGE_HOURS && !force) {
+			if (format === OutputFormat.JSON) {
+				await reportExistingJSON(ageHours, indexPath, targetDir)
+			} else {
+				await reportExistingMarkdown(ageHours, indexPath, targetDir)
+			}
+			return
+		}
+
+		// Generate progress indicator (markdown only)
+		if (format === OutputFormat.MARKDOWN) {
+			console.log(color('blue', '▶ Generating index...'))
+		}
+
+		// Generate new index
+		const { durationSec } = await generateIndex(targetDir, indexPath)
+
+		// Report success
+		if (format === OutputFormat.JSON) {
+			await reportSuccessJSON(durationSec, indexPath, targetDir)
+		} else {
+			await reportSuccessMarkdown(durationSec, indexPath, targetDir)
+		}
+	} catch (error) {
+		if (format === OutputFormat.JSON) {
+			console.error(
+				JSON.stringify(
+					{
+						error: error instanceof Error ? error.message : 'Unknown error',
+						isError: true,
+					},
+					null,
+					2,
+				),
+			)
+		} else {
+			console.error(color('red', '\n❌ Error:'), error)
+
+			// Check if kit is installed
+			try {
+				ensureCommandAvailable('kit')
+			} catch {
+				console.error(color('yellow', '\n💡 Kit CLI not found. Install with:'))
+				console.error(color('dim', '  uv tool install cased-kit'))
+				console.error(color('dim', '  # or'))
+				console.error(color('dim', '  pipx install cased-kit'))
+			}
+		}
+
+		process.exit(1)
+	}
+}

package/src/lib/commands/search.ts

@@ -0,0 +1,146 @@
+/**
+ * Semantic search command - Natural language code search
+ *
+ * Uses kit semantic search to find code by meaning rather than exact text.
+ * Gracefully falls back to grep if ML dependencies unavailable.
+ */
+
+import { color, OutputFormat } from '../formatters/output'
+import { executeKitSemantic } from '../kit-wrapper'
+import type { SemanticMatch, SemanticOptions, SemanticResult } from '../types'
+
+/**
+ * Execute semantic search command
+ *
+ * Performs natural language search over codebase using vector embeddings.
+ * Shows warning with install instructions if semantic unavailable.
+ *
+ * @param query - Natural language search query
+ * @param options - Search options (path, topK, chunkBy, buildIndex)
+ * @param format - Output format (markdown or JSON)
+ */
+export async function executeSearch(
+	query: string,
+	options: Omit<SemanticOptions, 'query'>,
+	format: OutputFormat,
+): Promise<void> {
+	try {
+		// Execute semantic search
+		const result = executeKitSemantic({ query, ...options })
+
+		// Handle errors
+		if ('error' in result) {
+			if (format === OutputFormat.JSON) {
+				console.error(
+					JSON.stringify(
+						{
+							error: result.error,
+							query,
+							isError: true,
+						},
+						null,
+						2,
+					),
+				)
+			} else {
+				console.error(color('red', '\n❌ Error:'), result.error, '\n')
+
+				// Show install hint if semantic unavailable
+				if ('hint' in result && result.hint) {
+					console.error(color('yellow', '💡 Tip:'), result.hint, '\n')
+				}
+			}
+			process.exit(1)
+		}
+
+		// Show fallback warning if grep was used
+		if (result.fallback && format === OutputFormat.MARKDOWN) {
+			console.log(
+				color(
+					'yellow',
+					'\n⚠️  Semantic search unavailable - using grep fallback\n',
+				),
+			)
+			if (result.installHint) {
+				console.log(color('dim', result.installHint), '\n')
+			}
+		}
+
+		// Output results
+		if (format === OutputFormat.JSON) {
+			console.log(JSON.stringify(result, null, 2))
+		} else {
+			console.log(formatMarkdown(result))
+		}
+	} catch (error) {
+		if (format === OutputFormat.JSON) {
+			console.error(
+				JSON.stringify(
+					{
+						error: error instanceof Error ? error.message : 'Unknown error',
+						query,
+						isError: true,
+					},
+					null,
+					2,
+				),
+			)
+		} else {
+			console.error(
+				color('red', '\n❌ Error:'),
+				error instanceof Error ? error.message : error,
+				'\n',
+			)
+		}
+		process.exit(1)
+	}
+}
+
+/**
+ * Format semantic results as markdown
+ */
+function formatMarkdown(result: SemanticResult): string {
+	const { query, count, matches, fallback } = result
+
+	if (count === 0) {
+		return color('yellow', `\n⚠️  No matches found for query: "${query}"\n`)
+	}
+
+	let output = color('cyan', `\n🔍 Found ${count} semantic match(es) for: `)
+	output += color('blue', `"${query}"`)
+	if (fallback) {
+		output += color('dim', ' (grep fallback)')
+	}
+	output += '\n\n'
+
+	// Group by file
+	const byFile = new Map<string, SemanticMatch[]>()
+	for (const match of matches) {
+		if (!byFile.has(match.file)) {
+			byFile.set(match.file, [])
+		}
+		byFile.get(match.file)?.push(match)
+	}
+
+	// Output each file's matches
+	for (const [file, fileMatches] of byFile.entries()) {
+		output += color('dim', `${file}:\n`)
+		for (const match of fileMatches) {
+			const lineInfo = match.startLine
+				? `L${match.startLine}${match.endLine ? `-${match.endLine}` : ''}`
+				: ''
+			const scoreStr = `(${(match.score * 100).toFixed(1)}%)`
+
+			output += `  ${color('dim', lineInfo)} ${color('green', scoreStr)}\n`
+
+			// Show chunk preview (first 2 lines max)
+			const lines = match.chunk.split('\n').slice(0, 2)
+			for (const line of lines) {
+				output += `    ${color('dim', line.trim())}\n`
+			}
+			output += '\n'
+		}
+	}
+
+	return output
+}

package/src/lib/errors.ts

@@ -0,0 +1,221 @@
+/**
+ * Kit Plugin Error Taxonomy
+ *
+ * Comprehensive error handling with clear recovery instructions.
+ */
+
+import {
+	detectErrorFromOutput as coreDetectErrorFromOutput,
+	type ErrorPattern,
+	isTimeoutOutput,
+	PluginError,
+} from '@side-quest/core/instrumentation'
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Kit error types with associated recovery strategies.
+ */
+export enum KitErrorType {
+	/** Kit CLI not found in PATH */
+	KitNotInstalled = 'KitNotInstalled',
+	/** Invalid repository path */
+	InvalidPath = 'InvalidPath',
+	/** Invalid input (regex, glob, etc.) */
+	InvalidInput = 'InvalidInput',
+	/** Semantic search not available (missing ML deps) */
+	SemanticNotAvailable = 'SemanticNotAvailable',
+	/** Semantic search index not yet built for repository */
+	SemanticIndexNotBuilt = 'SemanticIndexNotBuilt',
+	/** Too many results returned */
+	TooManyResults = 'TooManyResults',
+	/** Kit command failed */
+	KitCommandFailed = 'KitCommandFailed',
+	/** Failed to parse Kit output */
+	OutputParseError = 'OutputParseError',
+	/** Operation timed out */
+	Timeout = 'Timeout',
+}
+
+// ============================================================================
+// Error Messages & Recovery Hints
+// ============================================================================
+
+/**
+ * User-facing error messages with recovery hints.
+ */
+export const ERROR_MESSAGES: Record<
+	KitErrorType,
+	{ message: string; hint: string }
+> = {
+	[KitErrorType.KitNotInstalled]: {
+		message: 'Kit CLI is not installed or not found in PATH.',
+		hint: 'Install Kit with: uv tool install cased-kit',
+	},
+	[KitErrorType.InvalidPath]: {
+		message: 'The specified path does not exist or is not accessible.',
+		hint: 'Check the path exists and you have read permissions.',
+	},
+	[KitErrorType.InvalidInput]: {
+		message: 'Invalid input provided.',
+		hint: 'Check your search pattern or options for syntax errors.',
+	},
+	[KitErrorType.SemanticNotAvailable]: {
+		message: 'Semantic search is not available.',
+		hint: `Install ML dependencies: pip install 'cased-kit[ml]' or uv tool install 'cased-kit[ml]'`,
+	},
+	[KitErrorType.SemanticIndexNotBuilt]: {
+		message: 'Vector index has not been built for this repository yet.',
+		hint: 'Build it by running the CLI command provided in the error details. After building (one-time), semantic search will be fast and cached.',
+	},
+	[KitErrorType.TooManyResults]: {
+		message: 'Query returned too many results.',
+		hint: 'Try a more specific query or use --max-results to limit output.',
+	},
+	[KitErrorType.KitCommandFailed]: {
+		message: 'Kit command failed to execute.',
+		hint: 'Check the error details below for more information.',
+	},
+	[KitErrorType.OutputParseError]: {
+		message: 'Failed to parse Kit output.',
+		hint: 'This may be a bug. Check logs for details.',
+	},
+	[KitErrorType.Timeout]: {
+		message:
+			'Operation timed out (this may take longer on large repositories).',
+		hint: 'Try again—the vector index will be cached. If it times out again, clear .kit/vector_db and rebuild with build_index: true.',
+	},
+}
+
+// ============================================================================
+// Error Class
+// ============================================================================
+
+/**
+ * Custom error class for Kit operations.
+ *
+ * Extends PluginError to provide Kit-specific error handling with:
+ * - Typed error classification (KitErrorType enum)
+ * - User-friendly messages with recovery hints
+ * - Structured JSON serialization for MCP responses
+ */
+export class KitError extends PluginError<KitErrorType> {
+	constructor(type: KitErrorType, details?: string, stderr?: string) {
+		const errorInfo = ERROR_MESSAGES[type]
+		super('KitError', type, errorInfo.message, errorInfo.hint, details, stderr)
+	}
+}
+
+// ============================================================================
+// Semantic Search Fallback
+// ============================================================================
+
+/**
+ * Install hint shown when semantic search is unavailable.
+ */
+export const SEMANTIC_INSTALL_HINT = `
+Semantic search is not available. Using text search instead.
+
+To enable semantic search, install the ML dependencies:
+  pip install 'cased-kit[ml]'
+
+Or if using uv:
+  uv tool install 'cased-kit[ml]'
+`.trim()
+
+/**
+ * Check if an error indicates semantic search is unavailable.
+ * @param stderr - Standard error output from Kit
+ */
+export function isSemanticUnavailableError(stderr: string): boolean {
+	const patterns = [
+		'sentence-transformers',
+		'chromadb',
+		'semantic search',
+		'vector index',
+		'embedding',
+	]
+	const lowerStderr = stderr.toLowerCase()
+	return patterns.some((p) => lowerStderr.includes(p))
+}
+
+/**
+ * Check if an error indicates a timeout occurred.
+ *
+ * Re-exports the core utility for backward compatibility.
+ *
+ * @param stderr - Standard error output
+ */
+export const isTimeoutError = isTimeoutOutput
+
+// ============================================================================
+// Error Detection Helpers
+// ============================================================================
+
+/**
+ * Kit-specific error patterns for subprocess output detection.
+ *
+ * These patterns are tested in order by detectErrorType().
+ */
+const KIT_ERROR_PATTERNS: ErrorPattern<KitErrorType>[] = [
+	// Semantic search unavailable (must be first - most specific)
+	{
+		type: KitErrorType.SemanticNotAvailable,
+		patterns: [
+			'sentence-transformers',
+			'chromadb',
+			'semantic search',
+			'vector index',
+			'embedding',
+		],
+	},
+	// Path errors
+	{
+		type: KitErrorType.InvalidPath,
+		patterns: ['no such file', 'not found', 'does not exist'],
+	},
+	// Timeout errors
+	{
+		type: KitErrorType.Timeout,
+		patterns: ['timeout', 'timed out', 'etimedout'],
+	},
+	// Too many results
+	{
+		type: KitErrorType.TooManyResults,
+		patterns: ['too many', 'limit'],
+	},
+]
+
+/**
+ * Detect error type from Kit stderr output.
+ *
+ * Uses the generic core pattern matcher with Kit-specific patterns.
+ *
+ * @param stderr - Standard error output from Kit
+ * @param _exitCode - Exit code from Kit process (currently unused)
+ */
+export function detectErrorType(
+	stderr: string,
+	_exitCode: number,
+): KitErrorType {
+	return coreDetectErrorFromOutput(
+		stderr,
+		KIT_ERROR_PATTERNS,
+		KitErrorType.KitCommandFailed, // Default
+	)
+}
+
+/**
+ * Create a KitError from process output.
+ * @param stderr - Standard error output
+ * @param exitCode - Process exit code
+ */
+export function createErrorFromOutput(
+	stderr: string,
+	exitCode: number,
+): KitError {
+	const errorType = detectErrorType(stderr, exitCode)
+	return new KitError(errorType, undefined, stderr.trim())
+}

package/src/lib/formatters/output.ts

@@ -0,0 +1,9 @@
+/**
+ * Output format enum
+ */
+export {
+	color,
+	colors,
+	OutputFormat,
+	parseOutputFormat,
+} from '@side-quest/core/formatters'