// @lifecycle canonical - Prompt engine action metadata definitions.
import {
  prompt_engineCommands,
  prompt_engineParameters,
} from '../../contracts/schemas/_generated/prompt_engine.generated.js';
import {
  contractToCommandDescriptors,
  contractToParameterDescriptors,
} from '../../contracts/schemas/adapter.js';

import type {
  PromptEngineMetadataData,
  ToolMetadata,
  ParameterDescriptor,
  CommandDescriptor,
  UsagePatternDescriptor,
} from './types.js';
import type { McpToolRequest } from '../../../shared/types/execution.js';

type RequestField = keyof McpToolRequest;

const promptEngineContract = {
  tool: 'prompt_engine',
  version: 1,
  summary:
    'Execute prompts/chains with inline operators. Steps must start with `>>prompt_id` (or `/prompt_id`); place modifiers first: `%judge @Framework #style :: gates`.',
  parameters: prompt_engineParameters,
  commands: prompt_engineCommands,
};

// Parameter-specific issues (only track actual problems, not documentation)
const issuesByParam: Partial<Record<RequestField, ParameterDescriptor<RequestField>['issues']>> = {
  // No active issues - parameters are working as designed
};

const generatedParameters = contractToParameterDescriptors<RequestField>(promptEngineContract).map(
  (param) => {
    const issues = issuesByParam[param.name];
    if (!issues) {
      return param;
    }

    return {
      ...param,
      issues,
    };
  }
) satisfies ParameterDescriptor<RequestField>[];

// Parameters from contracts plus any manually tracked deprecated params
const parameterDescriptors: ParameterDescriptor<RequestField>[] = [...generatedParameters];

const commandDescriptors: CommandDescriptor[] = [
  ...contractToCommandDescriptors(promptEngineContract),
  {
    id: '>>listprompts',
    status: 'working',
    description: 'Routes to resource_manager prompt list action. Accepts optional search terms.',
    issues: [],
  },
];

const usagePatterns: UsagePatternDescriptor<RequestField>[] = [
  {
    id: 'combined-operators',
    title: 'Combined Modifiers Chain',
    summary:
      'Show correct operator order: modifiers first, prompt ids on every step, quoted free text after the prompt id.',
    sampleCommand: [
      'prompt_engine({',
      '  "command": "%judge @CAGEERF #analytical >>analytical \\"overview\\" --> >>procedural \\"edge cases\\" --> >>creative \\"JSON summary\\" :: framework-compliance :: technical-accuracy"',
      '})',
    ].join('\n'),
    parameters: ['command'],
    notes: [
      'Modifiers (%judge/@/#style/::) apply to the whole chain—keep them at the front.',
      'Each step must start with `>>prompt_id` (or `/prompt_id`); avoid plain-text step labels.',
      'Execution shape: command (+optional gates/options); resume shape: chain_id plus user_response and/or gate_verdict/gate_action.',
    ],
  },
  {
    id: 'inline-criteria',
    title: 'Inline Quality Criteria (Simplest)',
    summary:
      'Use the `::` operator to add validation criteria directly in commands as natural language. Simple, flexible, and requires no setup.',
    sampleCommand: [
      '// Simple single prompt with criteria',
      'prompt_engine({',
      '  "command": ">>audit_plan topic:\\"security\\" :: \\"cite two examples, list mitigations, flag open questions\\""',
      '})',
      '',
      '// Chain with criteria applied to steps',
      'prompt_engine({',
      '  "command": ">>analysis --> summary :: \\"include sources, note confidence levels\\""',
      '})',
      '',
      '// Multiple criteria',
      'prompt_engine({',
      '  "command": ">>code_review :: \\"check naming conventions, verify error handling, confirm tests\\" -->"',
      '})',
    ].join('\n'),
    parameters: ['command'],
    notes: [
      'Provide clear, actionable criteria as natural language text - the system automatically creates validation guidance.',
      'Works with single prompts and chains - criteria apply to all steps in a chain.',
      'Most flexible approach - adjust criteria per execution without configuration.',
      'For reusable validation with complex configurations, use the `gates` parameter instead.',
    ],
  },
  {
    id: 'unified-gates',
    title: 'Unified Gates Parameter (Recommended)',
    summary:
      'Use the new `gates` parameter to specify all types of validation in a single array. Accepts gate IDs, simple checks, and full gate definitions.',
    sampleCommand: [
      '// Mix gate IDs, simple checks, and full definitions',
      'prompt_engine({',
      '  "command": ">>prompt security-review",',
      '  "gates": [',
      '    "toxicity",                                    // Gate ID reference',
      '    "traceability",                                // Gate ID reference',
      '    { "name": "red-team", "description": "Confirm exfil path" },  // Simple check',
      '    { "id": "gdpr-check", "criteria": ["no PII"], "severity": "high" }  // Full definition',
      '  ]',
      '})',
      '',
      '// Chain with step-specific gates',
      'prompt_engine({',
      '  "command": ">>analysis --> review --> summary",',
      '  "gates": [',
      '    "research-quality",                            // Applies to all steps',
      '    { "id": "step2-only", "criteria": ["cite sources"], "target_step_number": 2 },',
      '    { "id": "final-steps", "criteria": ["verify conclusions"], "apply_to_steps": [2, 3] }',
      '  ]',
      '})',
    ].join('\n'),
    parameters: ['command', 'gates'],
    notes: [
      'Canonical parameter for all gate specification (v3.0.0+).',
      'Accepts mixed array: gate ID strings, simple name/description objects, or full gate definitions.',
      'In chain executions, use target_step_number or apply_to_steps to control which steps gates apply to.',
      'Without step targeting, gates default to current step (step 1 for new chains, resume step for resumed chains).',
    ],
  },
  {
    id: 'chain-resume',
    title: 'Chain Resume & Restart',
    summary:
      'Resume an interrupted chain with chain_id, feed a user response, or force a restart from the first step.',
    sampleCommand: [
      'prompt_engine({',
      '  "chain_id": "chain-threat-model#3",',
      '  "user_response": "Proceed with mitigations A and B."',
      '})',
    ].join('\n'),
    parameters: ['command', 'chain_id', 'user_response', 'force_restart'],
    notes: [
      'Use gate_verdict when resuming after manual reviews.',
      'Setting force_restart:true ignores previously cached steps even if chain_id is present.',
    ],
  },
  {
    id: 'prompt-catalog',
    title: 'Prompt Catalog Discovery',
    summary:
      'Route list commands back to the resource manager for semantic filtering, even when invoked from prompt engine.',
    sampleCommand: ['prompt_engine({', '  "command": ">>listprompts security audits"', '})'].join(
      '\n'
    ),
    parameters: ['command'],
    notes: [
      'Routing pattern handled before prompt execution; falls back to in-memory catalog if resource_manager is offline.',
      'Use search terms after >>listprompts to limit results (e.g., `>>listprompts security`).',
    ],
  },
];

export const promptEngineMetadata: ToolMetadata<PromptEngineMetadataData> = {
  tool: 'prompt_engine',
  version: 1, // Matches contract version
  notes: [
    'Parameters sourced from contracts/_generated and McpToolRequest interface.',
    'Use this data to seed telemetry and guide flows.',
    'Unified gates parameter is canonical for all gate specification.',
  ],
  issues: [
    // No active issues - system is stable
  ],
  data: {
    parameters: parameterDescriptors,
    commands: commandDescriptors,
    usagePatterns,
  },
};
