@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/handlers/types.ts

@@ -1,176 +1,176 @@
-/**
- * Authentication context from API key validation
- */
-export interface AuthContext {
-	userId: string;
-	apiKeyId: string;
-	organizationId?: string;
-	scope: 'personal' | 'organization';
-}
-
-/**
- * Model-specific token tracking
- */
-export interface ModelTokens {
-	input: number;
-	output: number;
-}
-
-/**
- * Token usage tracking for the session
- */
-export interface TokenUsage {
-	callCount: number;
-	totalTokens: number;
-	byTool: Record<string, { calls: number; tokens: number }>;
-	byModel: Record<string, ModelTokens>;
-	currentModel: string | null; // 'opus' | 'sonnet' | 'haiku' | null
-}
-
-/**
- * Agent role for specialized work routing
- * - developer: General development work, picks up any available task (default)
- * - validator: Focuses on validating completed tasks
- * - deployer: Handles deployment coordination and monitoring
- * - reviewer: Code review and quality checks
- * - maintainer: Task management, git orchestration, housekeeping
- */
-export type AgentRole = 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
-
-/**
- * Session state that persists across tool calls
- */
-export interface SessionState {
-	instanceId: string;
-	currentSessionId: string | null;
-	currentPersona: string | null;
-	currentRole: AgentRole | null;
-	currentProjectId: string | null;
-	tokenUsage: TokenUsage;
-}
-
-/**
- * User updates since last sync (for start_work_session full mode)
- */
-export interface UserUpdates {
-	tasks?: Array<{ id: string; title: string; created_at: string }>;
-	blockers?: Array<{ id: string; description: string; created_at: string }>;
-	ideas?: Array<{ id: string; title: string; created_at: string }>;
-}
-
-/**
- * Context passed to all handlers
- */
-export interface HandlerContext {
-	auth: AuthContext;
-	session: SessionState;
-	/** Update session state (for handlers that modify session) */
-	updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'currentProjectId' | 'tokenUsage'>>) => void;
-	/** Get user updates since last sync (for session handlers) */
-	getUserUpdates?: (projectId: string) => Promise<UserUpdates | undefined>;
-	/** Select an available persona for the agent */
-	selectPersona?: (usedPersonas: Set<string>, instanceId: string) => string;
-	/** Extract project name from git URL */
-	extractProjectNameFromGitUrl?: (gitUrl: string) => string;
-}
-
-/**
- * Success result with typed data
- */
-export interface SuccessResult<T = unknown> {
-	result: T;
-	content?: Array<{ type: string; text: string }>;
-	isError?: false;
-}
-
-/**
- * Error result with error information
- */
-export interface ErrorResult {
-	result: { error: string; [key: string]: unknown };
-	content?: Array<{ type: string; text: string }>;
-	isError: true;
-}
-
-/**
- * Result returned by handlers - discriminated union for type safety
- * Use the helper functions success() and error() to create properly typed results.
- */
-export type HandlerResult<T = unknown> = SuccessResult<T> | ErrorResult;
-
-/**
- * Legacy HandlerResult interface for backward compatibility
- * @deprecated Use HandlerResult<T> discriminated union instead
- */
-export interface LegacyHandlerResult {
-	result?: unknown;
-	content?: Array<{ type: string; text: string }>;
-	isError?: boolean;
-}
-
-// ============================================================================
-// Result Factory Functions - use these for type-safe handler results
-// ============================================================================
-
-/**
- * Create a success result with typed data
- * @example
- * return success({ tasks: data, total_count: count });
- */
-export function success<T>(data: T): SuccessResult<T> {
-	return { result: data };
-}
-
-/**
- * Create an error result
- * @example
- * return error('Task not found');
- * return error('Validation failed', { field: 'title', reason: 'too long' });
- */
-export function error(message: string, details?: Record<string, unknown>): ErrorResult {
-	return {
-		result: { error: message, ...details },
-		isError: true
-	};
-}
-
-// ============================================================================
-// Type Predicates - use for runtime type narrowing
-// ============================================================================
-
-/**
- * Check if a handler result is a success (not an error)
- * @example
- * const result = await handler(args, ctx);
- * if (isSuccess(result)) {
- *   console.log(result.result); // typed as T
- * }
- */
-export function isSuccess<T>(result: HandlerResult<T>): result is SuccessResult<T> {
-	return !result.isError;
-}
-
-/**
- * Check if a handler result is an error
- * @example
- * const result = await handler(args, ctx);
- * if (isError(result)) {
- *   console.log(result.result.error); // string
- * }
- */
-export function isError(result: HandlerResult<unknown>): result is ErrorResult {
-	return result.isError === true;
-}
-
-/**
- * Handler function type
- */
-export type Handler = (
-	args: Record<string, unknown>,
-	ctx: HandlerContext
-) => Promise<HandlerResult>;
-
-/**
- * Handler registry - maps tool names to handler functions
- */
-export type HandlerRegistry = Record<string, Handler>;
+/**
+ * Authentication context from API key validation
+ */
+export interface AuthContext {
+	userId: string;
+	apiKeyId: string;
+	organizationId?: string;
+	scope: 'personal' | 'organization';
+}
+
+/**
+ * Model-specific token tracking
+ */
+export interface ModelTokens {
+	input: number;
+	output: number;
+}
+
+/**
+ * Token usage tracking for the session
+ */
+export interface TokenUsage {
+	callCount: number;
+	totalTokens: number;
+	byTool: Record<string, { calls: number; tokens: number }>;
+	byModel: Record<string, ModelTokens>;
+	currentModel: string | null; // 'opus' | 'sonnet' | 'haiku' | null
+}
+
+/**
+ * Agent role for specialized work routing
+ * - developer: General development work, picks up any available task (default)
+ * - validator: Focuses on validating completed tasks
+ * - deployer: Handles deployment coordination and monitoring
+ * - reviewer: Code review and quality checks
+ * - maintainer: Task management, git orchestration, housekeeping
+ */
+export type AgentRole = 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+
+/**
+ * Session state that persists across tool calls
+ */
+export interface SessionState {
+	instanceId: string;
+	currentSessionId: string | null;
+	currentPersona: string | null;
+	currentRole: AgentRole | null;
+	currentProjectId: string | null;
+	tokenUsage: TokenUsage;
+}
+
+/**
+ * User updates since last sync (for start_work_session full mode)
+ */
+export interface UserUpdates {
+	tasks?: Array<{ id: string; title: string; created_at: string }>;
+	blockers?: Array<{ id: string; description: string; created_at: string }>;
+	ideas?: Array<{ id: string; title: string; created_at: string }>;
+}
+
+/**
+ * Context passed to all handlers
+ */
+export interface HandlerContext {
+	auth: AuthContext;
+	session: SessionState;
+	/** Update session state (for handlers that modify session) */
+	updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'currentProjectId' | 'tokenUsage'>>) => void;
+	/** Get user updates since last sync (for session handlers) */
+	getUserUpdates?: (projectId: string) => Promise<UserUpdates | undefined>;
+	/** Select an available persona for the agent */
+	selectPersona?: (usedPersonas: Set<string>, instanceId: string) => string;
+	/** Extract project name from git URL */
+	extractProjectNameFromGitUrl?: (gitUrl: string) => string;
+}
+
+/**
+ * Success result with typed data
+ */
+export interface SuccessResult<T = unknown> {
+	result: T;
+	content?: Array<{ type: string; text: string }>;
+	isError?: false;
+}
+
+/**
+ * Error result with error information
+ */
+export interface ErrorResult {
+	result: { error: string; [key: string]: unknown };
+	content?: Array<{ type: string; text: string }>;
+	isError: true;
+}
+
+/**
+ * Result returned by handlers - discriminated union for type safety
+ * Use the helper functions success() and error() to create properly typed results.
+ */
+export type HandlerResult<T = unknown> = SuccessResult<T> | ErrorResult;
+
+/**
+ * Legacy HandlerResult interface for backward compatibility
+ * @deprecated Use HandlerResult<T> discriminated union instead
+ */
+export interface LegacyHandlerResult {
+	result?: unknown;
+	content?: Array<{ type: string; text: string }>;
+	isError?: boolean;
+}
+
+// ============================================================================
+// Result Factory Functions - use these for type-safe handler results
+// ============================================================================
+
+/**
+ * Create a success result with typed data
+ * @example
+ * return success({ tasks: data, total_count: count });
+ */
+export function success<T>(data: T): SuccessResult<T> {
+	return { result: data };
+}
+
+/**
+ * Create an error result
+ * @example
+ * return error('Task not found');
+ * return error('Validation failed', { field: 'title', reason: 'too long' });
+ */
+export function error(message: string, details?: Record<string, unknown>): ErrorResult {
+	return {
+		result: { error: message, ...details },
+		isError: true
+	};
+}
+
+// ============================================================================
+// Type Predicates - use for runtime type narrowing
+// ============================================================================
+
+/**
+ * Check if a handler result is a success (not an error)
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isSuccess(result)) {
+ *   console.log(result.result); // typed as T
+ * }
+ */
+export function isSuccess<T>(result: HandlerResult<T>): result is SuccessResult<T> {
+	return !result.isError;
+}
+
+/**
+ * Check if a handler result is an error
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isError(result)) {
+ *   console.log(result.result.error); // string
+ * }
+ */
+export function isError(result: HandlerResult<unknown>): result is ErrorResult {
+	return result.isError === true;
+}
+
+/**
+ * Handler function type
+ */
+export type Handler = (
+	args: Record<string, unknown>,
+	ctx: HandlerContext
+) => Promise<HandlerResult>;
+
+/**
+ * Handler registry - maps tool names to handler functions
+ */
+export type HandlerRegistry = Record<string, Handler>;