# Help Module - Comprehensive Help System
# Organized help areas with navigation and guidance

# Show help system with optional area argument
[no-cd]
help AREA="":
    #!/usr/bin/env bash
    case "{{AREA}}" in
        "")
            # Default basic help overview
            echo "🚀 Nushell Plugins Development Environment"
            echo "========================================"
            echo ""
            echo "📋 HELP AREAS - Use: just help <area>"
            echo "======================================"
            echo ""
            echo "  modules      - Available modules and their commands"
            echo "  status       - Status and information commands"
            echo "  get-started  - Getting started guide"
            echo "  docs         - Documentation and resources"
            echo ""
            echo "💡 QUICK ACCESS:"
            echo "==============="
            echo "  just h <area>            - Short alias for help"
            echo "  just b                   - Build all plugins (alias for build)"
            echo "  just c                   - Collect all plugins targets (alias for collect)"
            echo "  just s                   - Show plugin status (alias for status)"
            echo "  just validate-nushell    - Check version consistency (START HERE)"
            echo "  just dev-flow            - Complete development workflow"
            echo ""
            echo "🔧 Most Common Commands:"
            echo "======================="
            echo "  just build               - Build all plugins"
            echo "  just test                - Run all tests"
            echo "  just upstream-check      - Check for upstream changes"
            echo "  just release-cross       - Cross-platform release"
            ;;
        "modules")
            echo "📋 AVAILABLE MODULES"
            echo "==================="
            echo ""
            echo "🔨 BUILD MODULE"
            echo "  Commands: build, build-cross, build-docker-*"
            echo "  Help: just build-help"
            echo "  Purpose: Native and cross-platform compilation"
            echo ""
            echo "📦 DISTRIBUTION MODULE"
            echo "  Commands: collect, pack, release-*"
            echo "  Help: just distro-help"
            echo "  Purpose: Collection and packaging of built plugins"
            echo ""
            echo "🔄 UPSTREAM MODULE"
            echo "  Commands: upstream-*, status-*"
            echo "  Help: just upstream-help"
            echo "  Purpose: Repository tracking and synchronization"
            echo ""
            echo "🧪 QA MODULE"
            echo "  Commands: test, lint, fmt, audit, qa-*"
            echo "  Help: just qa-help"
            echo "  Purpose: Testing, linting, and code quality"
            echo ""
            echo "🛠️ TOOLS MODULE"
            echo "  Commands: validate-*, make-plugin, interactive"
            echo "  Help: just tools-help"
            echo "  Purpose: Development tools and utilities"
            echo ""
            echo "💡 TIP: Use 'just <module>-help' for detailed commands in each module"
            ;;
        "status" | "info")
            echo "📊 STATUS & INFORMATION COMMANDS"
            echo "================================"
            echo ""
            echo "🔍 System Status:"
            echo "  just status              - Plugin status dashboard"
            echo "  just status-all          - Detailed status for all plugins"
            echo "  just status-attention    - Plugins requiring attention"
            echo "  just system-info         - System information"
            echo "  just validate            - Validate setup and dependencies"
            echo ""
            echo "📋 Project Information:"
            echo "  just modules             - List all available modules"
            echo "  just list-plugins        - List all plugins"
            echo "  just stats               - Project statistics"
            echo "  just config-list         - Show configuration files"
            echo ""
            echo "🔧 Version Management:"
            echo "  just validate-nushell    - Check nushell version consistency"
            echo "  just list-nu-versions    - List current nu dependency versions"
            echo "  just build-targets       - List available build targets"
            ;;
        "get-started" | "start")
            echo "💡 GETTING STARTED GUIDE"
            echo "========================"
            echo ""
            echo "🚀 FIRST TIME SETUP:"
            echo "1. Validate your environment:"
            echo "   just validate                # Check tools and setup"
            echo "   just validate-nushell        # Check version consistency (CRITICAL)"
            echo ""
            echo "2. Check project status:"
            echo "   just status                  # See plugin status dashboard"
            echo "   just upstream-check          # Check for upstream changes"
            echo ""
            echo "📅 DAILY DEVELOPMENT WORKFLOW:"
            echo "1. Run the development workflow:"
            echo "   just dev-flow                # validate → upstream → build → test → status"
            echo ""
            echo "2. Or run individual steps:"
            echo "   just validate-nushell        # Always start here"
            echo "   just upstream-check          # Check for updates"
            echo "   just b                       # Build all plugins (short alias)"
            echo "   just test                    # Run tests"
            echo ""
            echo "🌍 CROSS-PLATFORM BUILD:"
            echo "1. See available platforms:"
            echo "   just build-targets           # List supported platforms"
            echo ""
            echo "2. Build for all platforms:"
            echo "   just release-cross           # Full cross-platform release"
            echo ""
            echo "🆘 NEED HELP?"
            echo "  just help modules            # See all available modules"
            echo "  just build-help              # Build-specific commands"
            echo "  just qa-help                 # Testing and quality commands"
            ;;
        "docs" | "documentation")
            echo "📚 DOCUMENTATION & RESOURCES"
            echo "============================"
            echo ""
            echo "📖 Main Documentation:"
            echo "  docs/BUILDING.md             - Complete build documentation"
            echo "  README.md                    - Project overview"
            echo ""
            echo "⚙️ Configuration Files:"
            echo "  etc/plugin_registry.toml     - Plugin tracking configuration"
            echo "  etc/build_targets.toml       - Cross-compilation targets"
            echo "  etc/upstream_exclude.toml    - Upstream exclusion rules"
            echo ""
            echo "🔧 Auto-Generated Documentation:"
            echo "  just docs                    - Generate Rust documentation"
            echo "  just docs-open PLUGIN        - Open plugin docs in browser"
            echo ""
            echo "💡 Examples & Help:"
            echo "  just help modules            - Module overview"
            echo "  just help get-started        - Getting started guide"
            echo "  just <module>-help           - Detailed module help"
            echo ""
            echo "🌐 Online Resources:"
            echo "  Nushell: https://nushell.sh"
            echo "  Rust: https://rust-lang.org"
            echo "  Just: https://github.com/casey/just"
            ;;
        *)
            echo "❌ Unknown help area: {{AREA}}"
            echo ""
            echo "Available help areas:"
            echo "  modules      - Available modules and commands"
            echo "  status       - Status and information commands"
            echo "  get-started  - Getting started guide"
            echo "  docs         - Documentation and resources"
            echo ""
            echo "Usage: just help [area]"
            echo "       just h [area]     # Short alias"
            ;;
    esac

