Fix web templates, multi-word search, suggest prioritization, and log pollution

[Copilot]

Description

Resolves 6 issues: web interface template loading failures, multi-word package search not finding matches, suggest command showing wrong results for common queries like "coding", and noisy error logs from unavailable package managers.

Related Issue

Changes Made

Web Interface Template Fix

• Added templates/*.html and templates/**/* to pyproject.toml package-data
• Set explicit template folder path in web.py using os.path.join(base_dir, 'templates')

Multi-word Search Query Normalization

• Added normalize_query() function generating 3 variations per query:
  • Original: "jellyfin media player"
  • Hyphenated: "jellyfin-media-player"
  • Concatenated: "jellyfinmediaplayer"
• Search function now tries all variations, deduplicates results

Suggest Command Prioritization

• Reordered popular_apps for code-editor intent: code, vscode, vscodium now first
• Increased popular app scoring bonus from +40 to +60 points

Clean Console Output

• Changed log level from ERROR to DEBUG for "command not found" in:
  • search_snap.py line 54
  • search_flatpak.py line 53
• Users now see only: "Note: Some sources unavailable: Snap"

Enhanced Help Message

• Updated CLI callback docstring with comprehensive usage guide
• Added sections: Search, Suggest, Web, Updates, Config, Service, Distributions

Screenshots or GIFs (if applicable)

N/A - CLI/backend changes

Checklist

• Code is formatted with the project's Prettier config provided in .prettierrc (if present).
• Only the necessary files are modified; no unrelated changes are included.
• Follows clean code principles (readable, maintainable, minimal duplication).
• All changes are clearly documented.
• Code has been tested (manual/automated) and verified against edge cases.
• No breaking changes are introduced to existing functionality.
• All new and existing tests passed (if tests exist).

Additional Notes

Example: Multi-word search normalization

# Before: "jellyfin media player" → no results
# After: Tries 3 variations automatically
normalize_query("jellyfin media player")
# → ["jellyfin media player", "jellyfin-media-player", "jellyfinmediaplayer"]

Security: CodeQL scan passed with 0 alerts. All changes are backward compatible.

Original prompt

Comprehensive Fix for Multiple Issues

Issue 1: Web Interface Template Error

Error: jinja2.exceptions.TemplateNotFound: home.html

Root Cause:

1. pyproject.toml doesn't include HTML templates in package-data
2. web.py doesn't specify explicit template folder path

Fix in pyproject.toml:

[tool.setuptools.package-data]
archpkg = ["*.yaml", "*.yml", "*.json", "templates/*.html", "templates/**/*"]

Fix in archpkg/web.py:

import os

base_dir = os.path.dirname(os.path.abspath(__file__))
template_dir = os.path.join(base_dir, 'templates')

app = Flask(__name__, template_folder=template_dir)

---

Issue 2: Add archpkg web Command

The web interface exists but there's no CLI command to launch it.

Add to cli.py:

@app.command()
def web(
    port: int = Option(5000, "--port", "-p", help="Port to run web server on"),
    host: str = Option("127.0.0.1", "--host", help="Host to bind to"),
    debug: bool = Option(False, "--debug", help="Enable debug mode")
) -> None:
    """Launch the web interface for package management."""
    from archpkg.web import app as flask_app
    console.print(f"[bold cyan]🌐 Starting web interface at http://{host}:{port}[/bold cyan]")
    console.print("[dim]Press Ctrl+C to stop the server[/dim]")
    flask_app.run(host=host, port=port, debug=debug)

---

Issue 3: Suggest Shows Wrong First Result

When user searches "coding", neovim-qt appears first instead of code/vscode/vscodium.

Root Cause: The scoring algorithm in suggest.py doesn't properly prioritize popular/mainstream apps.

Fix: Add priority boost for popular apps in the suggest module:

# Popular apps that should be prioritized for common intents
POPULAR_APPS = {
    "code editor": ["code", "vscodium", "visual-studio-code-bin", "neovim", "vim"],
    "coding": ["code", "vscodium", "visual-studio-code-bin", "neovim", "vim"],
    "ide": ["code", "vscodium", "intellij-idea-community-edition", "pycharm-community-edition"],
    # ... more mappings
}

And boost scores for these apps when they match the detected intent.

---

Issue 4: Multi-word Search Doesn't Find Packages

archpkg search jellyfin media player finds nothing, but jellyfin-media-player works.

Root Cause: The search algorithm doesn't try variations of the query (with hyphens, without spaces, etc.)

Fix: Add query normalization to try multiple variations:

