nushell-plugins/justfiles/help.just

# 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 nushell + all plugins (alias for collect)"
            echo "  just il                  - Install plugin in nu from local distro (alias for install-local)"
            echo "  just is                  - Install to ~/.local/bin (alias for install-system)"
            echo "  just s                   - Show plugin status (alias for status)"
            echo "  just v                   - Verify plugins (alias for verify-plugins)"
            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 build-nushell       - Build nushell + system plugins"
            echo "  just build-full          - Build nushell + all plugins"
            echo "  just collect             - Collect nushell + all plugins"
            echo "  just collect-all         - Collect nushell + all plugins (all platforms)"
            echo "  just test                - Run all tests"
            echo "  just upstream-check      - Check for upstream changes"
            echo "  just pack-full           - Create complete distribution"
            echo "  just release-full-cross  - Full cross-platform release"
            echo ""
            echo "📦 Archive Creation Workflow:"
            echo "  just build-full                       - Build nushell + all plugins"
            echo "  just collect-full                     - Collect to distribution/"
            echo "  just create-distribution              - Create archives in bin_archives/"
            echo ""
            echo "📦 Version Update Commands (v0.108.0+):"
            echo "  just complete-update VERSION          - All-in-one Nushell update"
            echo "  just update-help                      - Show all update commands"
            echo "  just commands                         - Show all commands by group"
            ;;
        "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, collect-all, pack, release-*"
            echo "  Help: just distro-help"
            echo "  Purpose: Collection and packaging (UPDATED: now includes nushell + system plugins)"
            echo ""
            echo "🚀 FULL DISTRIBUTION MODULE"
            echo "  Commands: build-full*, pack-full*, release-full*"
            echo "  Help: just full-help"
            echo "  Purpose: Complete Nushell distributions with zero prerequisites"
            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 "🔄 VERSION UPDATE MODULE"
            echo "  Commands: complete-update, update-plugins, analyze-features, detect-breaking, etc."
            echo "  Help: just update-help"
            echo "  Purpose: Nushell version management and updates"
            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 "🚀 ARCHIVE CREATION WORKFLOW:"
            echo "1. Build everything:"
            echo "   just build-full              # Build nushell + all plugins"
            echo ""
            echo "2. Collect binaries:"
            echo "   just collect-full            # Collect to distribution/"
            echo ""
            echo "3. Create archives:"
            echo "   just create-distribution     # Create nushell-full + plugins-only archives"
            echo ""
            echo "📤 FULL DISTRIBUTION WORKFLOW:"
            echo "1. Build and create archives:"
            echo "   just build-full && just collect-full && just create-distribution"
            echo ""
            echo "2. Cross-platform release:"
            echo "   just release-full-cross      # Build for all platforms"
            echo ""
            echo "3. End-user installation:"
            echo "   curl -sSf https://your-url/install.sh | sh"
            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 of plugins"
    @echo "   Commands: collect, pack, release-*"
    @echo "   Help: just distro-help"
    @echo ""
    @echo "🚀 FULL DISTRIBUTION MODULE (justfiles/full_distro.just)"
    @echo "   Complete Nushell distributions with zero prerequisites"
    @echo "   Commands: build-full*, pack-full*, release-full*"
    @echo "   Help: just full-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 "🔄 VERSION UPDATE MODULE (justfiles/version_update.just)"
    @echo "   Nushell version management and updates"
    @echo "   Commands: complete-update, update-plugins, analyze-features, detect-breaking"
    @echo "   Help: just update-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 full-help
    @echo ""
    @just upstream-help
    @echo ""
    @just qa-help
    @echo ""
    @just tools-help
    @echo ""
    @just update-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             - Plugin distribution commands"
    @echo "  just full-help               - Full distribution commands"
    @echo "  just upstream-help           - Upstream module commands"
    @echo "  just qa-help                 - QA module commands"
    @echo "  just tools-help              - Tools module commands"
    @echo "  just update-help             - Version update module commands"

# Show all available commands by group (alias for --list)
[no-cd]
commands:
    @just --list