# List all available modules
[no-cd]
modules:
    @echo "📋 Available Justfile Modules:"
    @echo "============================="
    @echo ""
    @echo "🔨 BUILD MODULE (justfiles/build.just)"
    @echo "   Native and cross-platform compilation"
    @echo "   Commands: build, build-cross, build-docker-*"
    @echo "   Help: just build-help"
    @echo ""
    @echo "📦 DISTRIBUTION MODULE (justfiles/distro.just)"
    @echo "   Collection and packaging"
    @echo "   Commands: collect, pack, release-*"
    @echo "   Help: just distro-help"
    @echo ""
    @echo "🔄 UPSTREAM MODULE (justfiles/upstream.just)"
    @echo "   Repository tracking and synchronization"
    @echo "   Commands: upstream-*, status-*"
    @echo "   Help: just upstream-help"
    @echo ""
    @echo "🧪 QA MODULE (justfiles/qa.just)"
    @echo "   Testing, linting, and code quality"
    @echo "   Commands: test, lint, fmt, audit, qa-*"
    @echo "   Help: just qa-help"
    @echo ""
    @echo "🛠️ TOOLS MODULE (justfiles/tools.just)"
    @echo "   Development tools and utilities"
    @echo "   Commands: validate-*, make-plugin, interactive"
    @echo "   Help: just tools-help"
    @echo ""
    @echo "🎯 ALIAS MODULE (justfiles/alias.just)"
    @echo "   Quick access shortcuts"
    @echo "   Aliases: h (help), b (build), s (status)"
    @echo ""
    @echo "🆘 HELP MODULE (justfiles/help.just)"
    @echo "   Comprehensive help system"
    @echo "   Commands: help, modules"

# Quick access to all module help commands
[no-cd]
help-all:
    @echo "📚 Complete Help for All Modules"
    @echo "================================"
    @echo ""
    @just build-help
    @echo ""
    @just distro-help
    @echo ""
    @just upstream-help
    @echo ""
    @just qa-help
    @echo ""
    @just tools-help

# List all available commands across all modules
[no-cd]
list-all:
    @echo "📋 All Available Commands:"
    @echo "========================="
    @echo ""
    @echo "Use 'just --list' to see all commands, or:"
    @echo "  just help                    - Main help with module overview"
    @echo "  just modules                 - List all modules"
    @echo "  just help-all                - Complete help for all modules"
    @echo ""
    @echo "Module-specific help:"
    @echo "  just build-help              - Build module commands"
    @echo "  just distro-help             - Distribution module commands"
    @echo "  just upstream-help           - Upstream module commands"
    @echo "  just qa-help                 - QA module commands"
    @echo "  just tools-help              - Tools module commands"