def normalize_query(query: str) -> List[str]:
    """Generate query variations for better matching."""
    variations = [query]
    
    # Add hyphenated version: "jellyfin media player" -> "jellyfin-media-player"
    if ' ' in query:
        variations.append(query.replace(' ', '-'))
    
    # Add concatenated version: "jellyfin media player" -> "jellyfinmediaplayer"
    if ' ' in query:
        variations.append(query.replace(' ', ''))
    
    return variations

Then search for all variations and combine results.

---

Issue 5: Snap/Flatpak Errors Pollute Output

When Snap isn't installed, users see error messages:

2025-12-09 13:02:04 - archpkg.search_snap - ERROR - search_snap:54 - snap command not found

Fix: Suppress these logs from console output while still logging to file:

1. Don't print package manager errors to console if the package manager isn't installed
2. Only show the summary "Note: Some sources unavailable: Snap" which is already there
3. Change log level from ERROR to DEBUG for "not found" cases

---

Issue 6: Enhanced Help Message

Combine the original comprehensive help with new features from PR #66.

Add to CLI callback or help command:

🎯 ArchPkg Helper - Universal Package Manager for All Linux Distros

📦 What does it do?
   Searches and installs packages across multiple sources:
   ✓ Official repos (pacman, apt, dnf, zypper)
   ✓ AUR (Arch User Repository)
   ✓ Flatpak & Snap (works on any distro)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 SEARCH FOR PACKAGES
   archpkg search <package-name>
   archpkg <package-name>             (search is default)
   
   Examples:
   🔸 archpkg firefox
   🔸 archpkg visual studio code
   🔸 archpkg search telegram
   
   Options:
   --aur              Prefer AUR packages over official repos
   --no-cache         Skip cache, search fresh results
   --limit, -l        Maximum results to show (default: 5)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 GET APP SUGGESTIONS BY PURPOSE
   archpkg suggest <purpose>
   
   Examples:
   🔸 archpkg suggest video editing
   🔸 archpkg suggest coding
   🔸 archpkg suggest gaming
   
   --list             Show all available purposes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌐 WEB INTERFACE
   archpkg web                        Launch web UI
   archpkg web --port 8080            Use custom port

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 PACKAGE TRACKING & UPDATES
   archpkg lis...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created as a result of the following prompt from Copilot chat.*
