# Module: Help System Dispatcher
# Purpose: Routes help requests to appropriate category handlers and resolves documentation URLs.
# Dependencies: help_system_categories

# Help System Core - Dispatcher and URL Resolution
# Routes help requests to category-specific help handlers

use platform/config/accessor.nu *

# Import all help category functions
# BROKEN: file not found — use ./help_system_categories.nu *

# Resolve documentation URL with local fallback
export def resolve-doc-url [doc_path: string] {
    let config = (load-config)
    let mdbook_enabled = ($config.documentation?.mdbook_enabled? | default false)
    let mdbook_base = ($config.documentation?.mdbook_base_url? | default "")
    let docs_root = ($config.documentation?.docs_root? | default "docs/src")

    if $mdbook_enabled and ($mdbook_base | str length) > 0 {
        # Return both URL and local path
        {
            url: $"($mdbook_base)/($doc_path).html"
            local: $"provisioning/($docs_root)/($doc_path).md"
            mode: "url"
        }
    } else {
        # Use local files only
        {
            url: null
            local: $"provisioning/($docs_root)/($doc_path).md"
            mode: "local"
        }
    }
}

# Main help dispatcher
export def provisioning-help [
    category?: string  # Optional category: infrastructure, orchestration, development, workspace, platform, auth, plugins, utilities, concepts, guides, integrations, build
] {
    # If no category provided, show main help
    if ($category == null) or ($category == "") {
        return (help-main)
    }

    # Try to match the category
    let result = (match $category {
        "infrastructure" | "infra" => "infrastructure"
        "orchestration" | "orch" => "orchestration"
        "development" | "dev" => "development"
        "workspace" | "ws" => "workspace"
        "platform" | "plat" => "platform"
        "setup" | "st" => "setup"
        "authentication" | "auth" => "authentication"
        "mfa" => "mfa"
        "plugins" | "plugin" => "plugins"
        "utilities" | "utils" | "cache" => "utilities"
        "tools" => "tools"
        "vm" => "vm"
        "diagnostics" | "diag" | "status" | "health" => "diagnostics"
        "concepts" | "concept" => "concepts"
        "guides" | "guide" | "howto" => "guides"
        "integrations" | "integration" | "int" => "integrations"
        "build" | "bi" | "build-image" => "build"
        _ => "unknown"
    })

    # If unknown category, show error
    if $result == "unknown" {
        print $"❌ Unknown help category: \"($category)\"\n"
        print "Available help categories:"
        print "  infrastructure [infra]  - Server, taskserv, cluster, VM management"
        print "  orchestration [orch]    - Workflow, batch operations"
        print "  development [dev]       - Module system, layers, versioning"
        print "  workspace [ws]          - Workspace and template management"
        print "  setup [st]              - System setup, configuration, initialization"
        print "  platform [plat]         - Orchestrator, Control Center, MCP"
        print "  authentication [auth]   - JWT authentication, MFA, sessions"
        print "  mfa                     - Multi-Factor Authentication details"
        print "  plugins [plugin]        - Plugin management"
        print "  utilities [utils]       - Cache, SOPS, providers, SSH"
        print "  tools                   - Tool and dependency management"
        print "  vm                      - Virtual machine operations"
        print "  diagnostics [diag]      - System status, health checks"
        print "  concepts [concept]      - Architecture and key concepts"
        print "  guides [guide]          - Quick guides and cheatsheets"
        print "  integrations [int]      - Prov-ecosystem and provctl bridge"
        print "  build [bi]              - Role image build, state, and watch\n"
        print "Use 'provisioning help' for main help"
        exit 1
    }

    # Match valid category
    match $result {
        "infrastructure" => (help-infrastructure)
        "orchestration" => (help-orchestration)
        "development" => (help-development)
        "workspace" => (help-workspace)
        "platform" => (help-platform)
        "setup" => (help-setup)
        "authentication" => (help-authentication)
        "mfa" => (help-mfa)
        "plugins" => (help-plugins)
        "utilities" => (help-utilities)
        "tools" => (help-tools)
        "vm" => (help-vm)
        "diagnostics" => (help-diagnostics)
        "concepts" => (help-concepts)
        "guides" => (help-guides)
        "integrations" => (help-integrations)
        "build" => (help-build)
        _ => (help-main)
    }
}