how-cli 0.2.0__tar.gz → 0.3.0__tar.gz

how_cli-0.3.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: how-cli
+Version: 0.3.0
+Summary: An AI-based CLI assistant to help you with command line & shell.
+Home-page: https://github.com/FireHead90544/how-cli
+Author: Rudransh Joshi (FireHead90544)
+Author-email: rudranshjoshi1806@gmail.com
+License: MIT
+Project-URL: Issue Tracker, https://github.com/FireHead90544/how-cli/issues
+Platform: any
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: langchain
+Requires-Dist: langchain-google-genai
+Requires-Dist: langchain-google-vertexai
+Requires-Dist: langchain-groq
+Requires-Dist: langchain-openai
+Requires-Dist: langchain-anthropic
+Requires-Dist: langchain-ollama
+Requires-Dist: pyperclip
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
+
+# how-cli
+An AI-based CLI assistant to help you with command line & shell.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Demo 
+https://github.com/user-attachments/assets/effefe1a-c0ed-4b60-838c-98f992f6c25f
+
+## Features
+
+- ⚡ **Deferred & Lazy LLM Initialization**: Zero heavy imports during `--help` or startup, preventing startup crashes.
+- 🦙 **Local LLM Support (Ollama)**: Run 100% offline with Ollama models (`qwen2.5-coder`, `llama3.2`, etc.) with no API keys required.
+- 🎯 **Intelligent Environment & Project Context**: Automatically detects your active shell, available package managers (`apt`, `brew`, `dnf`, `pacman`, etc.), and project root markers (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Dockerfile`).
+- 🛡️ **Safety Guardrails**: Heuristic pattern detection warns against destructive commands (`rm -rf`, `dd if=`, `mkfs`, `> /dev/sd`, `chmod -R 777`, `git reset --hard`, `git push --force`, fork bombs, curl-pipe-to-shell) and gates execution with an explicit confirmation phrase.
+- 📋 **Interactive Action Menu & Clipboard**:
+  - `[E]xecute`: Safely runs generated commands step-by-step, halting on non-zero exits.
+  - `[C]opy`: Copies commands directly to your system clipboard via `pyperclip`.
+  - `[M]odify`: Lets you edit commands inline before executing.
+  - `[A]bort`: Cleanly exits with status 0.
+- 🔧 **`how fix` Diagnostic Command**: Inspects the last failed shell command from history or stderr and diagnoses fixes.
+
+---
+
+## Installation
+
+**1. Using `pip`**
+```bash
+pip install -U how-cli
+```
+
+**2. Manual Installation**
+```bash
+git clone https://github.com/FireHead90544/how-cli.git && cd how-cli
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+---
+
+## Usage
+
+```console
+$ how [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+* `-v, --version`: Shows the version of the application.
+* `--help`: Show help message and exit.
+
+**Commands**:
+* `setup`: Sets up the LLM provider, API key, custom model, or local endpoint.
+* `to`: Sends a task description to the LLM and returns the commands.
+* `fix`: Diagnoses the last failed command from shell history or stderr.
+
+---
+
+## `how setup`
+
+Configure your preferred LLM provider. Supports both cloud providers (OpenAI, Anthropic, Google, Groq) and local models via Ollama.
+
+**Interactive Mode**:
+```bash
+how setup
+```
+
+**Non-Interactive Mode**:
+```bash
+# Using local Ollama (no API key needed!)
+how setup --no-interactive --provider Ollama --model qwen2.5-coder:latest --endpoint http://localhost:11434
+
+# Using OpenAI
+how setup --no-interactive --provider OpenAI --api-key "sk-..." --model gpt-4o
+
+# Using Groq
+how setup --no-interactive --provider GroqLLaMa --api-key "gsk_..."
+```
+
+---
+
+## `how to`
+
+Translates a natural language query into concrete shell commands tailored to your system and project.
+
+```bash
+how to "find all files larger than 100MB"
+how to "install dependencies"
+```
+
+After commands are generated, the interactive action menu appears:
+```text
+Options: [E]xecute | [C]opy | [M]odify | [A]bort
+Select an action [e/c/m/a/E/C/M/A] (a):
+```
+
+### Safety Guardrails
+When a destructive command is detected (e.g. `rm -rf`, `git push --force`), `how` warns you with a prominent alert panel:
+```text
+╭─────────────────────────── SAFETY GUARDRAIL ALERT ───────────────────────────╮
+│ WARNING: Destructive or High-Risk Command(s) Detected!                       │
+│ • Recursive Force Delete: rm -rf node_modules                                │
+│   Permanently deletes files and directories recursively without              │
+│ confirmation.                                                                │
+│                                                                              │
+│ To prevent accidental damage, type the exact confirmation phrase:            │
+│ I UNDERSTAND THE RISKS                                                       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+Typing `y` is rejected; you must explicitly enter `I UNDERSTAND THE RISKS` before execution is permitted.
+
+---
+
+## `how fix`
+
+Diagnoses why your last command failed and suggests the fix.
+
+```bash
+# Automatically read the last failed command from ~/.bash_history or ~/.zsh_history:
+how fix
+
+# Provide the command and stderr explicitly:
+how fix -c "git push origin main" -e "error: failed to push some refs" -x 1
+```
+
+---
+
+## Providers
+
+| Provider | Default Model | Package | Requires Key | Tested |
+|:--------:|:-------------:|:-------:|:------------:|:------:|
+| **Ollama** (Local) | `qwen2.5-coder:latest` | `langchain-ollama` | ❌ No | ✅ |
+| GoogleGenAI | `gemma-4-31b-it` | `langchain-google-genai` | ✅ Yes | ✅ |
+| GoogleVertexAI | `gemma-4-31b-it` | `langchain-google-vertexai` | ✅ Yes | ❌ |
+| GroqMistralAI | `mixtral-8x7b-32768` | `langchain-groq` | ✅ Yes | ✅ |
+| GroqLLaMa | `qwen/qwen3.8-27b` | `langchain-groq` | ✅ Yes | ✅ |
+| OpenAI | `gpt-4o` | `langchain-openai` | ✅ Yes | ✅ |
+| Anthropic | `claude-3-5-sonnet-20240620` | `langchain-anthropic` | ✅ Yes | ✅ |
+
+---
+
+## Shell Integration
+
+You can bind `how to` directly to a keyboard shortcut (e.g. `Ctrl+G`) in your shell to immediately convert your typed command buffer into an AI prompt:
+
+### Zsh (`~/.zshrc`)
+```bash
+how-widget() {
+  BUFFER="how to \"$BUFFER\""
+  zle accept-line
+}
+zle -N how-widget
+bindkey '^G' how-widget
+```
+
+### Bash (`~/.bashrc`)
+```bash
+how-widget() {
+  local cmd="how to \"$READLINE_LINE\""
+  READLINE_LINE=""
+  eval "$cmd"
+}
+bind -x '"\C-g": how-widget'
+```
+
+---
+
+## License
+`how-cli` is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Honourable Mentions
+This project is inspired by [kynnyhsap's](https://github.com/kynnyhsap) [how](https://github.com/kynnyhsap/how).
+
+## Maintainers
+
+- [@FireHead90544](https://github.com/FireHead90544) — Creator & Primary Maintainer
+- [@ashishsinghbora](https://github.com/ashishsinghbora) — Contributor

how_cli-0.3.0/README.md

@@ -0,0 +1,176 @@
+# how-cli
+An AI-based CLI assistant to help you with command line & shell.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Demo 
+https://github.com/user-attachments/assets/effefe1a-c0ed-4b60-838c-98f992f6c25f
+
+## Features
+
+- ⚡ **Deferred & Lazy LLM Initialization**: Zero heavy imports during `--help` or startup, preventing startup crashes.
+- 🦙 **Local LLM Support (Ollama)**: Run 100% offline with Ollama models (`qwen2.5-coder`, `llama3.2`, etc.) with no API keys required.
+- 🎯 **Intelligent Environment & Project Context**: Automatically detects your active shell, available package managers (`apt`, `brew`, `dnf`, `pacman`, etc.), and project root markers (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Dockerfile`).
+- 🛡️ **Safety Guardrails**: Heuristic pattern detection warns against destructive commands (`rm -rf`, `dd if=`, `mkfs`, `> /dev/sd`, `chmod -R 777`, `git reset --hard`, `git push --force`, fork bombs, curl-pipe-to-shell) and gates execution with an explicit confirmation phrase.
+- 📋 **Interactive Action Menu & Clipboard**:
+  - `[E]xecute`: Safely runs generated commands step-by-step, halting on non-zero exits.
+  - `[C]opy`: Copies commands directly to your system clipboard via `pyperclip`.
+  - `[M]odify`: Lets you edit commands inline before executing.
+  - `[A]bort`: Cleanly exits with status 0.
+- 🔧 **`how fix` Diagnostic Command**: Inspects the last failed shell command from history or stderr and diagnoses fixes.
+
+---
+
+## Installation
+
+**1. Using `pip`**
+```bash
+pip install -U how-cli
+```
+
+**2. Manual Installation**
+```bash
+git clone https://github.com/FireHead90544/how-cli.git && cd how-cli
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+---
+
+## Usage
+
+```console
+$ how [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+* `-v, --version`: Shows the version of the application.
+* `--help`: Show help message and exit.
+
+**Commands**:
+* `setup`: Sets up the LLM provider, API key, custom model, or local endpoint.
+* `to`: Sends a task description to the LLM and returns the commands.
+* `fix`: Diagnoses the last failed command from shell history or stderr.
+
+---
+
+## `how setup`
+
+Configure your preferred LLM provider. Supports both cloud providers (OpenAI, Anthropic, Google, Groq) and local models via Ollama.
+
+**Interactive Mode**:
+```bash
+how setup
+```
+
+**Non-Interactive Mode**:
+```bash
+# Using local Ollama (no API key needed!)
+how setup --no-interactive --provider Ollama --model qwen2.5-coder:latest --endpoint http://localhost:11434
+
+# Using OpenAI
+how setup --no-interactive --provider OpenAI --api-key "sk-..." --model gpt-4o
+
+# Using Groq
+how setup --no-interactive --provider GroqLLaMa --api-key "gsk_..."
+```
+
+---
+
+## `how to`
+
+Translates a natural language query into concrete shell commands tailored to your system and project.
+
+```bash
+how to "find all files larger than 100MB"
+how to "install dependencies"
+```
+
+After commands are generated, the interactive action menu appears:
+```text
+Options: [E]xecute | [C]opy | [M]odify | [A]bort
+Select an action [e/c/m/a/E/C/M/A] (a):
+```
+
+### Safety Guardrails
+When a destructive command is detected (e.g. `rm -rf`, `git push --force`), `how` warns you with a prominent alert panel:
+```text
+╭─────────────────────────── SAFETY GUARDRAIL ALERT ───────────────────────────╮
+│ WARNING: Destructive or High-Risk Command(s) Detected!                       │
+│ • Recursive Force Delete: rm -rf node_modules                                │
+│   Permanently deletes files and directories recursively without              │
+│ confirmation.                                                                │
+│                                                                              │
+│ To prevent accidental damage, type the exact confirmation phrase:            │
+│ I UNDERSTAND THE RISKS                                                       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+Typing `y` is rejected; you must explicitly enter `I UNDERSTAND THE RISKS` before execution is permitted.
+
+---
+
+## `how fix`
+
+Diagnoses why your last command failed and suggests the fix.
+
+```bash
+# Automatically read the last failed command from ~/.bash_history or ~/.zsh_history:
+how fix
+
+# Provide the command and stderr explicitly:
+how fix -c "git push origin main" -e "error: failed to push some refs" -x 1
+```
+
+---
+
+## Providers
+
+| Provider | Default Model | Package | Requires Key | Tested |
+|:--------:|:-------------:|:-------:|:------------:|:------:|
+| **Ollama** (Local) | `qwen2.5-coder:latest` | `langchain-ollama` | ❌ No | ✅ |
+| GoogleGenAI | `gemma-4-31b-it` | `langchain-google-genai` | ✅ Yes | ✅ |
+| GoogleVertexAI | `gemma-4-31b-it` | `langchain-google-vertexai` | ✅ Yes | ❌ |
+| GroqMistralAI | `mixtral-8x7b-32768` | `langchain-groq` | ✅ Yes | ✅ |
+| GroqLLaMa | `qwen/qwen3.8-27b` | `langchain-groq` | ✅ Yes | ✅ |
+| OpenAI | `gpt-4o` | `langchain-openai` | ✅ Yes | ✅ |
+| Anthropic | `claude-3-5-sonnet-20240620` | `langchain-anthropic` | ✅ Yes | ✅ |
+
+---
+
+## Shell Integration
+
+You can bind `how to` directly to a keyboard shortcut (e.g. `Ctrl+G`) in your shell to immediately convert your typed command buffer into an AI prompt:
+
+### Zsh (`~/.zshrc`)
+```bash
+how-widget() {
+  BUFFER="how to \"$BUFFER\""
+  zle accept-line
+}
+zle -N how-widget
+bindkey '^G' how-widget
+```
+
+### Bash (`~/.bashrc`)
+```bash
+how-widget() {
+  local cmd="how to \"$READLINE_LINE\""
+  READLINE_LINE=""
+  eval "$cmd"
+}
+bind -x '"\C-g": how-widget'
+```
+
+---
+
+## License
+`how-cli` is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Honourable Mentions
+This project is inspired by [kynnyhsap's](https://github.com/kynnyhsap) [how](https://github.com/kynnyhsap/how).
+
+## Maintainers
+
+- [@FireHead90544](https://github.com/FireHead90544) — Creator & Primary Maintainer
+- [@ashishsinghbora](https://github.com/ashishsinghbora) — Contributor

how_cli-0.3.0/how/__init__.py

@@ -0,0 +1,3 @@
+from how.core import __author__, __version__
+
+__all__ = ["__author__", "__version__"]

how_cli-0.3.0/how/actions.py

@@ -0,0 +1,182 @@
+import contextlib
+import subprocess
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from how.core.safety import assess_risk
+
+console = Console()
+
+CONFIRMATION_PHRASE = "I UNDERSTAND THE RISKS"
+
+
+def check_safety_gate(commands: list[str]) -> bool:
+    """
+    Check if commands contain destructive patterns. If so, display a bold
+    warning panel and require an exact confirmation phrase.
+    """
+    flags = assess_risk(commands)
+    if not flags:
+        return True
+
+    warning_text = "[bold red]WARNING: Destructive or High-Risk Command(s) Detected![/bold red]\n\n"
+    for flag in flags:
+        warning_text += (
+            f"• [bold yellow]{flag.rule_name}[/bold yellow]: [bold white]{flag.command}[/bold white]\n"
+            f"  {flag.description}\n"
+        )
+    warning_text += (
+        f"\nTo prevent accidental damage, type the exact confirmation phrase:\n"
+        f"[bold white]{CONFIRMATION_PHRASE}[/bold white]"
+    )
+
+    console.print(
+        Panel(
+            warning_text,
+            title="[bold red]SAFETY GUARDRAIL ALERT[/bold red]",
+            border_style="red",
+        )
+    )
+
+    try:
+        user_input = Prompt.ask("Confirmation phrase")
+        if user_input.strip() != CONFIRMATION_PHRASE:
+            console.print(
+                "[yellow]Confirmation phrase mismatch. Execution blocked.[/yellow]"
+            )
+            return False
+        return True
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Execution blocked.[/yellow]")
+        return False
+
+
+def copy_to_clipboard(commands: list[str]) -> bool:
+    """Copy commands to clipboard via pyperclip."""
+    joined = "\n".join(commands)
+    try:
+        import pyperclip
+
+        pyperclip.copy(joined)
+        console.print("[bold green]✓ Commands copied to clipboard![/bold green]")
+        return True
+    except Exception as e:  # noqa: BLE001
+        console.print(
+            f"[yellow]! Clipboard copy failed: {e}. "
+            "Please ensure xclip, xsel, or wl-clipboard is installed.[/yellow]"
+        )
+        return False
+
+
+def execute_commands(commands: list[str]) -> int:
+    """
+    Run commands sequentially via subprocess.run(cmd, shell=True)
+    after confirmation and safety verification.
+    """
+    if not commands:
+        return 0
+
+    if not check_safety_gate(commands):
+        return 1
+
+    if not typer.confirm("Are you sure you want to execute these commands?"):
+        console.print("[yellow]Execution cancelled.[/yellow]")
+        return 0
+
+    for idx, cmd in enumerate(commands, start=1):
+        console.print(f"\n[bold cyan]({idx}/{len(commands)}) $ {cmd}[/bold cyan]")
+        try:
+            proc = subprocess.run(cmd, shell=True, check=False)
+            if proc.returncode != 0:
+                console.print(
+                    f"[bold red]Command failed with exit code {proc.returncode}[/bold red]"
+                )
+                if idx < len(commands):
+                    continue_run = typer.confirm(
+                        "Do you want to continue running the remaining commands?",
+                        default=False,
+                    )
+                    if not continue_run:
+                        console.print("[yellow]Execution stopped.[/yellow]")
+                        return proc.returncode
+                else:
+                    return proc.returncode
+            else:
+                console.print("[green]✓ Success (exit code 0)[/green]")
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Execution interrupted by user.[/yellow]")
+            return 130
+        except OSError as e:
+            console.print(f"[bold red]Error executing command: {e}[/bold red]")
+            return 1
+
+    return 0
+
+
+def modify_commands(commands: list[str]) -> list[str]:
+    """Allow inline editing of the commands."""
+    joined = "\n".join(commands)
+    console.print("[cyan]Modify the command below:[/cyan]")
+    try:
+        import readline
+
+        def hook() -> None:
+            readline.insert_text(joined)
+            readline.set_startup_hook()
+
+        readline.set_startup_hook(hook)
+        edited = input("> ")
+    except Exception:  # noqa: BLE001
+        edited = Prompt.ask("Edit command", default=joined)
+    finally:
+        with contextlib.suppress(Exception):
+            import readline
+
+            readline.set_startup_hook(None)
+
+    new_cmds = [line.strip() for line in edited.splitlines() if line.strip()]
+    if new_cmds:
+        return new_cmds
+    return commands
+
+
+def interactive_action_menu(commands: list[str]) -> None:
+    """Interactive action menu offering Execute, Copy, Modify, and Abort."""
+    current_commands = list(commands)
+    if not current_commands:
+        return
+
+    while True:
+        try:
+            console.print(
+                "\n[bold]Options:[/bold] "
+                "[bold green][E]xecute[/bold green] | "
+                "[bold cyan][C]opy[/bold cyan] | "
+                "[bold yellow][M]odify[/bold yellow] | "
+                "[bold red][A]bort[/bold red]"
+            )
+            choice = Prompt.ask(
+                "Select an action",
+                choices=["e", "c", "m", "a", "E", "C", "M", "A"],
+                default="a",
+            ).lower()
+
+            if choice == "e":
+                execute_commands(current_commands)
+                break
+            elif choice == "c":
+                copy_to_clipboard(current_commands)
+            elif choice == "m":
+                current_commands = modify_commands(current_commands)
+                console.print(
+                    f"[green]Updated command(s):[/green] {', '.join(current_commands)}"
+                )
+            elif choice == "a":
+                console.print("[yellow]Aborted.[/yellow]")
+                break
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Aborted.[/yellow]")
+            break

how_cli-0.3.0/how/core/__init__.py

@@ -0,0 +1,6 @@
+"""
+Package containing the core modules of the project.
+"""
+
+__version__ = "0.3.0"
+__author__ = "Rudransh Joshi (FireHead90544)"

how_cli-0.3.0/how/core/chains.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+
+def get_chain(llm: Any | None = None) -> Any:
+    """Build and return the LangChain runnable chain using an initialized LLM."""
+    from how.core.llm import get_llm
+    from how.core.template import PROMPT_TEMPLATE
+
+    if llm is None:
+        llm = get_llm()
+
+    return PROMPT_TEMPLATE | llm
+
+
+def __getattr__(name: str) -> Any:
+    if name == "HOW_CLI_CHAIN":
+        return get_chain()
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

how_cli-0.3.0/how/core/config.py

@@ -0,0 +1,86 @@
+import json
+from pathlib import Path
+from typing import Any
+
+
+class Config:
+    """
+    Manages the configuration of the application.
+    Config file is stored in ~/.how/config.json by default.
+    """
+
+    def __init__(self, config_dir: Path | None = None) -> None:
+        self.config_dir = config_dir or (Path.home() / ".how")
+        self.config_file = self.config_dir / "config.json"
+        self.__init_config()
+
+    def __init_config(self) -> None:
+        """
+        Initialize the configuration directory & file if they don't exist.
+        """
+        if not self.config_dir.exists():
+            self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        if not self.config_file.exists():
+            with open(self.config_file, "w", encoding="utf-8") as f:
+                json.dump(
+                    {
+                        "provider": "",
+                        "api_key": "",
+                        "model": "",
+                        "endpoint": "",
+                    },
+                    f,
+                    indent=4,
+                )
+
+    def setup(
+        self,
+        provider: str,
+        api_key: str = "",
+        model: str | None = None,
+        endpoint: str | None = None,
+    ) -> None:
+        """
+        Save the LLM Provider, API Key, and optional custom model/endpoint.
+        """
+        data: dict[str, Any] = {
+            "provider": provider,
+            "api_key": api_key,
+            "model": model or "",
+            "endpoint": endpoint or "",
+        }
+        with open(self.config_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=4)
+
+    @property
+    def values(self) -> dict[str, Any]:
+        """
+        Get the configuration values.
+        """
+        try:
+            with open(self.config_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return {}
+
+    def is_ready(self) -> bool:
+        """
+        Check if the configuration file is ready to use.
+        """
+        try:
+            vals = self.values
+            provider = vals.get("provider")
+            if not provider:
+                return False
+
+            from how.core.providers import LLM_PROVIDERS
+
+            provider_info = LLM_PROVIDERS.get(provider)
+            if not provider_info:
+                return False
+
+            requires_key = provider_info.get("requires_key", True)
+            return not (requires_key and not vals.get("api_key"))
+        except (KeyError, TypeError, ValueError, ImportError):
+            return False