> ## Comprehensive Fix for Multiple Issues
> 
> ### Issue 1: Web Interface Template Error
> **Error:** `jinja2.exceptions.TemplateNotFound: home.html`
> 
> **Root Cause:** 
> 1. `pyproject.toml` doesn't include HTML templates in package-data
> 2. `web.py` doesn't specify explicit template folder path
> 
> **Fix in `pyproject.toml`:**
> ```toml
> [tool.setuptools.package-data]
> archpkg = ["*.yaml", "*.yml", "*.json", "templates/*.html", "templates/**/*"]
> ```
> 
> **Fix in `archpkg/web.py`:**
> ```python
> import os
> 
> base_dir = os.path.dirname(os.path.abspath(__file__))
> template_dir = os.path.join(base_dir, 'templates')
> 
> app = Flask(__name__, template_folder=template_dir)
> ```
> 
> ---
> 
> ### Issue 2: Add `archpkg web` Command
> The web interface exists but there's no CLI command to launch it.
> 
> **Add to `cli.py`:**
> ```python
> @app.command()
> def web(
>     port: int = Option(5000, "--port", "-p", help="Port to run web server on"),
>     host: str = Option("127.0.0.1", "--host", help="Host to bind to"),
>     debug: bool = Option(False, "--debug", help="Enable debug mode")
> ) -> None:
>     """Launch the web interface for package management."""
>     from archpkg.web import app as flask_app
>     console.print(f"[bold cyan]🌐 Starting web interface at http://{host}:{port}[/bold cyan]")
>     console.print("[dim]Press Ctrl+C to stop the server[/dim]")
>     flask_app.run(host=host, port=port, debug=debug)
> ```
> 
> ---
> 
> ### Issue 3: Suggest Shows Wrong First Result
> When user searches "coding", `neovim-qt` appears first instead of `code`/`vscode`/`vscodium`.
> 
> **Root Cause:** The scoring algorithm in `suggest.py` doesn't properly prioritize popular/mainstream apps.
> 
> **Fix:** Add priority boost for popular apps in the suggest module:
> ```python
> # Popular apps that should be prioritized for common intents
> POPULAR_APPS = {
>     "code editor": ["code", "vscodium", "visual-studio-code-bin", "neovim", "vim"],
>     "coding": ["code", "vscodium", "visual-studio-code-bin", "neovim", "vim"],
>     "ide": ["code", "vscodium", "intellij-idea-community-edition", "pycharm-community-edition"],
>     # ... more mappings
> }
> ```
> 
> And boost scores for these apps when they match the detected intent.
> 
> ---
> 
> ### Issue 4: Multi-word Search Doesn't Find Packages
> `archpkg search jellyfin media player` finds nothing, but `jellyfin-media-player` works.
> 
> **Root Cause:** The search algorithm doesn't try variations of the query (with hyphens, without spaces, etc.)
> 
> **Fix:** Add query normalization to try multiple variations:
> ```python
> def normalize_query(query: str) -> List[str]:
>     """Generate query variations for better matching."""
>     variations = [query]
>     
>     # Add hyphenated version: "jellyfin media player" -> "jellyfin-media-player"
>     if ' ' in query:
>         variations.append(query.replace(' ', '-'))
>     
>     # Add concatenated version: "jellyfin media player" -> "jellyfinmediaplayer"
>     if ' ' in query:
>         variations.append(query.replace(' ', ''))
>     
>     return variations
> ```
> 
> Then search for all variations and combine results.
> 
> ---
> 
> ### Issue 5: Snap/Flatpak Errors Pollute Output
> When Snap isn't installed, users see error messages:
> ```
> 2025-12-09 13:02:04 - archpkg.search_snap - ERROR - search_snap:54 - snap command not found
> ```
> 
> **Fix:** Suppress these logs from console output while still logging to file:
> 1. Don't print package manager errors to console if the package manager isn't installed
> 2. Only show the summary "Note: Some sources unavailable: Snap" which is already there
> 3. Change log level from ERROR to DEBUG for "not found" cases
> 
> ---
> 
> ### Issue 6: Enhanced Help Message
> Combine the original comprehensive help with new features from PR #66.
> 
> **Add to CLI callback or help command:**
> ```
> 🎯 ArchPkg Helper - Universal Package Manager for All Linux Distros
> 
> 📦 What does it do?
>    Searches and installs packages across multiple sources:
>    ✓ Official repos (pacman, apt, dnf, zypper)
>    ✓ AUR (Arch User Repository)
>    ✓ Flatpak & Snap (works on any distro)
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 🔍 SEARCH FOR PACKAGES
>    archpkg search <package-name>
>    archpkg <package-name>             (search is default)
>    
>    Examples:
>    🔸 archpkg firefox
>    🔸 archpkg visual studio code
>    🔸 archpkg search telegram
>    
>    Options:
>    --aur              Prefer AUR packages over official repos
>    --no-cache         Skip cache, search fresh results
>    --limit, -l        Maximum results to show (default: 5)
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 💡 GET APP SUGGESTIONS BY PURPOSE
>    archpkg suggest <purpose>
>    
>    Examples:
>    🔸 archpkg suggest video editing
>    🔸 archpkg suggest coding
>    🔸 archpkg suggest gaming
>    
>    --list             Show all available purposes
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 🌐 WEB INTERFACE
>    archpkg web                        Launch web UI
>    archpkg web --port 8080            Use custom port
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 📦 PACKAGE TRACKING & UPDATES
>    archpkg list-installed             List tracked packages
>    archpkg update                     Install updates
>    archpkg update --check-only        Only check for updates
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> ⚙️ CONFIGURATION
>    archpkg config --list              Show all settings
>    archpkg config <key> <value>       Set a config value
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 🔄 BACKGROUND SERVICE
>    archpkg service start|stop|status
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 📊 CACHE MANAGEMENT
>    --cache-stats                      Show cache statistics
>    --clear-cache all                  Clear all cached results
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 🔄 UPGRADE ARCHPKG
>    archpkg upgrade                    Get latest version from GitHub
> 
> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
> 
> 🌍 SUPPORTED DISTRIBUTIONS
>    Arch, Manjaro, EndeavourOS, Ubuntu, Debian, Fedora,
>    openSUSE, + any distro with Flatpak/Snap support
> ```
> 
> ---
> 
> ## Files to Modify
> 
> 1. **`pyproject.toml`** - Add templates to package-data
> 2. **`archpkg/web.py`** - Add explicit template folder path
> 3. **`archpkg/cli.py`** - Add `web` command and enhanced help
> 4. **`archpkg/suggest.py`** - Prioritize popular apps for common intents
> 5. **`archpkg/search_snap.py`** - Change "not found" log level to DEBUG
> 6. **`archpkg/search_flatpak.py`** - Change warning log level to DEBUG
> 7. **`archpkg/cli.py`** (search function) - Add query normalization to try hyphenated versions

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/AdmGenSameer/archpkg-helper/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.