@vibescope/mcp-server 0.2.0 → 0.2.1

package/dist/handlers/deployment.js

@@ -13,21 +13,103 @@
  * - complete_deployment_requirement
  * - get_deployment_requirements
  */
-import { ValidationError, validateRequired, validateUUID, validateEnvironment, } from '../validators.js';
+import { ValidationError, parseArgs, uuidValidator, createEnumValidator, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
+const ENVIRONMENTS = ['development', 'staging', 'production'];
+const VERSION_BUMPS = ['patch', 'minor', 'major'];
+const REQUIREMENT_TYPES = ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'];
+const REQUIREMENT_STAGES = ['preparation', 'deployment', 'verification'];
+const REQUIREMENT_STATUSES = ['pending', 'completed', 'converted_to_task', 'all'];
+const SCHEDULE_TYPES = ['once', 'daily', 'weekly', 'monthly'];
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+const requestDeploymentSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    environment: { type: 'string', default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
+    version_bump: { type: 'string', default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
+    notes: { type: 'string' },
+    git_ref: { type: 'string' },
+};
+const claimDeploymentValidationSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const reportValidationSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    build_passed: { type: 'boolean', required: true },
+    tests_passed: { type: 'boolean' },
+    error_message: { type: 'string' },
+};
+const checkDeploymentStatusSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const startDeploymentSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const completeDeploymentSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    success: { type: 'boolean', required: true },
+    summary: { type: 'string' },
+};
+const cancelDeploymentSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    reason: { type: 'string' },
+};
+const addDeploymentRequirementSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    type: { type: 'string', required: true, validate: createEnumValidator(REQUIREMENT_TYPES) },
+    title: { type: 'string', required: true },
+    description: { type: 'string' },
+    file_path: { type: 'string' },
+    stage: { type: 'string', default: 'preparation', validate: createEnumValidator(REQUIREMENT_STAGES) },
+    blocking: { type: 'boolean', default: false },
+    recurring: { type: 'boolean', default: false },
+};
+const completeDeploymentRequirementSchema = {
+    requirement_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const getDeploymentRequirementsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    status: { type: 'string', default: 'pending', validate: createEnumValidator(REQUIREMENT_STATUSES) },
+    stage: { type: 'string', validate: createEnumValidator([...REQUIREMENT_STAGES, 'all']) },
+};
+const scheduleDeploymentSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    environment: { type: 'string', default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
+    version_bump: { type: 'string', default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
+    schedule_type: { type: 'string', default: 'once', validate: createEnumValidator(SCHEDULE_TYPES) },
+    scheduled_at: { type: 'string', required: true },
+    auto_trigger: { type: 'boolean', default: true },
+    notes: { type: 'string' },
+    git_ref: { type: 'string' },
+};
+const getScheduledDeploymentsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    include_disabled: { type: 'boolean', default: false },
+};
+const updateScheduledDeploymentSchema = {
+    schedule_id: { type: 'string', required: true, validate: uuidValidator },
+    environment: { type: 'string', validate: createEnumValidator(ENVIRONMENTS) },
+    version_bump: { type: 'string', validate: createEnumValidator(VERSION_BUMPS) },
+    schedule_type: { type: 'string', validate: createEnumValidator(SCHEDULE_TYPES) },
+    scheduled_at: { type: 'string' },
+    auto_trigger: { type: 'boolean' },
+    enabled: { type: 'boolean' },
+    notes: { type: 'string' },
+    git_ref: { type: 'string' },
+};
+const deleteScheduledDeploymentSchema = {
+    schedule_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const triggerScheduledDeploymentSchema = {
+    schedule_id: { type: 'string', required: true, validate: uuidValidator },
+};
+const checkDueDeploymentsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
 export const requestDeployment = async (args, ctx) => {
-    const { project_id, environment = 'production', version_bump = 'patch', notes, git_ref } = args;
+    const { project_id, environment, version_bump, notes, git_ref } = parseArgs(args, requestDeploymentSchema);
     const { session } = ctx;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateEnvironment(environment);
-    if (version_bump && !['patch', 'minor', 'major'].includes(version_bump)) {
-        throw new ValidationError('Invalid version_bump value', {
-            field: 'version_bump',
-            validValues: ['patch', 'minor', 'major'],
-            hint: 'Must be one of: patch, minor, major',
-        });
-    }
     const apiClient = getApiClient();
     const response = await apiClient.requestDeployment(project_id, {
         environment,
@@ -41,10 +123,8 @@ export const requestDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const claimDeploymentValidation = async (args, ctx) => {
-    const { project_id } = args;
+    const { project_id } = parseArgs(args, claimDeploymentValidationSchema);
     const { session } = ctx;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
     const apiClient = getApiClient();
     const response = await apiClient.claimDeploymentValidation(project_id, session.currentSessionId || undefined);
     if (!response.ok) {
@@ -53,16 +133,8 @@ export const claimDeploymentValidation = async (args, ctx) => {
     return { result: response.data };
 };
 export const reportValidation = async (args, ctx) => {
-    const { project_id, build_passed, tests_passed, error_message } = args;
+    const { project_id, build_passed, tests_passed, error_message } = parseArgs(args, reportValidationSchema);
     const { session } = ctx;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    if (build_passed === undefined) {
-        throw new ValidationError('build_passed is required', {
-            field: 'build_passed',
-            hint: 'Set to true if the build succeeded, false otherwise',
-        });
-    }
     const apiClient = getApiClient();
     const response = await apiClient.reportValidation(project_id, {
         build_passed,
@@ -75,9 +147,7 @@ export const reportValidation = async (args, ctx) => {
     return { result: response.data };
 };
 export const checkDeploymentStatus = async (args, ctx) => {
-    const { project_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id } = parseArgs(args, checkDeploymentStatusSchema);
     const apiClient = getApiClient();
     const response = await apiClient.checkDeploymentStatus(project_id);
     if (!response.ok) {
@@ -86,10 +156,8 @@ export const checkDeploymentStatus = async (args, ctx) => {
     return { result: response.data };
 };
 export const startDeployment = async (args, ctx) => {
-    const { project_id } = args;
+    const { project_id } = parseArgs(args, startDeploymentSchema);
     const { session } = ctx;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
     const apiClient = getApiClient();
     const response = await apiClient.startDeployment(project_id, session.currentSessionId || undefined);
     if (!response.ok) {
@@ -98,16 +166,8 @@ export const startDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const completeDeployment = async (args, ctx) => {
-    const { project_id, success, summary } = args;
+    const { project_id, success, summary } = parseArgs(args, completeDeploymentSchema);
     const { session } = ctx;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    if (success === undefined) {
-        throw new ValidationError('success is required', {
-            field: 'success',
-            hint: 'Set to true if deployment succeeded, false otherwise',
-        });
-    }
     const apiClient = getApiClient();
     const response = await apiClient.completeDeployment(project_id, {
         success,
@@ -119,9 +179,7 @@ export const completeDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const cancelDeployment = async (args, ctx) => {
-    const { project_id, reason } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id, reason } = parseArgs(args, cancelDeploymentSchema);
     const apiClient = getApiClient();
     const response = await apiClient.cancelDeployment(project_id, reason);
     if (!response.ok) {
@@ -130,19 +188,7 @@ export const cancelDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const addDeploymentRequirement = async (args, ctx) => {
-    const { project_id, type, title, description, file_path, stage = 'preparation', blocking = false, recurring = false } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(type, 'type');
-    validateRequired(title, 'title');
-    const validTypes = ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'];
-    if (!validTypes.includes(type)) {
-        throw new ValidationError(`type must be one of: ${validTypes.join(', ')}`);
-    }
-    const validStages = ['preparation', 'deployment', 'verification'];
-    if (!validStages.includes(stage)) {
-        throw new ValidationError(`stage must be one of: ${validStages.join(', ')}`);
-    }
+    const { project_id, type, title, description, file_path, stage, blocking, recurring } = parseArgs(args, addDeploymentRequirementSchema);
     const apiClient = getApiClient();
     const response = await apiClient.addDeploymentRequirement(project_id, {
         type: type,
@@ -159,9 +205,7 @@ export const addDeploymentRequirement = async (args, ctx) => {
     return { result: response.data };
 };
 export const completeDeploymentRequirement = async (args, ctx) => {
-    const { requirement_id } = args;
-    validateRequired(requirement_id, 'requirement_id');
-    validateUUID(requirement_id, 'requirement_id');
+    const { requirement_id } = parseArgs(args, completeDeploymentRequirementSchema);
     const apiClient = getApiClient();
     const response = await apiClient.completeDeploymentRequirement(requirement_id);
     if (!response.ok) {
@@ -170,9 +214,7 @@ export const completeDeploymentRequirement = async (args, ctx) => {
     return { result: response.data };
 };
 export const getDeploymentRequirements = async (args, ctx) => {
-    const { project_id, status = 'pending', stage } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id, status, stage } = parseArgs(args, getDeploymentRequirementsSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getDeploymentRequirements(project_id, {
         status: status,
@@ -187,23 +229,7 @@ export const getDeploymentRequirements = async (args, ctx) => {
 // Scheduled Deployments
 // ============================================================================
 export const scheduleDeployment = async (args, ctx) => {
-    const { project_id, environment = 'production', version_bump = 'patch', schedule_type = 'once', scheduled_at, auto_trigger = true, notes, git_ref, } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(scheduled_at, 'scheduled_at');
-    validateEnvironment(environment);
-    if (!['patch', 'minor', 'major'].includes(version_bump)) {
-        throw new ValidationError('Invalid version_bump value', {
-            field: 'version_bump',
-            validValues: ['patch', 'minor', 'major'],
-        });
-    }
-    if (!['once', 'daily', 'weekly', 'monthly'].includes(schedule_type)) {
-        throw new ValidationError('Invalid schedule_type value', {
-            field: 'schedule_type',
-            validValues: ['once', 'daily', 'weekly', 'monthly'],
-        });
-    }
+    const { project_id, environment, version_bump, schedule_type, scheduled_at, auto_trigger, notes, git_ref, } = parseArgs(args, scheduleDeploymentSchema);
     // Parse and validate scheduled_at
     const scheduledDate = new Date(scheduled_at);
     if (isNaN(scheduledDate.getTime())) {
@@ -233,9 +259,7 @@ export const scheduleDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const getScheduledDeployments = async (args, ctx) => {
-    const { project_id, include_disabled = false } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id, include_disabled } = parseArgs(args, getScheduledDeploymentsSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getScheduledDeployments(project_id, include_disabled);
     if (!response.ok) {
@@ -244,26 +268,14 @@ export const getScheduledDeployments = async (args, ctx) => {
     return { result: response.data };
 };
 export const updateScheduledDeployment = async (args, ctx) => {
-    const { schedule_id, environment, version_bump, schedule_type, scheduled_at, auto_trigger, enabled, notes, git_ref, } = args;
-    validateRequired(schedule_id, 'schedule_id');
-    validateUUID(schedule_id, 'schedule_id');
+    const { schedule_id, environment, version_bump, schedule_type, scheduled_at, auto_trigger, enabled, notes, git_ref, } = parseArgs(args, updateScheduledDeploymentSchema);
     const updates = {};
-    if (environment !== undefined) {
-        validateEnvironment(environment);
+    if (environment !== undefined)
         updates.environment = environment;
-    }
-    if (version_bump !== undefined) {
-        if (!['patch', 'minor', 'major'].includes(version_bump)) {
-            throw new ValidationError('Invalid version_bump value');
-        }
+    if (version_bump !== undefined)
         updates.version_bump = version_bump;
-    }
-    if (schedule_type !== undefined) {
-        if (!['once', 'daily', 'weekly', 'monthly'].includes(schedule_type)) {
-            throw new ValidationError('Invalid schedule_type value');
-        }
+    if (schedule_type !== undefined)
         updates.schedule_type = schedule_type;
-    }
     if (scheduled_at !== undefined) {
         const scheduledDate = new Date(scheduled_at);
         if (isNaN(scheduledDate.getTime())) {
@@ -290,9 +302,7 @@ export const updateScheduledDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const deleteScheduledDeployment = async (args, ctx) => {
-    const { schedule_id } = args;
-    validateRequired(schedule_id, 'schedule_id');
-    validateUUID(schedule_id, 'schedule_id');
+    const { schedule_id } = parseArgs(args, deleteScheduledDeploymentSchema);
     const apiClient = getApiClient();
     const response = await apiClient.deleteScheduledDeployment(schedule_id);
     if (!response.ok) {
@@ -301,10 +311,8 @@ export const deleteScheduledDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const triggerScheduledDeployment = async (args, ctx) => {
-    const { schedule_id } = args;
+    const { schedule_id } = parseArgs(args, triggerScheduledDeploymentSchema);
     const { session } = ctx;
-    validateRequired(schedule_id, 'schedule_id');
-    validateUUID(schedule_id, 'schedule_id');
     const apiClient = getApiClient();
     const response = await apiClient.triggerScheduledDeployment(schedule_id, session.currentSessionId || undefined);
     if (!response.ok) {
@@ -313,9 +321,7 @@ export const triggerScheduledDeployment = async (args, ctx) => {
     return { result: response.data };
 };
 export const checkDueDeployments = async (args, ctx) => {
-    const { project_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id } = parseArgs(args, checkDueDeploymentsSchema);
     const apiClient = getApiClient();
     const response = await apiClient.checkDueDeployments(project_id);
     if (!response.ok) {

package/dist/handlers/discovery.js

@@ -8,6 +8,14 @@
  * Note: Tool documentation is lazy-loaded from tool-docs.ts to save tokens.
  * This saves ~8,000 tokens per schema load.
  */
+import { parseArgs } from '../validators.js';
+// Argument schemas for type-safe parsing
+const discoverToolsSchema = {
+    category: { type: 'string' },
+};
+const getToolInfoSchema = {
+    tool_name: { type: 'string', required: true },
+};
 // Lazy-loaded tool documentation cache
 let toolInfoCache = null;
 /**
@@ -163,6 +171,22 @@ const TOOL_CATEGORIES = {
             { name: 'activate_body_of_work', brief: 'Activate for work' },
         ],
     },
+    sprints: {
+        description: 'Time-bounded sprints with velocity tracking',
+        tools: [
+            { name: 'create_sprint', brief: 'Create new sprint' },
+            { name: 'update_sprint', brief: 'Update sprint details' },
+            { name: 'get_sprint', brief: 'Get sprint with tasks' },
+            { name: 'get_sprints', brief: 'List project sprints' },
+            { name: 'delete_sprint', brief: 'Delete sprint' },
+            { name: 'start_sprint', brief: 'Start sprint' },
+            { name: 'complete_sprint', brief: 'Complete sprint' },
+            { name: 'add_task_to_sprint', brief: 'Add task to sprint' },
+            { name: 'remove_task_from_sprint', brief: 'Remove from sprint' },
+            { name: 'get_sprint_backlog', brief: 'Get available tasks' },
+            { name: 'get_sprint_velocity', brief: 'Velocity metrics' },
+        ],
+    },
     requests: {
         description: 'User request handling',
         tools: [
@@ -200,6 +224,15 @@ const TOOL_CATEGORIES = {
             { name: 'get_task_costs', brief: 'Cost per task' },
         ],
     },
+    git_issues: {
+        description: 'Git conflict and issue tracking',
+        tools: [
+            { name: 'add_git_issue', brief: 'Record git issue' },
+            { name: 'resolve_git_issue', brief: 'Mark resolved' },
+            { name: 'get_git_issues', brief: 'List git issues' },
+            { name: 'delete_git_issue', brief: 'Delete git issue' },
+        ],
+    },
     knowledge: {
         description: 'Queryable knowledge base from project data',
         tools: [
@@ -208,7 +241,7 @@ const TOOL_CATEGORIES = {
     },
 };
 export const discoverTools = async (args) => {
-    const { category } = args;
+    const { category } = parseArgs(args, discoverToolsSchema);
     if (category) {
         // Return tools in specific category
         const cat = TOOL_CATEGORIES[category];
@@ -243,10 +276,7 @@ export const discoverTools = async (args) => {
     };
 };
 export const getToolInfo = async (args) => {
-    const { tool_name } = args;
-    if (!tool_name) {
-        return { result: { error: 'tool_name is required' } };
-    }
+    const { tool_name } = parseArgs(args, getToolInfoSchema);
     // Lazy-load tool documentation
     const toolDocs = await getToolDocs();
     const info = toolDocs[tool_name];

package/dist/handlers/fallback.js

@@ -9,7 +9,7 @@
  *
  * MIGRATED: Uses Vibescope API client instead of direct Supabase
  */
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { FALLBACK_ACTIVITIES } from '../utils.js';
 import { getApiClient } from '../api-client.js';
 const VALID_ACTIVITIES = [
@@ -24,14 +24,25 @@ const VALID_ACTIVITIES = [
     'dependency_audit',
     'validate_completed_tasks',
 ];
+// Argument schemas for type-safe parsing
+const startFallbackActivitySchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    activity: { type: 'string', required: true, validate: createEnumValidator(VALID_ACTIVITIES) },
+};
+const stopFallbackActivitySchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    summary: { type: 'string' },
+};
+const getActivityHistorySchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    activity_type: { type: 'string' },
+    limit: { type: 'number', default: 50 },
+};
+const getActivitySchedulesSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+};
 export const startFallbackActivity = async (args, ctx) => {
-    const { project_id, activity } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
-    validateRequired(activity, 'activity');
-    if (!VALID_ACTIVITIES.includes(activity)) {
-        throw new Error(`Invalid activity. Must be one of: ${VALID_ACTIVITIES.join(', ')}`);
-    }
+    const { project_id, activity } = parseArgs(args, startFallbackActivitySchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.startFallbackActivity(project_id, activity, session.currentSessionId || undefined);
@@ -61,9 +72,7 @@ export const startFallbackActivity = async (args, ctx) => {
     return { result };
 };
 export const stopFallbackActivity = async (args, ctx) => {
-    const { project_id, summary } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+    const { project_id, summary } = parseArgs(args, stopFallbackActivitySchema);
     const { session } = ctx;
     const apiClient = getApiClient();
     const response = await apiClient.stopFallbackActivity(project_id, summary, session.currentSessionId || undefined);
@@ -77,10 +86,8 @@ export const stopFallbackActivity = async (args, ctx) => {
         },
     };
 };
-export const getActivityHistory = async (args, ctx) => {
-    const { project_id, activity_type, limit = 50 } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+export const getActivityHistory = async (args, _ctx) => {
+    const { project_id, activity_type, limit } = parseArgs(args, getActivityHistorySchema);
     const apiClient = getApiClient();
     // Use proxy for get_activity_history operation
     const response = await apiClient.proxy('get_activity_history', {
@@ -99,10 +106,8 @@ export const getActivityHistory = async (args, ctx) => {
         },
     };
 };
-export const getActivitySchedules = async (args, ctx) => {
-    const { project_id } = args;
-    validateRequired(project_id, 'project_id');
-    validateUUID(project_id, 'project_id');
+export const getActivitySchedules = async (args, _ctx) => {
+    const { project_id } = parseArgs(args, getActivitySchedulesSchema);
     const apiClient = getApiClient();
     // Use proxy for get_activity_schedules operation
     const response = await apiClient.proxy('get_activity_schedules', {

package/dist/handlers/file-checkouts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * File Checkouts Handlers
+ *
+ * Handles file checkout/checkin for multi-agent coordination:
+ * - checkout_file: Check out a file before editing
+ * - checkin_file: Check in a file after editing
+ * - get_file_checkouts: Get active checkouts for a project
+ * - abandon_checkout: Force release a checkout
+ */
+import type { Handler, HandlerRegistry } from './types.js';
+export declare const checkoutFile: Handler;
+export declare const checkinFile: Handler;
+export declare const getFileCheckouts: Handler;
+export declare const abandonCheckout: Handler;
+/**
+ * File Checkouts handlers registry
+ */
+export declare const fileCheckoutHandlers: HandlerRegistry;

package/dist/handlers/file-checkouts.js

@@ -0,0 +1,101 @@
+/**
+ * File Checkouts Handlers
+ *
+ * Handles file checkout/checkin for multi-agent coordination:
+ * - checkout_file: Check out a file before editing
+ * - checkin_file: Check in a file after editing
+ * - get_file_checkouts: Get active checkouts for a project
+ * - abandon_checkout: Force release a checkout
+ */
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+const VALID_CHECKOUT_STATUSES = ['checked_out', 'checked_in', 'abandoned'];
+// Argument schemas for type-safe parsing
+const checkoutFileSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    file_path: { type: 'string', required: true },
+    reason: { type: 'string' },
+};
+const checkinFileSchema = {
+    checkout_id: { type: 'string', validate: uuidValidator },
+    project_id: { type: 'string', validate: uuidValidator },
+    file_path: { type: 'string' },
+    summary: { type: 'string' },
+};
+const getFileCheckoutsSchema = {
+    project_id: { type: 'string', required: true, validate: uuidValidator },
+    status: { type: 'string', validate: createEnumValidator(VALID_CHECKOUT_STATUSES) },
+    file_path: { type: 'string' },
+    limit: { type: 'number', default: 50 },
+};
+const abandonCheckoutSchema = {
+    checkout_id: { type: 'string', validate: uuidValidator },
+    project_id: { type: 'string', validate: uuidValidator },
+    file_path: { type: 'string' },
+};
+export const checkoutFile = async (args, ctx) => {
+    const { project_id, file_path, reason } = parseArgs(args, checkoutFileSchema);
+    const apiClient = getApiClient();
+    const response = await apiClient.checkoutFile(project_id, file_path, reason, ctx.session.currentSessionId || undefined);
+    if (!response.ok) {
+        throw new Error(response.error || 'Failed to checkout file');
+    }
+    return { result: response.data };
+};
+export const checkinFile = async (args, ctx) => {
+    const { checkout_id, project_id, file_path, summary } = parseArgs(args, checkinFileSchema);
+    // Validate that either checkout_id or both project_id and file_path are provided
+    if (!checkout_id && (!project_id || !file_path)) {
+        throw new Error('Either checkout_id or both project_id and file_path are required');
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.checkinFile({
+        checkout_id,
+        project_id,
+        file_path,
+        summary
+    }, ctx.session.currentSessionId || undefined);
+    if (!response.ok) {
+        throw new Error(response.error || 'Failed to checkin file');
+    }
+    return { result: response.data };
+};
+export const getFileCheckouts = async (args, _ctx) => {
+    const { project_id, status, file_path, limit } = parseArgs(args, getFileCheckoutsSchema);
+    const apiClient = getApiClient();
+    const response = await apiClient.getFileCheckouts(project_id, {
+        status,
+        file_path,
+        limit
+    });
+    if (!response.ok) {
+        throw new Error(response.error || 'Failed to get file checkouts');
+    }
+    return { result: response.data };
+};
+export const abandonCheckout = async (args, _ctx) => {
+    const { checkout_id, project_id, file_path } = parseArgs(args, abandonCheckoutSchema);
+    // Validate that either checkout_id or both project_id and file_path are provided
+    if (!checkout_id && (!project_id || !file_path)) {
+        throw new Error('Either checkout_id or both project_id and file_path are required');
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.abandonCheckout({
+        checkout_id,
+        project_id,
+        file_path
+    });
+    if (!response.ok) {
+        throw new Error(response.error || 'Failed to abandon checkout');
+    }
+    return { result: response.data };
+};
+/**
+ * File Checkouts handlers registry
+ */
+export const fileCheckoutHandlers = {
+    checkout_file: checkoutFile,
+    checkin_file: checkinFile,
+    get_file_checkouts: getFileCheckouts,
+    abandon_checkout: abandonCheckout,
+};

package/dist/handlers/findings.d.ts

@@ -19,6 +19,12 @@ export declare const getFindings: Handler;
 export declare const getFindingsStats: Handler;
 export declare const updateFinding: Handler;
 export declare const deleteFinding: Handler;
+/**
+ * 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 declare const queryKnowledgeBase: Handler;
 /**
  * Findings handlers registry
  */