@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/handlers/findings.ts

@@ -1,239 +1,239 @@
-/**
- * Findings Handlers
- *
- * Handles audit findings and knowledge base:
- * - add_finding
- * - get_findings (supports summary_only for reduced tokens)
- * - get_findings_stats (aggregate counts for minimal tokens)
- * - update_finding
- * - delete_finding
- */
-
-import type { Handler, HandlerRegistry } from './types.js';
-import { success, error } from './types.js';
-import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
-import { getApiClient } from '../api-client.js';
-
-const VALID_FINDING_CATEGORIES = ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'] as const;
-const VALID_FINDING_SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'] as const;
-const VALID_FINDING_STATUSES = ['open', 'in_development', 'implemented', 'addressed', 'dismissed', 'wontfix'] as const;
-
-type FindingCategory = typeof VALID_FINDING_CATEGORIES[number];
-type FindingSeverity = typeof VALID_FINDING_SEVERITIES[number];
-type FindingStatus = typeof VALID_FINDING_STATUSES[number];
-
-// Argument schemas for type-safe parsing
-const addFindingSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const, required: true as const },
-	description: { type: 'string' as const },
-	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
-	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
-	file_path: { type: 'string' as const },
-	line_number: { type: 'number' as const },
-	related_task_id: { type: 'string' as const, validate: uuidValidator },
-};
-
-const getFindingSchema = {
-	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const getFindingsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
-	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
-	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
-	limit: { type: 'number' as const, default: 10 },
-	offset: { type: 'number' as const, default: 0 },
-	search_query: { type: 'string' as const },
-	summary_only: { type: 'boolean' as const, default: true },
-};
-
-const getFindingsStatsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const updateFindingSchema = {
-	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	title: { type: 'string' as const },
-	description: { type: 'string' as const },
-	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
-	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
-	resolution_note: { type: 'string' as const },
-};
-
-const deleteFindingSchema = {
-	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const VALID_SCOPES = ['summary', 'detailed'] as const;
-
-const queryKnowledgeBaseSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	scope: { type: 'string' as const, default: 'summary', validate: createEnumValidator(VALID_SCOPES) },
-	categories: { type: 'array' as const },
-	limit: { type: 'number' as const, default: 5 },
-	search_query: { type: 'string' as const },
-};
-
-export const addFinding: Handler = async (args, ctx) => {
-	const { project_id, title, description, category, severity, file_path, line_number, related_task_id } = parseArgs(args, addFindingSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.addFinding(project_id, {
-		title,
-		description,
-		category: category as FindingCategory | undefined,
-		severity: severity as FindingSeverity | undefined,
-		file_path,
-		line_number,
-		related_task_id
-	}, ctx.session.currentSessionId || undefined);
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to add finding');
-	}
-
-	return success(response.data);
-};
-
-/**
- * Get a single finding by ID.
- * More token-efficient than get_findings when you need details for a specific finding.
- */
-export const getFinding: Handler = async (args, _ctx) => {
-	const { finding_id } = parseArgs(args, getFindingSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.proxy<{
-		finding: {
-			id: string;
-			title: string;
-			description?: string;
-			category: string;
-			severity: string;
-			status: string;
-			file_path?: string;
-			line_number?: number;
-			resolution_note?: string;
-			created_at: string;
-			updated_at: string;
-		};
-	}>('get_finding', { finding_id });
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to get finding');
-	}
-
-	return success(response.data);
-};
-
-export const getFindings: Handler = async (args, _ctx) => {
-	const { project_id, category, severity, status, limit, offset, search_query, summary_only } = parseArgs(args, getFindingsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getFindings(project_id, {
-		category: category as FindingCategory | undefined,
-		severity: severity as FindingSeverity | undefined,
-		status: status as FindingStatus | undefined,
-		limit,
-		offset,
-		search_query,
-		summary_only
-	});
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to get findings');
-	}
-
-	return success(response.data);
-};
-
-/**
- * Get aggregate statistics about findings for a project.
- * Returns counts by category, severity, and status without the actual finding data.
- * This is much more token-efficient than get_findings for understanding the overall state.
- */
-export const getFindingsStats: Handler = async (args, _ctx) => {
-	const { project_id } = parseArgs(args, getFindingsStatsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getFindingsStats(project_id);
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to get findings stats');
-	}
-
-	return success(response.data);
-};
-
-export const updateFinding: Handler = async (args, _ctx) => {
-	const { finding_id, title, description, severity, status, resolution_note } = parseArgs(args, updateFindingSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.updateFinding(finding_id, {
-		title,
-		description,
-		severity: severity as FindingSeverity | undefined,
-		status: status as FindingStatus | undefined,
-		resolution_note
-	});
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to update finding');
-	}
-
-	return success(response.data);
-};
-
-export const deleteFinding: Handler = async (args, _ctx) => {
-	const { finding_id } = parseArgs(args, deleteFindingSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.deleteFinding(finding_id);
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to delete finding');
-	}
-
-	return success(response.data);
-};
-
-/**
- * Query aggregated project knowledge in a single call.
- * Returns findings, Q&A, decisions, completed tasks, and resolved blockers.
- * Use this instead of multiple separate tool calls to reduce token usage.
- */
-export const queryKnowledgeBase: Handler = async (args, _ctx) => {
-	const { project_id, scope, categories, limit, search_query } = parseArgs(args, queryKnowledgeBaseSchema);
-
-	// Validate limit range
-	const effectiveLimit = Math.min(Math.max(1, limit ?? 5), 20);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.queryKnowledgeBase(project_id, {
-		scope: scope as 'summary' | 'detailed' | undefined,
-		categories: categories as string[] | undefined,
-		limit: effectiveLimit,
-		search_query
-	});
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to query knowledge base');
-	}
-
-	return success(response.data);
-};
-
-/**
- * Findings handlers registry
- */
-export const findingHandlers: HandlerRegistry = {
-	add_finding: addFinding,
-	get_finding: getFinding,
-	get_findings: getFindings,
-	get_findings_stats: getFindingsStats,
-	update_finding: updateFinding,
-	delete_finding: deleteFinding,
-	query_knowledge_base: queryKnowledgeBase,
-};
+/**
+ * Findings Handlers
+ *
+ * Handles audit findings and knowledge base:
+ * - add_finding
+ * - get_findings (supports summary_only for reduced tokens)
+ * - get_findings_stats (aggregate counts for minimal tokens)
+ * - update_finding
+ * - delete_finding
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { success, error } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const VALID_FINDING_CATEGORIES = ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'] as const;
+const VALID_FINDING_SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'] as const;
+const VALID_FINDING_STATUSES = ['open', 'in_development', 'implemented', 'addressed', 'dismissed', 'wontfix'] as const;
+
+type FindingCategory = typeof VALID_FINDING_CATEGORIES[number];
+type FindingSeverity = typeof VALID_FINDING_SEVERITIES[number];
+type FindingStatus = typeof VALID_FINDING_STATUSES[number];
+
+// Argument schemas for type-safe parsing
+const addFindingSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	file_path: { type: 'string' as const },
+	line_number: { type: 'number' as const },
+	related_task_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const getFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const getFindingsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	limit: { type: 'number' as const, default: 10 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+	summary_only: { type: 'boolean' as const, default: true },
+};
+
+const getFindingsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const updateFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	resolution_note: { type: 'string' as const },
+};
+
+const deleteFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const VALID_SCOPES = ['summary', 'detailed'] as const;
+
+const queryKnowledgeBaseSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	scope: { type: 'string' as const, default: 'summary', validate: createEnumValidator(VALID_SCOPES) },
+	categories: { type: 'array' as const },
+	limit: { type: 'number' as const, default: 5 },
+	search_query: { type: 'string' as const },
+};
+
+export const addFinding: Handler = async (args, ctx) => {
+	const { project_id, title, description, category, severity, file_path, line_number, related_task_id } = parseArgs(args, addFindingSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.addFinding(project_id, {
+		title,
+		description,
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
+		file_path,
+		line_number,
+		related_task_id
+	}, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to add finding');
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Get a single finding by ID.
+ * More token-efficient than get_findings when you need details for a specific finding.
+ */
+export const getFinding: Handler = async (args, _ctx) => {
+	const { finding_id } = parseArgs(args, getFindingSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		finding: {
+			id: string;
+			title: string;
+			description?: string;
+			category: string;
+			severity: string;
+			status: string;
+			file_path?: string;
+			line_number?: number;
+			resolution_note?: string;
+			created_at: string;
+			updated_at: string;
+		};
+	}>('get_finding', { finding_id });
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to get finding');
+	}
+
+	return success(response.data);
+};
+
+export const getFindings: Handler = async (args, _ctx) => {
+	const { project_id, category, severity, status, limit, offset, search_query, summary_only } = parseArgs(args, getFindingsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFindings(project_id, {
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
+		limit,
+		offset,
+		search_query,
+		summary_only
+	});
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to get findings');
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Get aggregate statistics about findings for a project.
+ * Returns counts by category, severity, and status without the actual finding data.
+ * This is much more token-efficient than get_findings for understanding the overall state.
+ */
+export const getFindingsStats: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getFindingsStatsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFindingsStats(project_id);
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to get findings stats');
+	}
+
+	return success(response.data);
+};
+
+export const updateFinding: Handler = async (args, _ctx) => {
+	const { finding_id, title, description, severity, status, resolution_note } = parseArgs(args, updateFindingSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.updateFinding(finding_id, {
+		title,
+		description,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
+		resolution_note
+	});
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to update finding');
+	}
+
+	return success(response.data);
+};
+
+export const deleteFinding: Handler = async (args, _ctx) => {
+	const { finding_id } = parseArgs(args, deleteFindingSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.deleteFinding(finding_id);
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to delete finding');
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Query aggregated project knowledge in a single call.
+ * Returns findings, Q&A, decisions, completed tasks, and resolved blockers.
+ * Use this instead of multiple separate tool calls to reduce token usage.
+ */
+export const queryKnowledgeBase: Handler = async (args, _ctx) => {
+	const { project_id, scope, categories, limit, search_query } = parseArgs(args, queryKnowledgeBaseSchema);
+
+	// Validate limit range
+	const effectiveLimit = Math.min(Math.max(1, limit ?? 5), 20);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.queryKnowledgeBase(project_id, {
+		scope: scope as 'summary' | 'detailed' | undefined,
+		categories: categories as string[] | undefined,
+		limit: effectiveLimit,
+		search_query
+	});
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to query knowledge base');
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Findings handlers registry
+ */
+export const findingHandlers: HandlerRegistry = {
+	add_finding: addFinding,
+	get_finding: getFinding,
+	get_findings: getFindings,
+	get_findings_stats: getFindingsStats,
+	update_finding: updateFinding,
+	delete_finding: deleteFinding,
+	query_knowledge_base: queryKnowledgeBase,
+};