@swoft/platform-contracts/examples/navigation-hints-example.ts

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

/**
 * NavigationHints Interface Examples
 * Demonstrates the enhanced platform contracts for cross-MCP navigation
 */

import {
  NavigationHints,
  ContextHandoff,
  OperationType,
  SeverityLevel,
  McpServerId,
  DomainContext,
  WorkflowPhase,
} from '../src/shared/NavigationHints.js';

// ============================================
// EXAMPLE 1: DevOps Incident Handoff to GTD
// ============================================

const devopsIncidentNavigationHints: NavigationHints = {
  next_steps: [
    'Use service_control to restart the failed service',
    'Use logs to investigate the root cause',
    'Document the incident for follow-up',
  ],

  related_tools: [
    {
      toolName: 'service_control',
      description: 'Restart/stop/start PM2 services',
      relevanceContext: 'Service is down and needs restart',
    },
    {
      toolName: 'logs',
      description: 'View service logs for debugging',
      relevanceContext: 'Need to investigate failure cause',
    },
  ],

  cross_mcp: [
    {
      mcpServer: 'mcp__gtd-mcp__',
      toolName: 'gtd_inbox_capture',
      relationshipDescription: 'Document incident for tracking and follow-up',
      integrationPattern: 'sequential',
    },
  ],

  git_aware: [
    {
      type: 'status_check',
      message: 'Service configuration may have changed',
      suggestedCommands: ['git status', 'git diff HEAD~1'],
      affectedPaths: ['ecosystem.config.js', '.env.local'],
    },
  ],

  context: {
    workflowPhase: 'incident_response',
    domainContext: 'devops',
    currentObjective: 'Restore service stability',
    constraints: ['Service is critical for production'],
    availableResources: ['PM2 process manager', 'MongoDB backups'],
    boundedContextInfo: {
      devops: {
        affected_services: ['@swoft/collaboration-backend'],
        system_health_status: 'degraded',
        ongoing_incidents: 1,
        maintenance_windows: [],
      },
    },
  },

  // Enhanced: Complex context handoffs
  context_handoffs: {
    document_incident: {
      mcp: 'mcp__gtd-mcp__',
      tool: 'gtd_inbox_capture',
      suggested_action: 'Document service incident for follow-up investigation',
      scenario: 'Service down - requires immediate attention and follow-up',
      pre_populated: {
        content:
          'INCIDENT: @swoft/collaboration-backend service down - investigate and prevent recurrence',
        source: 'devops-health-check',
        capturedBy: 'ai-coordinator',
        tags: ['incident', 'service-down', 'collaboration-backend'],
        priority: 'high',
      },
      workflow_context: {
        operation_type: 'incident',
        severity: 'high',
        service_context: {
          service_name: '@swoft/collaboration-backend',
          service_port: 5001,
          service_type: 'backend',
          incident_type: 'service_down',
        },
      },
    },

    find_service_owner: {
      mcp: 'mcp__party-mcp__',
      tool: 'party_list_persons',
      suggested_action: 'Locate responsible team member for immediate notification',
      scenario: 'Service incident requires human intervention',
      pre_populated: {
        searchTerm: 'backend developer',
        roleType: 'Human',
        isActive: true,
        limit: 5,
      },
      workflow_context: {
        operation_type: 'incident',
        severity: 'high',
        service_context: {
          affected_service: '@swoft/collaboration-backend',
          urgency: 'immediate',
        },
      },
    },
  },

  metadata: {
    generated_at: new Date().toISOString(),
    confidence: 0.95,
    source: 'devops-health-check',
    version: '1.1.0',
  },
};

// ============================================
// EXAMPLE 2: GTD Planning Handoff to DDD
// ============================================

const gtdPlanningNavigationHints: NavigationHints = {
  next_steps: [
    'Define project outcome clearly',
    'Identify domain boundaries',
    'Create domain model structure',
  ],

  related_tools: [
    {
      toolName: 'gtd_natural_planning',
      description: 'Apply 5-step natural planning model',
      relevanceContext: 'Project needs clear planning structure',
    },
  ],

  cross_mcp: [
    {
      mcpServer: 'mcp__ddd-mcp__',
      toolName: 'ddd_create_domain',
      relationshipDescription: 'Model the business domain for this project',
      integrationPattern: 'sequential',
    },
  ],

  git_aware: [],

  context: {
    workflowPhase: 'planning',
    domainContext: 'gtd',
    currentObjective: 'Plan new feature development project',
    boundedContextInfo: {
      gtd: {
        current_area_of_focus: 'product_development',
        active_projects: ['User Authentication System'],
        inbox_items_count: 0,
        next_actions_due: 3,
      },
    },
  },

  context_handoffs: {
    model_domain: {
      mcp: 'mcp__ddd-mcp__',
      tool: 'ddd_create_domain',
      suggested_action: 'Create domain model for the authentication system',
      scenario: 'New feature requires domain modeling before implementation',
      pre_populated: {
        id: 'user-authentication',
        name: 'User Authentication',
        type: 'core',
        description: 'User authentication and authorization domain',
      },
      workflow_context: {
        operation_type: 'planning',
        severity: 'medium',
        domain_context: {
          business_area: 'user_management',
          complexity: 'medium',
          stakeholders: ['product_team', 'security_team'],
        },
      },
    },
  },
};

// ============================================
// EXAMPLE 3: Cross-MCP Factory Usage
// ============================================

function createMaintenanceHandoff(
  targetMcp: McpServerId,
  maintenanceType: string,
  context: Record<string, unknown>
): ContextHandoff {
  return {
    mcp: targetMcp,
    suggested_action: `Schedule ${maintenanceType} maintenance`,
    scenario: `System healthy - good time for ${maintenanceType}`,
    pre_populated: {
      maintenance_type: maintenanceType,
      scheduled_time: 'next_maintenance_window',
      ...context,
    },
    workflow_context: {
      operation_type: 'maintenance',
      severity: 'low',
      service_context: context,
    },
  };
}

// Usage example
const maintenanceHandoff = createMaintenanceHandoff('mcp__gtd-mcp__', 'dependency_update', {
  affected_services: ['@swoft/platform-contracts'],
  maintenance_window: '2024-08-03T02:00:00Z',
});

console.log('✅ NavigationHints examples created successfully!');
console.log('🔄 Enhanced interface ready for rollout to all MCP servers');