@swoft/platform-contracts/src/shared/NavigationHints.ts

DDD-compliant dependency injection contracts for Swoft platform - Defines clean architecture boundaries

/**
 * NavigationHints Interface System
 *
 * Defines AI-native navigation patterns for MCP (Model Context Protocol) servers.
 * Standardizes how AI agents discover and navigate between related tools and contexts.
 *
 * Design Principles:
 * - AI-native: Designed for LLM consumption and understanding
 * - Extensible: Easy to add new navigation patterns
 * - Cross-MCP: Supports navigation between different MCP servers
 * - Context-aware: Includes workflow and git state information
 */

// ============================================
// TYPE DEFINITIONS
// ============================================

/**
 * Operation types for workflow context
 * Standardized across all MCP servers
 */
export type OperationType =
  | 'incident'
  | 'maintenance'
  | 'discovery'
  | 'monitoring'
  | 'development'
  | 'planning';

/**
 * Severity levels for prioritization
 * Consistent across all domains
 */
export type SeverityLevel = 'low' | 'medium' | 'high' | 'critical';

/**
 * MCP server identifiers
 * Canonical list of all MCP servers in the ecosystem
 */
export type McpServerId =
  | 'mcp__devops-mcp__'
  | 'mcp__gtd-mcp__'
  | 'mcp__party-mcp__'
  | 'mcp__ddd-mcp__'
  | 'mcp__frontend-dev__'
  | 'mcp__backend-dev__';

/**
 * Domain contexts supported across the platform
 */
export type DomainContext =
  | 'gtd'
  | 'party_management'
  | 'devops'
  | 'ddd_modeling'
  | 'frontend_dev'
  | 'backend_dev'
  | 'infrastructure'
  | 'coordination';

/**
 * Workflow phases for development and operational work
 */
export type WorkflowPhase =
  | 'planning'
  | 'analysis'
  | 'design'
  | 'implementation'
  | 'testing'
  | 'deployment'
  | 'monitoring'
  | 'maintenance'
  | 'incident_response';

// ============================================
// CORE NAVIGATION INTERFACES
// ============================================

/**
 * Reference to a tool within the same MCP server
 */
export interface ToolReference {
  /** Name of the tool (e.g., 'create_person', 'health_check') */
  toolName: string;

  /** Human-readable description of what this tool does */
  description: string;

  /** When this tool would be relevant (e.g., 'after_creation', 'for_validation') */
  relevanceContext?: string;

  /** Suggested parameters based on current context */
  suggestedParams?: Record<string, unknown>;
}

/**
 * Reference to tools in other MCP servers
 */
export interface CrossMcpReference {
  /** MCP server name from the canonical registry */
  mcpServer: McpServerId;

  /** Tool name within that MCP server */
  toolName: string;

  /** Why this cross-MCP tool is relevant */
  relationshipDescription: string;

  /** Expected workflow integration */
  integrationPattern?: 'sequential' | 'parallel' | 'conditional' | 'fallback';
}

/**
 * Complex context handoff for cross-MCP workflows
 * Enables seamless transitions between different MCP servers with pre-populated data
 */
export interface ContextHandoff {
  /** Target MCP server */
  mcp: string;

  /** Specific tool to invoke (optional) */
  tool?: string;

  /** Recommended action for the user */
  suggested_action: string;

  /** Use case scenario description */
  scenario: string;

  /** Pre-populated parameters for the target tool */
  pre_populated: Record<string, unknown>;

  /** Workflow context for intelligent coordination */
  workflow_context: {
    /** Type of operation being performed */
    operation_type: OperationType;

    /** Severity or priority level */
    severity: SeverityLevel;

    /** Domain-specific context information */
    service_context?: Record<string, unknown>;
    domain_context?: Record<string, unknown>;
    user_context?: Record<string, unknown>;
    project_context?: Record<string, unknown>;
  };
}

/**
 * Git-aware navigation hints for repository context
 */
export interface GitNavigationHint {
  /** Type of git-related hint */
  type: 'branch_switch' | 'commit_needed' | 'merge_conflict' | 'submodule_update' | 'status_check';

  /** Human-readable message about git state */
  message: string;

  /** Suggested git commands to resolve */
  suggestedCommands?: string[];

  /** Files or paths relevant to this hint */
  affectedPaths?: string[];
}

/**
 * Contextual information about current workflow state
 */
export interface ContextualInformation {
  /** Current phase of work */
  workflowPhase?: WorkflowPhase;

  /** Domain context - which bounded context or domain this relates to */
  domainContext?: DomainContext;

  /** User's current goal or objective */
  currentObjective?: string;

  /** Constraints or limitations to be aware of */
  constraints?: string[];

