// @lifecycle canonical - Routes MCP tool invocations to implementations.
export interface ToolRoutingResult {
  requiresRouting: boolean;
  targetTool?: string;
  translatedParams?: Record<string, any>;
  originalCommand?: string;
}

const LIST_PROMPTS_PATTERN = /^(>>|\/)?listprompts?(\s.+)?$/i;
const HELP_PATTERN = /^(>>|\/)?help(?:\s+(.*))?$/i;
const STATUS_PATTERN = /^(>>|\/)?status$/i;
const FRAMEWORK_PATTERN = /^(>>|\/)?framework\s+(switch|change)\s+(.+)$/i;
const ANALYTICS_PATTERN = /^(>>|\/)?analytics?$/i;
const GUIDE_PATTERN = /^(>>|\/)?guide(?:\s+(.*))?$/i;
const GATES_PATTERN = /^(>>|\/)?gates?(?:\s+(.*))?$/i;
const ALLOWED_PREFIX_TOKENS = ['@', '%judge', '%clean', '%lean'];

function isPlausiblePromptId(token: string): boolean {
  return /^[A-Za-z0-9][A-Za-z0-9_\/-]*$/.test(token);
}

/**
 * Detects whether a raw command string should be routed to an internal handler
 * (resource manager, system control, etc.) before the prompt engine attempts to
 * parse it as a template/chain instruction.
 */
export function detectToolRoutingCommand(command: string): ToolRoutingResult {
  const trimmedCommand = command.trim();
  if (!trimmedCommand) {
    return { requiresRouting: false };
  }

  if (LIST_PROMPTS_PATTERN.test(trimmedCommand)) {
    const args = trimmedCommand.replace(/^(?:>>|\/)?listprompts?\s?/i, '').trim();
    return {
      requiresRouting: true,
      targetTool: 'resource_manager',
      translatedParams: {
        resource_type: 'prompt',
        action: 'list',
        ...(args && { search_query: args }),
      },
      originalCommand: command,
    };
  }

  const guideMatch = trimmedCommand.match(GUIDE_PATTERN);
  if (guideMatch) {
    const goal = (guideMatch[2] ?? '').trim();
    return {
      requiresRouting: true,
      targetTool: 'prompt_engine_guide',
      translatedParams: { goal },
      originalCommand: command,
    };
  }

  const helpMatch = trimmedCommand.match(HELP_PATTERN);
  if (helpMatch) {
    const topic = (helpMatch[2] ?? '').trim();
    return {
      requiresRouting: true,
      targetTool: 'system_control',
      translatedParams: topic ? { action: 'guide', topic } : { action: 'guide' },
      originalCommand: command,
    };
  }

  if (STATUS_PATTERN.test(trimmedCommand)) {
    return {
      requiresRouting: true,
      targetTool: 'system_control',
      translatedParams: { action: 'status' },
      originalCommand: command,
    };
  }

  const frameworkMatch = trimmedCommand.match(FRAMEWORK_PATTERN);
  if (frameworkMatch?.[3]) {
    return {
      requiresRouting: true,
      targetTool: 'system_control',
      translatedParams: {
        action: 'framework',
        operation: 'switch',
        framework: frameworkMatch[3].trim(),
      },
      originalCommand: command,
    };
  }

  if (ANALYTICS_PATTERN.test(trimmedCommand)) {
    return {
      requiresRouting: true,
      targetTool: 'system_control',
      translatedParams: { action: 'analytics' },
      originalCommand: command,
    };
  }

  // >>gates command - list available canonical gates with optional search
  const gatesMatch = trimmedCommand.match(GATES_PATTERN);
  if (gatesMatch) {
    const searchTerm = (gatesMatch[2] ?? '').trim();
    return {
      requiresRouting: true,
      targetTool: 'system_control',
      translatedParams: {
        action: 'gates',
        operation: 'list',
        ...(searchTerm && { search_query: searchTerm }),
      },
      originalCommand: command,
    };
  }

  if (trimmedCommand.startsWith('>>')) {
    const rest = trimmedCommand.slice(2).trimStart();
    const firstToken = rest.split(/\s+/)[0] ?? '';
    const isAllowedPrefix = ALLOWED_PREFIX_TOKENS.some((prefix) =>
      rest.toLowerCase().startsWith(prefix)
    );

    if (!rest || (!isAllowedPrefix && !isPlausiblePromptId(firstToken))) {
      return {
        requiresRouting: true,
        targetTool: 'prompt_engine_invalid_command',
        translatedParams: {
          reason: 'missing-or-invalid-prompt-id',
        },
        originalCommand: command,
      };
    }
  }

  return { requiresRouting: false };
}
