/**
 * Canonical Environment Variable Specification for ticket-mate
 * 
 * This file defines all environment variables used by ticket-mate.
 * It's used for documentation, validation, and tooling.
 */

export const envSpec = {
  required: [
    "JIRA_BASE_URL",
    "JIRA_EMAIL",
    "JIRA_API_KEY",
  ],
  
  optional: [
    // Authentication & OAuth
    "JIRA_API_TOKEN",              // DEPRECATED: Use JIRA_API_KEY instead (backward compatibility only, will be removed)
    "ATLASSIAN_CLIENT_ID",              // OAuth client ID (for OAuth flow)
    "ATLASSIAN_CLIENT_SECRET",          // OAuth client secret
    "JIRA_REDIRECT_URI",           // OAuth redirect URI (defaults to localhost:4000)
    "JIRA_SCOPES",                 // OAuth scopes (defaults to read:jira-work write:jira-work read:jira-user offline_access)
    
    // Project Configuration
    "JIRA_PROJECT_KEY",            // Default project key (e.g., NOVA)
    "JIRA_SUPPORT_PROJECT_KEY",    // Legacy alias for JIRA_PROJECT_KEY
    "JIRA_EPIC_KEY",               // Default epic key
    "JIRA_SUPPORT_EPIC_KEY",       // Legacy alias for JIRA_EPIC_KEY
    "JIRA_LABEL",                  // Default label
    "JIRA_SUPPORT_LABEL",          // Legacy alias for JIRA_LABEL
    
    // User Configuration
    "JIRA_DEFAULT_REPORTER",       // Default reporter email/accountId for ticket creation
    "JIRA_AUTOMATION_EMAIL",       // Automation user email (e.g., cursor.automation@domain.com)
    "JIRA_AUTO_WORK_ASSIGNEE",     // Default assignee for automation (defaults to "cursor.automation")
    "JIRA_CURSOR_DEV_ACCOUNT_ID",  // Cursor dev account ID
    "JIRA_LEAD_ACCOUNT_ID",        // Project lead account ID
    
    // Cloud API Configuration
    "JIRA_CLOUD_ID",               // Atlassian cloud ID for scoped API tokens
    "JIRA_USE_CLOUD_API",          // Use cloud API URL (set to "true")
    
    // Webhooks & Integration
    "JIRA_WEBHOOK_SECRET",         // Secret for validating Jira webhooks
    "NEXT_PUBLIC_APP_URL",         // Public app URL (for webhooks, defaults to localhost:4000)
    "NEXT_PUBLIC_WEBHOOK_URL",     // Public webhook URL
    "NEXT_PUBLIC_NGROK_URL",       // Ngrok URL for local development
    "NGROK_DEV_DOMAIN",            // Ngrok dev domain
    
    // Custom Fields
    "JIRA_EPIC_LINK_FIELD_ID",     // Epic link custom field ID (defaults to customfield_10014)
    "JIRA_ACCEPTANCE_CRITERIA_FIELD_ID", // Acceptance criteria custom field ID
    
    // Status Transitions
    "JIRA_TRANSITION_TODO",        // "To Do" transition name (defaults to "To Do")
    "JIRA_TRANSITION_IN_PROGRESS", // "In Progress" transition name (defaults to "In Progress")
    "JIRA_TRANSITION_IN_REVIEW",   // "In Review" transition name (defaults to "In Review")
    "JIRA_TRANSITION_DONE",        // "Done" transition name (defaults to "Done")
    
    // AI Configuration
    "JIRA_AI_READY_LABEL",         // Label for AI-ready tickets (defaults to "AI-READY")
    "JIRA_AI_READY_STATUS_CATEGORY", // Status category for AI-ready (defaults to "In Progress")
    "JIRA_ISSUE_TYPE_MAPPING",     // CSV mapping of issue types
    
    // Frontend Configuration
    "NEXT_PUBLIC_JIRA_BASE_URL",   // Public Jira base URL (exposed to browser)
    "NEXT_PUBLIC_JIRA_MATE_API_KEY", // Public API key for frontend API calls
    "NEXT_PUBLIC_GITHUB_REPO_URL", // GitHub repository URL
    "NEXT_PUBLIC_GOOGLE_MAPS_API_KEY", // Google Maps API key
    
    // Development & Debugging
    "DEBUG",                       // Enable debug mode (set to "true")
    "JIRA_MATE_DEBUG",             // Enable ticket-mate debug mode (set to "true")
    "NODE_ENV",                    // Node environment (development, production, test)
    "VERCEL_ENV",                  // Vercel environment
    "VERCEL_URL",                  // Vercel deployment URL
  ],
} as const;

export type EnvVarName = typeof envSpec.required[number] | typeof envSpec.optional[number];

/**
 * Get description for an environment variable
 */
export function getEnvVarDescription(key: string): string {
  const descriptions: Record<string, string> = {
    // Required
    JIRA_BASE_URL: "Base URL for your Jira Cloud instance (e.g., https://pamcms.atlassian.net)",
    JIRA_EMAIL: "Atlassian account email used for API calls",
    JIRA_API_KEY: "Jira personal access token (192 characters). Generate at https://id.atlassian.com/manage-profile/security/api-tokens",
    
    // Optional - Auth (deprecated)
    JIRA_API_TOKEN: "DEPRECATED: Use JIRA_API_KEY instead (backward compatibility only)",
    ATLASSIAN_CLIENT_ID: "OAuth client ID from Atlassian app",
    ATLASSIAN_CLIENT_SECRET: "OAuth client secret from Atlassian app",
    JIRA_REDIRECT_URI: "OAuth redirect URI (defaults to http://localhost:4000/api/auth/jira/callback)",
    JIRA_SCOPES: "OAuth scopes (defaults to read:jira-work write:jira-work read:jira-user offline_access)",
    
    // Optional - Project
    JIRA_PROJECT_KEY: "Default project key (e.g., NOVA)",
    JIRA_DEFAULT_REPORTER: "Default reporter email/accountId for ticket creation",
    JIRA_AUTOMATION_EMAIL: "Automation user email (e.g., cursor.automation@domain.com)",
    JIRA_AUTO_WORK_ASSIGNEE: "Default assignee for automation (defaults to cursor.automation)",
    
    // Optional - Cloud API (PAT mode only)
    JIRA_CLOUD_ID: "Optional: Atlassian cloud ID (for PAT mode Cloud API calls only; OAuth mode stores this in DB, not env)",
    JIRA_USE_CLOUD_API: "Optional: Use cloud API URL (set to 'true' for PAT mode scoped tokens)",
    JIRA_AUTH_MODE: "Optional: Explicit auth mode ('PAT' or 'OAUTH', defaults to PAT if not set)",
    
    // Optional - Webhooks
    JIRA_WEBHOOK_SECRET: "Secret for validating Jira webhooks",
    NEXT_PUBLIC_APP_URL: "Public app URL (for webhooks, defaults to http://localhost:4000)",
    
    // Optional - Frontend
    NEXT_PUBLIC_JIRA_BASE_URL: "Public Jira base URL (exposed to browser)",
    NEXT_PUBLIC_JIRA_MATE_API_KEY: "Public API key for frontend API calls",
  };
  
  return descriptions[key] || "See documentation for details";
}