  /** Resources or dependencies that are available */
  availableResources?: string[];

  /**
   * Specific bounded context information
   * Domain-specific context that varies by MCP server
   */
  boundedContextInfo?: {
    /** GTD-specific context */
    gtd?: {
      current_area_of_focus?: string;
      active_projects?: string[];
      inbox_items_count?: number;
      next_actions_due?: number;
    };

    /** Party management context */
    party?: {
      active_organization?: string;
      current_person_context?: string;
      team_members_involved?: string[];
    };

    /** DevOps context */
    devops?: {
      affected_services?: string[];
      system_health_status?: string;
      ongoing_incidents?: number;
      maintenance_windows?: string[];
    };

    /** DDD modeling context */
    ddd?: {
      current_domain?: string;
      bounded_contexts_in_focus?: string[];
      aggregates_being_designed?: string[];
    };
  };
}

/**
 * Main NavigationHints interface
 * Provides comprehensive navigation guidance for AI agents
 */
export interface NavigationHints {
  /** Immediate next steps the AI should consider */
  next_steps: string[];

  /** Related tools within the same MCP server */
  related_tools: ToolReference[];

  /** Tools in other MCP servers that might be relevant */
  cross_mcp: CrossMcpReference[];

  /** Git repository state and recommendations */
  git_aware: GitNavigationHint[];

  /** Current workflow and domain context */
  context: ContextualInformation;

  /**
   * Complex context handoffs for seamless cross-MCP workflows
   * Enables intelligent coordination between different MCP servers
   */
  context_handoffs?: Record<string, ContextHandoff>;

  /** Optional metadata for advanced navigation */
  metadata?: {
    /** Timestamp when hints were generated */
    generated_at?: string;

    /** Confidence level in the suggestions (0-1) */
    confidence?: number;

    /** Source of the navigation hints */
    source?: string;

    /** Version of the navigation system */
    version?: string;
  };
}

// ============================================
// GENERIC RESPONSE WRAPPER
// ============================================

/**
 * Generic wrapper that adds navigation hints to any MCP response
 * Enables consistent navigation patterns across all MCP tools
 */
export interface McpResponseWithNavigation<T> {
  /** The original response data */
  data: T;

  /** Navigation hints for AI consumption */
  navigation: NavigationHints;

  /** Optional success indicator */
  success?: boolean;

  /** Optional error information */
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
}

// ============================================
// UTILITY TYPES
// ============================================

/**
 * Partial navigation hints for scenarios where only some navigation info is available
 */
export type PartialNavigationHints = Partial<NavigationHints>;

/**
 * Navigation hint builder for fluent API construction
 */
export interface NavigationHintsBuilder {
  addNextStep(step: string): NavigationHintsBuilder;
  addRelatedTool(tool: ToolReference): NavigationHintsBuilder;
  addCrossMcpTool(reference: CrossMcpReference): NavigationHintsBuilder;
  addGitHint(hint: GitNavigationHint): NavigationHintsBuilder;
  setContext(context: ContextualInformation): NavigationHintsBuilder;
  addContextHandoff(key: string, handoff: ContextHandoff): NavigationHintsBuilder;
  setMetadata(metadata: NavigationHints['metadata']): NavigationHintsBuilder;
  build(): NavigationHints;
}

/**
 * Factory function type for creating navigation hints
 */
export type NavigationHintsFactory = (context?: Partial<ContextualInformation>) => NavigationHints;

/**
 * Type for navigation hint processors that can enhance or filter hints
 */
export type NavigationHintsProcessor = (
  hints: NavigationHints,
  context?: unknown
) => NavigationHints;

// ============================================
// HELPER FACTORY INTERFACES
// ============================================

/**
 * Context handoff factory for common scenarios
 * Provides pre-built handoff patterns for typical cross-MCP workflows
 */
export interface ContextHandoffFactory {
  createIncidentHandoff(
    targetMcp: McpServerId,
    severity: SeverityLevel,
    context: Record<string, unknown>
  ): ContextHandoff;

  createMaintenanceHandoff(
    targetMcp: McpServerId,
    maintenanceType: string,
    context: Record<string, unknown>
  ): ContextHandoff;

  createDiscoveryHandoff(
    targetMcp: McpServerId,
    discoveryGoal: string,
    context: Record<string, unknown>
  ): ContextHandoff;

  createDevelopmentHandoff(
    targetMcp: McpServerId,
    developmentPhase: WorkflowPhase,
    context: Record<string, unknown>
  ): ContextHandoff;

  createPlanningHandoff(
    targetMcp: McpServerId,
    planningScope: string,
    context: Record<string, unknown>
  ): ContextHandoff;
}