cmdo-cli 0.1.0__py3-none-any.whl

cmdo/__init__.py

@@ -0,0 +1,3 @@
+"""cmdo — Natural language to shell commands."""
+
+__version__ = "0.1.0"

cmdo/cli.py

@@ -0,0 +1,174 @@
+"""CLI entry point for cmdo."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+from cmdo import __version__
+
+console = Console()
+
+
+@click.command(context_settings={"ignore_unknown_options": True})
+@click.argument("query", nargs=-1)
+@click.option("--config", "do_config", is_flag=True, help="Configure cmdo")
+@click.option("--show", is_flag=True, help="Show current configuration (use with --config)")
+@click.option("--reset", is_flag=True, help="Reset configuration (use with --config)")
+@click.option("--dry-run", "-d", is_flag=True, help="Generate command without executing")
+@click.option("--yes", "-y", is_flag=True, help="Auto-confirm safe commands")
+@click.option("--model", "-m", default=None, help="Override default model")
+@click.option("--version", "-V", is_flag=True, help="Show version")
+def main(
+    query: tuple[str, ...],
+    do_config: bool,
+    show: bool,
+    reset: bool,
+    dry_run: bool,
+    yes: bool,
+    model: str | None,
+    version: bool,
+) -> None:
+    """cmdo — Natural language to shell commands.
+
+    \b
+    Examples:
+      cmdo "find all Python files larger than 1MB"
+      cmdo "start a local HTTP server on port 8080"
+      cmdo --explain "tar -czf archive.tar.gz dir/"
+      cmdo --dry-run "delete the temp folder"
+    """
+    if version:
+        click.echo(f"cmdo v{__version__}")
+        return
+
+    # Config management
+    if do_config:
+        if show:
+            from cmdo.config import show_config
+            show_config()
+        elif reset:
+            from cmdo.config import reset_config
+            reset_config()
+        else:
+            from cmdo.config import configure
+            configure()
+        return
+
+    # No query provided
+    if not query:
+        click.echo(f"cmdo v{__version__} — Natural language to shell commands")
+        click.echo('Usage: cmdo "your instruction"')
+        click.echo("       cmdo --config        Set up or reconfigure")
+        click.echo("       cmdo --help          Show full help")
+        return
+
+    # Core flow
+    query_str = " ".join(query)
+    _run_query(query_str, dry_run=dry_run, auto_yes=yes, model_override=model)
+
+
+def _run_query(
+    query: str,
+    *,
+    dry_run: bool = False,
+    auto_yes: bool = False,
+    model_override: str | None = None,
+) -> None:
+    """Core flow: query → generate → display → confirm → execute."""
+    from cmdo.clipboard import copy_to_clipboard
+    from cmdo.config import ensure_configured
+    from cmdo.context import gather_context
+    from cmdo.display import (
+        display_command,
+        display_error,
+        display_execution_result,
+        display_forbidden,
+        edit_command,
+        prompt_user,
+    )
+    from cmdo.executor import execute_command
+    from cmdo.llm.client import generate_command
+    from cmdo.models import RiskLevel, UserAction
+    from cmdo.safety.classifier import classify_risk, upgrade_risk
+    from cmdo.safety.forbidden import check_forbidden
+
+    # 1. Ensure configured
+    config = ensure_configured()
+    if model_override:
+        config.model = model_override
+
+    # 2. Gather context
+    with console.status("[dim]Gathering context...[/dim]", spinner="dots"):
+        context = gather_context()
+
+    # 3. Generate command via LLM
+    try:
+        with console.status("[dim]Thinking...[/dim]", spinner="dots"):
+            result = generate_command(query, context, config)
+    except Exception as e:
+        display_error(f"Failed to generate command: {e}")
+        sys.exit(2)
+
+    if not result.command:
+        display_error("Could not generate a command for that request.")
+        sys.exit(1)
+
+    # 4. Safety checks
+    forbidden_msg = check_forbidden(result.command)
+    if forbidden_msg:
+        display_forbidden(forbidden_msg)
+        sys.exit(1)
+
+    local_risk, local_reason = classify_risk(result.command)
+    result.risk_level = upgrade_risk(result.risk_level, local_risk)
+    if local_reason and result.risk_reason is None:
+        result.risk_reason = local_reason
+
+    # 5. Display
+    display_command(result)
+
+    # 6. Dry run — stop here
+    if dry_run:
+        return
+
+    # 7. Auto-confirm if --yes flag or config auto_confirm_safe
+    if (auto_yes or config.auto_confirm_safe) and result.risk_level != RiskLevel.DANGEROUS:
+        action = UserAction.EXECUTE
+    else:
+        action = prompt_user(result)
+
+    # 8. Handle action
+    if action == UserAction.CANCEL:
+        console.print("[dim]Cancelled.[/dim]")
+        sys.exit(1)
+
+    if action == UserAction.COPY:
+        if copy_to_clipboard(result.command):
+            console.print("[green]📋 Copied to clipboard![/green]")
+        else:
+            console.print(f"[yellow]Could not copy. Here's the command:[/yellow]\n{result.command}")
+        return
+
+    if action == UserAction.EDIT:
+        edited = edit_command(result.command)
+        if edited != result.command:
+            # Re-check safety on edited command
+            forbidden_msg = check_forbidden(edited)
+            if forbidden_msg:
+                display_forbidden(forbidden_msg)
+                sys.exit(1)
+            result.command = edited
+
+    # 9. Execute
+    stepwise = action == UserAction.EXECUTE_STEPWISE
+    exec_result = execute_command(result.command, stepwise=stepwise)
+    display_execution_result(exec_result.exit_code, exec_result.duration)
+
+    sys.exit(0 if exec_result.exit_code == 0 else 2)
+
+
+if __name__ == "__main__":
+    main()

cmdo/clipboard.py

@@ -0,0 +1,14 @@
+"""Clipboard integration."""
+
+from __future__ import annotations
+
+
+def copy_to_clipboard(command: str) -> bool:
+    """Copy command to system clipboard. Returns True on success."""
+    try:
+        import pyperclip
+
+        pyperclip.copy(command)
+        return True
+    except Exception:
+        return False

cmdo/config.py

@@ -0,0 +1,201 @@
+"""Configuration management for cmdo."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import tomli_w
+
+from cmdo.models import Config
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+CONFIG_DIR = Path.home() / ".config" / "cmdo"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def _load_toml() -> dict | None:
+    if not CONFIG_FILE.exists():
+        return None
+    with open(CONFIG_FILE, "rb") as f:
+        return tomllib.load(f)
+
+
+def _save_config(config: Config) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = {
+        "llm": {
+            "provider": config.provider,
+            "api_key": config.api_key,
+            "model": config.model,
+            "base_url": config.base_url,
+        },
+        "behavior": {
+            "auto_confirm_safe": config.auto_confirm_safe,
+            "danger_confirmation": config.danger_confirmation,
+        },
+        "display": {
+            "color": config.color,
+            "explanation": config.explanation,
+        },
+    }
+    with open(CONFIG_FILE, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def check_config() -> Config | None:
+    """Load and return Config if valid, else None."""
+    data = _load_toml()
+    if data is None:
+        return None
+    try:
+        llm = data.get("llm", {})
+        behavior = data.get("behavior", {})
+        display = data.get("display", {})
+        config = Config(
+            provider=llm.get("provider", "openai"),
+            api_key=llm.get("api_key", ""),
+            model=llm.get("model", "gpt-5-mini"),
+            base_url=llm.get("base_url", ""),
+            auto_confirm_safe=behavior.get("auto_confirm_safe", False),
+            danger_confirmation=behavior.get("danger_confirmation", "type"),
+            color=display.get("color", True),
+            explanation=display.get("explanation", True),
+        )
+        if not config.api_key:
+            return None
+        return config
+    except (KeyError, TypeError):
+        return None
+
+
+def configure() -> Config:
+    """Interactive setup wizard."""
+    from rich.console import Console
+
+    console = Console()
+    console.print("\n[bold]🔧 cmdo setup[/bold]\n")
+
+    # Provider (OpenAI only for MVP)
+    console.print("1. Choose your LLM provider:")
+    console.print("   [1] OpenAI (GPT-5.4, GPT-5-mini)")
+    console.print()
+    choice = input("   > ").strip()
+    if choice not in ("", "1"):
+        console.print("[yellow]Only OpenAI is supported in this version.[/yellow]")
+    provider = "openai"
+
+    # API key
+    console.print("\n2. Enter your OpenAI API key:")
+    console.print("   [dim](Get one at https://platform.openai.com/api-keys)[/dim]")
+    api_key = input("   > ").strip()
+    if not api_key:
+        console.print("[red]API key is required.[/red]")
+        sys.exit(2)
+
+    # Validate API key
+    console.print("\n   [dim]Validating API key...[/dim]", end="")
+    if _validate_api_key(api_key):
+        console.print(" [green]✓[/green]")
+    else:
+        console.print(" [red]✗[/red]")
+        console.print("[red]   API key validation failed. Please check your key.[/red]")
+        sys.exit(2)
+
+    # Model
+    console.print("\n3. Choose default model:")
+    console.print("   [1] gpt-5.4       (best quality, slower)")
+    console.print("   [2] gpt-5-mini    (fast, cheaper)")
+    console.print("   [3] Custom        (enter model name)")
+    model_choice = input("   > ").strip()
+    if model_choice == "1":
+        model = "gpt-5.4"
+    elif model_choice == "3":
+        model = input("   Enter model name: ").strip()
+        if not model:
+            console.print("[yellow]No model entered, defaulting to gpt-5-mini.[/yellow]")
+            model = "gpt-5-mini"
+    else:
+        model = "gpt-5-mini"
+
+    # Auto-confirm
+    console.print("\n4. Auto-confirm safe commands? (skip [Y/n] for non-destructive)")
+    auto_confirm = input("   [y/N] > ").strip().lower() == "y"
+
+    config = Config(
+        provider=provider,
+        api_key=api_key,
+        model=model,
+        auto_confirm_safe=auto_confirm,
+    )
+    _save_config(config)
+    console.print(f"\n[green]✅ Configuration saved to {CONFIG_FILE}[/green]")
+    console.print('   Run [bold]cmdo "list all python files"[/bold] to try it out!\n')
+    return config
+
+
+def _validate_api_key(api_key: str) -> bool:
+    """Validate API key by listing available models."""
+    try:
+        from openai import OpenAI
+
+        client = OpenAI(api_key=api_key)
+        client.models.list()
+        return True
+    except Exception:
+        return False
+
+
+def show_config() -> None:
+    """Print current config with masked API key."""
+    from rich.console import Console
+
+    console = Console()
+    config = check_config()
+    if config is None:
+        console.print("[yellow]No configuration found. Run `cmdo --config` to set up.[/yellow]")
+        return
+
+    masked_key = config.api_key[:7] + "..." + config.api_key[-4:] if len(config.api_key) > 11 else "****"
+    console.print("\n[bold]cmdo configuration[/bold]\n")
+    console.print(f"  Provider:           {config.provider}")
+    console.print(f"  API Key:            {masked_key}")
+    console.print(f"  Model:              {config.model}")
+    console.print(f"  Auto-confirm safe:  {config.auto_confirm_safe}")
+    console.print(f"  Color:              {config.color}")
+    console.print(f"  Explanations:       {config.explanation}")
+    console.print()
+
+
+def reset_config() -> None:
+    """Delete config after confirmation."""
+    from rich.console import Console
+
+    console = Console()
+    if not CONFIG_FILE.exists():
+        console.print("[yellow]No configuration file to reset.[/yellow]")
+        return
+
+    confirm = input("Are you sure you want to reset the configuration? [y/N] ").strip().lower()
+    if confirm == "y":
+        CONFIG_FILE.unlink()
+        console.print("[green]Configuration reset. Run `cmdo --config` to reconfigure.[/green]")
+    else:
+        console.print("Cancelled.")
+
+
+def ensure_configured() -> Config:
+    """Return config or exit with error if not configured."""
+    config = check_config()
+    if config is None:
+        from rich.console import Console
+
+        console = Console()
+        console.print("[yellow]⚠ cmdo is not configured yet.[/yellow]")
+        console.print("Run [bold]cmdo --config[/bold] to set up your LLM provider and API key.")
+        sys.exit(2)
+    return config

cmdo/context.py

@@ -0,0 +1,93 @@
+"""Shell context gathering for cmdo."""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+
+from cmdo.models import ShellContext
+
+COMMON_TOOLS = [
+    "tar", "gzip", "zip", "unzip", "pigz",
+    "docker", "docker-compose",
+    "git", "gh",
+    "python", "python3", "pip", "pip3",
+    "node", "npm", "npx",
+    "ffmpeg", "convert", "jq",
+    "curl", "wget", "httpie",
+    "rsync", "scp", "ssh",
+    "awk", "sed", "grep",
+    "kubectl", "terraform",
+]
+
+
+def _run(cmd: str, timeout: float = 2.0) -> str:
+    """Run a shell command and return stdout, or empty string on failure."""
+    try:
+        result = subprocess.run(
+            cmd, shell=True, capture_output=True, text=True, timeout=timeout
+        )
+        return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return ""
+
+
+def detect_tools(names: list[str] | None = None) -> list[str]:
+    """Check which CLI tools are installed."""
+    if names is None:
+        names = COMMON_TOOLS
+    available = []
+    for name in names:
+        if _run(f"which {name}"):
+            available.append(name)
+    return available
+
+
+def gather_context() -> ShellContext:
+    """Collect environmental context for the LLM prompt."""
+    # OS info
+    system = platform.system()
+    if system == "Darwin":
+        os_info = f"macOS {platform.mac_ver()[0]}"
+    elif system == "Linux":
+        os_info = _run("cat /etc/os-release | grep PRETTY_NAME | cut -d'\"' -f2") or f"Linux {platform.release()}"
+    else:
+        os_info = f"{system} {platform.release()}"
+
+    # Shell
+    shell = os.environ.get("SHELL", "")
+    shell_name = os.path.basename(shell) if shell else "unknown"
+    shell_version = _run(f"{shell} --version 2>&1 | head -1") if shell else ""
+    shell_info = f"{shell_name} {shell_version}".strip() if shell_version else shell_name
+
+    # CWD listing (first 50 entries)
+    cwd = os.getcwd()
+    try:
+        entries = sorted(os.listdir(cwd))[:50]
+    except OSError:
+        entries = []
+
+    # Git branch
+    git_branch = _run("git rev-parse --abbrev-ref HEAD 2>/dev/null") or None
+
+    # Environment hints
+    env_hints: dict[str, str] = {}
+    for key in ("CONDA_DEFAULT_ENV", "VIRTUAL_ENV", "PYENV_VERSION", "NVM_DIR"):
+        val = os.environ.get(key)
+        if val:
+            env_hints[key] = val
+
+    # Available tools
+    path_tools = detect_tools()
+
+    return ShellContext(
+        os=os_info,
+        shell=shell_info,
+        cwd=cwd,
+        cwd_listing=entries,
+        user=os.environ.get("USER", "unknown"),
+        path_tools=path_tools,
+        env_hints=env_hints,
+        git_branch=git_branch,
+    )

cmdo/display.py

@@ -0,0 +1,134 @@
+"""Terminal display and user interaction."""
+
+from __future__ import annotations
+
+import readline  # noqa: F401 — enables input() line editing
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from cmdo.models import CommandResult, RiskLevel, UserAction
+
+console = Console()
+
+RISK_STYLES = {
+    RiskLevel.SAFE: ("green", "🤖"),
+    RiskLevel.CAUTION: ("yellow", "🟡"),
+    RiskLevel.DANGEROUS: ("red", "🔴"),
+}
+
+
+def display_command(result: CommandResult) -> None:
+    """Render the command result with color-coded formatting."""
+    color, _ = RISK_STYLES.get(result.risk_level, ("white", "🤖"))
+
+    # Command box
+    console.print()
+    console.print("🤖 Will run:")
+    console.print(Panel(
+        Text(result.command, style=f"bold {color}"),
+        border_style=color,
+        expand=False,
+        padding=(0, 1),
+    ))
+
+    # Risk warning
+    if result.risk_level == RiskLevel.DANGEROUS:
+        reason = result.risk_reason or "This command may be destructive."
+        console.print(f"[bold red]🔴 WARNING: DESTRUCTIVE — {reason}[/bold red]")
+        console.print("[red]   This action may be IRREVERSIBLE.[/red]")
+    elif result.risk_level == RiskLevel.CAUTION:
+        reason = result.risk_reason or "This command modifies system state."
+        console.print(f"[yellow]🟡 CAUTION: {reason}[/yellow]")
+
+    # Explanation
+    if result.explanation:
+        console.print(f"\n[dim]📝 {result.explanation}[/dim]")
+
+    # Low confidence warning
+    if result.confidence < 0.5:
+        pct = int(result.confidence * 100)
+        console.print(f"\n[yellow]⚠ Low confidence ({pct}%). Please review carefully.[/yellow]")
+
+    console.print()
+
+
+def prompt_user(result: CommandResult) -> UserAction:
+    """Prompt user for action based on risk level."""
+    if result.risk_level == RiskLevel.DANGEROUS:
+        console.print('[bold red]Type "yes" to confirm, or [n] to cancel:[/bold red]')
+        try:
+            answer = input("> ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            console.print()
+            return UserAction.CANCEL
+        if answer == "yes":
+            return UserAction.EXECUTE
+        return UserAction.CANCEL
+    else:
+        # Show action menu
+        if result.is_multi_step:
+            console.print(r"\[Y] Execute all  \[s] Step-by-step  \[e] Edit  \[c] Copy  \[n] Cancel")
+        else:
+            console.print(r"\[Y] Execute  \[e] Edit  \[c] Copy  \[n] Cancel")
+
+        try:
+            answer = input("> ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            console.print()
+            return UserAction.CANCEL
+
+        if answer in ("", "y"):
+            return UserAction.EXECUTE
+        if answer == "s" and result.is_multi_step:
+            return UserAction.EXECUTE_STEPWISE
+        if answer == "e":
+            return UserAction.EDIT
+        if answer == "c":
+            return UserAction.COPY
+        return UserAction.CANCEL
+
+
+def edit_command(command: str) -> str:
+    """Allow user to edit the command inline."""
+    console.print("[dim]Edit the command (press Enter when done):[/dim]")
+
+    def prefill_input(text: str) -> str:
+        import readline as rl
+        def hook():
+            rl.insert_text(text)
+            rl.redisplay()
+        rl.set_pre_input_hook(hook)
+        try:
+            result = input("> ")
+        finally:
+            rl.set_pre_input_hook()
+        return result
+
+    try:
+        edited = prefill_input(command)
+        return edited.strip() or command
+    except (KeyboardInterrupt, EOFError):
+        console.print()
+        return command
+
+
+def display_execution_result(exit_code: int, duration: float) -> None:
+    """Show execution result summary."""
+    if exit_code == 0:
+        console.print(f"[green]✅ Done ({duration:.1f}s)[/green]")
+    else:
+        console.print(f"[red]❌ Command failed (exit code {exit_code})[/red]")
+
+
+def display_error(message: str) -> None:
+    """Display an error message."""
+    console.print(f"[red]❌ {message}[/red]")
+
+
+def display_forbidden(message: str) -> None:
+    """Display a forbidden command message."""
+    console.print(f"\n[bold red]🚫 {message}[/bold red]")
+    console.print("[red]This command is blocked for safety and cannot be executed.[/red]\n")

cmdo/executor.py

@@ -0,0 +1,103 @@
+"""Command execution with real-time output streaming."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import time
+
+from cmdo.models import ExecutionResult
+
+
+def execute_command(command: str, stepwise: bool = False) -> ExecutionResult:
+    """Execute a shell command with real-time output streaming."""
+    if stepwise:
+        return _execute_stepwise(command)
+    return _execute_single(command)
+
+
+def _execute_single(command: str) -> ExecutionResult:
+    """Execute a single command."""
+    shell = os.environ.get("SHELL", "/bin/sh")
+    start = time.time()
+    was_interrupted = False
+
+    try:
+        process = subprocess.Popen(
+            [shell, "-c", command],
+            stdout=None,  # inherit — stream to terminal
+            stderr=None,  # inherit — stream to terminal
+        )
+        exit_code = process.wait()
+
+    except KeyboardInterrupt:
+        # Send SIGINT to child process group
+        was_interrupted = True
+        try:
+            os.killpg(os.getpgid(process.pid), signal.SIGINT)
+        except (ProcessLookupError, OSError):
+            pass
+        try:
+            exit_code = process.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            exit_code = -1
+
+    duration = time.time() - start
+    return ExecutionResult(
+        exit_code=exit_code,
+        duration=duration,
+        was_interrupted=was_interrupted,
+    )
+
+
+def _execute_stepwise(command: str) -> ExecutionResult:
+    """Execute a multi-step command one step at a time."""
+    from rich.console import Console
+    console = Console()
+
+    # Split on && and ; (simple split — doesn't handle quoted strings perfectly)
+    import re
+    steps = re.split(r"\s*&&\s*|\s*;\s*", command)
+    steps = [s.strip() for s in steps if s.strip()]
+
+    total_duration = 0.0
+    for i, step in enumerate(steps, 1):
+        console.print(f"\n[bold]Step {i}/{len(steps)}:[/bold] {step}")
+        result = _execute_single(step)
+        total_duration += result.duration
+
+        if result.was_interrupted:
+            return ExecutionResult(
+                exit_code=-1,
+                duration=total_duration,
+                was_interrupted=True,
+            )
+
+        if result.exit_code != 0:
+            console.print(f"[red]Step {i} failed (exit code {result.exit_code}). Stopping.[/red]")
+            return ExecutionResult(
+                exit_code=result.exit_code,
+                duration=total_duration,
+            )
+
+        console.print(f"[green]Step {i} done ({result.duration:.1f}s)[/green]")
+
+        if i < len(steps):
+            try:
+                answer = input("Continue to next step? [Y/n] ").strip().lower()
+                if answer == "n":
+                    return ExecutionResult(
+                        exit_code=0,
+                        duration=total_duration,
+                        was_interrupted=True,
+                    )
+            except (KeyboardInterrupt, EOFError):
+                return ExecutionResult(
+                    exit_code=0,
+                    duration=total_duration,
+                    was_interrupted=True,
+                )
+
+    return ExecutionResult(exit_code=0, duration=total_duration)

cmdo/llm/client.py

@@ -0,0 +1,56 @@
+"""LLM API client for command generation."""
+
+from __future__ import annotations
+
+import time
+
+from openai import APIConnectionError, APITimeoutError, OpenAI, RateLimitError
+
+from cmdo.llm.parser import parse_response
+from cmdo.llm.prompt import build_prompt
+from cmdo.models import CommandResult, Config, ShellContext
+
+
+def generate_command(
+    query: str, context: ShellContext, config: Config
+) -> CommandResult:
+    """Send query + context to LLM and return a structured CommandResult."""
+    client = OpenAI(
+        api_key=config.api_key,
+        base_url=config.base_url or None,
+    )
+    messages = build_prompt(query, context)
+
+    for attempt in range(2):
+        try:
+            response = client.chat.completions.create(
+                model=config.model,
+                messages=messages,
+                max_completion_tokens=1024,
+            )
+            raw = response.choices[0].message.content or ""
+            result = parse_response(raw)
+            if result.command:
+                return result
+            # Empty command on first attempt — retry
+            if attempt == 0:
+                continue
+            return result
+
+        except RateLimitError:
+            if attempt == 0:
+                wait = 5
+                from rich.console import Console
+
+                Console().print(f"[yellow]⏳ Rate limited. Retrying in {wait}s...[/yellow]")
+                time.sleep(wait)
+                continue
+            raise
+
+        except (APITimeoutError, APIConnectionError):
+            if attempt == 0:
+                continue
+            raise
+
+    # Should not reach here, but just in case
+    return CommandResult(command="", explanation="Failed to generate command.", confidence=0.0)

cmdo/llm/parser.py

@@ -0,0 +1,56 @@
+"""Parse LLM responses into CommandResult."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from cmdo.models import CommandResult, RiskLevel
+
+
+def _extract_json(text: str) -> str:
+    """Extract JSON from text that may contain markdown fences."""
+    # Try to find JSON in code block
+    match = re.search(r"```(?:json)?\s*\n?(.*?)\n?\s*```", text, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    # Try to find raw JSON object
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if match:
+        return match.group(0)
+    return text
+
+
+def _parse_risk_level(value: str) -> RiskLevel:
+    """Parse risk level string to enum."""
+    value = value.upper().strip()
+    if value == "DANGEROUS":
+        return RiskLevel.DANGEROUS
+    if value == "CAUTION":
+        return RiskLevel.CAUTION
+    return RiskLevel.SAFE
+
+
+def parse_response(raw: str) -> CommandResult:
+    """Parse LLM JSON response into a CommandResult."""
+    json_str = _extract_json(raw)
+    try:
+        data = json.loads(json_str)
+    except json.JSONDecodeError:
+        # Fallback: treat the whole response as a command
+        return CommandResult(
+            command=raw.strip(),
+            explanation="(Could not parse LLM response)",
+            confidence=0.3,
+        )
+
+    return CommandResult(
+        command=data.get("command", ""),
+        explanation=data.get("explanation", ""),
+        risk_level=_parse_risk_level(data.get("risk_level", "SAFE")),
+        risk_reason=data.get("risk_reason"),
+        alternatives=data.get("alternatives", []),
+        is_multi_step=data.get("is_multi_step", False),
+        estimated_duration=data.get("estimated_duration"),
+        confidence=float(data.get("confidence", 0.8)),
+    )

cmdo/llm/prompt.py

@@ -0,0 +1,70 @@
+"""Prompt construction for LLM command generation."""
+
+from __future__ import annotations
+
+from cmdo.models import ShellContext
+
+SYSTEM_PROMPT = """\
+You are a shell command generator. Given a natural language instruction \
+and shell context, produce the exact command(s) to execute.
+
+Rules:
+1. Output ONLY valid shell commands for the user's OS and shell.
+2. Prefer simple, standard tools over obscure ones.
+3. Use tools confirmed available in the context. If the best tool \
+is unavailable, use a fallback AND note it.
+4. Never generate commands that require interactive input (use flags \
+to avoid prompts, e.g., `rm -f` not `rm -i` when deletion is intended).
+5. For file operations, use the cwd_listing to resolve ambiguous names.
+6. Classify risk level:
+   - SAFE: read-only, create files, list, search, compress
+   - CAUTION: modify files, install packages, change permissions
+   - DANGEROUS: delete files, format disks, overwrite data, sudo operations, \
+network-facing services, database drops, recursive force operations
+7. If the request is ambiguous, prefer the SAFER interpretation.
+8. If you cannot generate a command, say so — never hallucinate.
+
+Respond in JSON:
+{
+  "command": "...",
+  "explanation": "...",
+  "risk_level": "SAFE|CAUTION|DANGEROUS",
+  "risk_reason": "..." or null,
+  "alternatives": [...] or [],
+  "is_multi_step": true|false,
+  "estimated_duration": "..." or null,
+  "confidence": 0.0-1.0
+}"""
+
+
+def _format_context(context: ShellContext) -> str:
+    """Format shell context as a concise string for the LLM."""
+    lines = [
+        f"OS: {context.os}",
+        f"Shell: {context.shell}",
+        f"CWD: {context.cwd}",
+        f"User: {context.user}",
+    ]
+    if context.cwd_listing:
+        listing = ", ".join(context.cwd_listing[:30])
+        lines.append(f"Files in CWD: {listing}")
+    if context.path_tools:
+        lines.append(f"Available tools: {', '.join(context.path_tools)}")
+    if context.env_hints:
+        hints = ", ".join(f"{k}={v}" for k, v in context.env_hints.items())
+        lines.append(f"Environment: {hints}")
+    if context.git_branch:
+        lines.append(f"Git branch: {context.git_branch}")
+    return "\n".join(lines)
+
+
+def build_prompt(query: str, context: ShellContext) -> list[dict[str, str]]:
+    """Build the message list for the OpenAI API call."""
+    context_str = _format_context(context)
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {
+            "role": "user",
+            "content": f"Shell context:\n{context_str}\n\nInstruction: {query}",
+        },
+    ]

cmdo/models.py

@@ -0,0 +1,65 @@
+"""Shared data models for cmdo."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class RiskLevel(Enum):
+    SAFE = "safe"
+    CAUTION = "caution"
+    DANGEROUS = "dangerous"
+
+
+class UserAction(Enum):
+    EXECUTE = "execute"
+    EXECUTE_STEPWISE = "step"
+    EDIT = "edit"
+    COPY = "copy"
+    CANCEL = "cancel"
+
+
+@dataclass
+class ShellContext:
+    os: str = ""
+    shell: str = ""
+    cwd: str = ""
+    cwd_listing: list[str] = field(default_factory=list)
+    user: str = ""
+    path_tools: list[str] = field(default_factory=list)
+    env_hints: dict[str, str] = field(default_factory=dict)
+    git_branch: str | None = None
+
+
+@dataclass
+class CommandResult:
+    command: str = ""
+    explanation: str = ""
+    risk_level: RiskLevel = RiskLevel.SAFE
+    risk_reason: str | None = None
+    alternatives: list[str] = field(default_factory=list)
+    is_multi_step: bool = False
+    estimated_duration: str | None = None
+    confidence: float = 1.0
+
+
+@dataclass
+class ExecutionResult:
+    exit_code: int = 0
+    stdout: str = ""
+    stderr: str = ""
+    duration: float = 0.0
+    was_interrupted: bool = False
+
+
+@dataclass
+class Config:
+    provider: str = "openai"
+    api_key: str = ""
+    model: str = "gpt-5-mini"
+    base_url: str = ""
+    auto_confirm_safe: bool = False
+    danger_confirmation: str = "type"
+    color: bool = True
+    explanation: bool = True

cmdo/safety/classifier.py

@@ -0,0 +1,72 @@
+"""Local risk classification using pattern matching."""
+
+from __future__ import annotations
+
+import re
+
+from cmdo.models import RiskLevel
+
+# Patterns ordered from most to least dangerous
+DANGEROUS_PATTERNS: list[tuple[str, str]] = [
+    (r"\brm\s+(-\w*r\w*\s+-\w*f\w*|-\w*f\w*\s+-\w*r\w*|-\w*rf\w*)", "Recursive forced deletion"),
+    (r"\brm\s+-\w*r", "Recursive deletion"),
+    (r"\bmkfs\b", "Filesystem format"),
+    (r"\bdd\s+if=", "Direct disk write"),
+    (r">\s*/dev/", "Write to device"),
+    (r":\(\)\{\s*:\|:&\s*\};:", "Fork bomb"),
+    (r"\bchmod\s+(-\w*R\w*\s+)?777\b", "Open permissions to everyone"),
+    (r"\bDROP\s+(TABLE|DATABASE)\b", "Database destruction"),
+    (r"\bTRUNCATE\s+", "Database truncation"),
+    (r"\b(shutdown|reboot)\b", "System shutdown/reboot"),
+    (r"\bsudo\s+rm\b", "Privileged deletion"),
+    (r"\bcurl\b.*\|\s*(sudo\s+)?(ba)?sh\b", "Remote code execution"),
+    (r"\bwget\b.*\|\s*(sudo\s+)?(ba)?sh\b", "Remote code execution"),
+    (r"\bformat\b", "Disk format"),
+    (r"\bfdisk\b", "Disk partition"),
+    (r":>\s*\S+", "File truncation"),
+    (r">\s*/etc/", "Overwrite system config"),
+]
+
+CAUTION_PATTERNS: list[tuple[str, str]] = [
+    (r"\bsudo\b", "Requires elevated privileges"),
+    (r"\bmv\b", "File move/rename (overwrite risk)"),
+    (r"\bchmod\b", "Permission change"),
+    (r"\bchown\b", "Ownership change"),
+    (r"\bpip\s+install\b", "Package installation"),
+    (r"\bnpm\s+install\s+-g\b", "Global package installation"),
+    (r"\bbrew\s+install\b", "Package installation"),
+    (r"\bapt\s+(install|remove)\b", "Package management"),
+    (r"\bgit\s+push\s+--force\b", "Force push"),
+    (r"\bgit\s+reset\s+--hard\b", "Hard reset"),
+    (r"\bsed\s+-i\b", "In-place file edit"),
+    (r"\bdocker\s+rm\b", "Container removal"),
+    (r"\bkill\b", "Process termination"),
+    (r"\bpkill\b", "Process termination"),
+    (r"/etc/|/usr/", "System path modification"),
+]
+
+
+def classify_risk(command: str) -> tuple[RiskLevel, str | None]:
+    """Classify command risk level using local pattern matching.
+
+    Returns (risk_level, reason) tuple.
+    """
+    for pattern, reason in DANGEROUS_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return RiskLevel.DANGEROUS, reason
+
+    for pattern, reason in CAUTION_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return RiskLevel.CAUTION, reason
+
+    return RiskLevel.SAFE, None
+
+
+def upgrade_risk(
+    llm_level: RiskLevel, local_level: RiskLevel
+) -> RiskLevel:
+    """Return the higher of two risk levels."""
+    order = {RiskLevel.SAFE: 0, RiskLevel.CAUTION: 1, RiskLevel.DANGEROUS: 2}
+    if order[local_level] > order[llm_level]:
+        return local_level
+    return llm_level

cmdo/safety/forbidden.py

@@ -0,0 +1,35 @@
+"""Hard-blocked forbidden commands."""
+
+from __future__ import annotations
+
+import re
+
+FORBIDDEN_PATTERNS: list[tuple[str, str]] = [
+    (
+        r":\(\)\{\s*:\|:&\s*\};:",
+        "Fork bomb detected. This command would crash your system.",
+    ),
+    (
+        r"\bdd\s+if=/dev/(zero|urandom)\s+of=/dev/[hs]d[a-z]\b",
+        "Disk wipe detected. This would destroy all data on the target drive.",
+    ),
+    (
+        r"\brm\s+-\w*rf?\w*\s+/\s*$",
+        "Full system deletion detected. This would destroy your entire filesystem.",
+    ),
+    (
+        r"\brm\s+-\w*rf?\w*\s+/\*",
+        "Full system deletion detected. This would destroy your entire filesystem.",
+    ),
+]
+
+
+def check_forbidden(command: str) -> str | None:
+    """Check if a command is forbidden.
+
+    Returns an error message if forbidden, None if allowed.
+    """
+    for pattern, message in FORBIDDEN_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return message
+    return None

cmdo_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: cmdo-cli
+Version: 0.1.0
+Summary: Natural language to shell commands — just say what you want and cmdo does it.
+Author: Yijiang Pang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YijiangPang/cmdo
+Project-URL: Repository, https://github.com/YijiangPang/cmdo
+Project-URL: Issues, https://github.com/YijiangPang/cmdo/issues
+Keywords: cli,terminal,ai,shell,natural-language,command-line,openai,gpt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: openai>=1.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: pyperclip>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# cmdo
+
+**Natural language to shell commands.** Just say what you want and cmdo does it.
+
+```
+$ cmdo "compress the checkpoints folder"
+
+🤖 Will run:
+╭──────────────────────────────────────────────╮
+│ tar -czf checkpoints.tar.gz checkpoints/     │
+╰──────────────────────────────────────────────╯
+📝 Compresses the "checkpoints" directory into a gzipped tarball.
+
+[Y] Execute  [e] Edit  [c] Copy  [n] Cancel
+```
+
+## Features
+
+- **Translates natural language** into accurate shell commands using GPT
+- **Safety-first**: commands are classified as Safe / Caution / Dangerous with color-coded warnings
+- **Hard-blocks** catastrophic commands (fork bombs, `rm -rf /`, disk wipes)
+- **Context-aware**: knows your OS, shell, current directory, installed tools, and git branch
+- **Works everywhere**: any terminal — iTerm, VSCode, Terminal.app, SSH, tmux
+
+## Install
+
+```bash
+pip install cmdo
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```bash
+# First-time setup — enter your OpenAI API key
+cmdo --config
+
+# Use it
+cmdo "find all Python files larger than 1MB"
+cmdo "start a local HTTP server on port 8080"
+cmdo "show disk usage sorted by size"
+
+# Generate without executing
+cmdo --dry-run "delete the temp folder"
+
+# Auto-confirm safe commands
+cmdo --yes "list all docker containers"
+```
+
+## Safety
+
+Every generated command goes through two layers of safety checking:
+
+1. **LLM classification** — the model labels each command as SAFE, CAUTION, or DANGEROUS
+2. **Local pattern matching** — a regex-based classifier catches anything the LLM misses
+
+| Risk Level | Confirmation | Auto-confirm (`--yes`) |
+|---|---|---|
+| **SAFE** (green) | Single keypress `Y` | Allowed |
+| **CAUTION** (yellow) | Single keypress `Y` | Allowed |
+| **DANGEROUS** (red) | Type full word `yes` | Never |
+
+Certain commands are **hard-blocked** and can never be executed:
+- Fork bombs
+- Full disk wipes (`dd if=/dev/zero of=/dev/sda`)
+- System-wide deletion (`rm -rf /`)
+
+## Configuration
+
+```bash
+cmdo --config           # Interactive setup wizard
+cmdo --config --show    # View current config (API key masked)
+cmdo --config --reset   # Reset to defaults
+```
+
+Config is stored in `~/.config/cmdo/config.toml`.
+
+## CLI Reference
+
+```
+Usage: cmdo [OPTIONS] [QUERY]...
+
+Options:
+  --config          Configure cmdo
+  --show            Show current configuration (use with --config)
+  --reset           Reset configuration (use with --config)
+  -d, --dry-run     Generate command without executing
+  -y, --yes         Auto-confirm safe commands
+  -m, --model TEXT  Override default model for one query
+  -V, --version     Show version
+  --help            Show help
+```
+
+## License
+
+MIT

cmdo_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+cmdo/__init__.py,sha256=Jt4rFOgqLrGQGWHwudm-1ANtlvyuLxz87SO7T0w4A4A,74
+cmdo/cli.py,sha256=XXU97K-gtGX-vKdN-ifMcNisPpwjPa_B1YDrH2VZW5s,5458
+cmdo/clipboard.py,sha256=u-KVpJgk9Na4GZj6Go_jSZ0KVPO7FgqA-IDMnbuP5Pw,311
+cmdo/config.py,sha256=4KkiL6hM7rt9Nd-lqwV6zPREme3HxNZsZ473oR_Fnxo,6415
+cmdo/context.py,sha256=XxLnitT1_Nq3TQWZmDkkX-15afMQEPwwh2l90XJ6Msw,2662
+cmdo/display.py,sha256=ncGP1RmleyrX9VyGOnDzzwEu1n1_N9lE5ZheVI62Thk,4323
+cmdo/executor.py,sha256=J_LT9VShZ0TVjyo2M71pG-PkV0Qz5K3tlR8dGCUW5Y0,3229
+cmdo/models.py,sha256=QyFcT3WtC4TEbSnpufrxTH6CaEgUDttKzIkPoVWO7V4,1420
+cmdo/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cmdo/llm/client.py,sha256=xGZ3Zu4Q3Lxzp5xoPKljzDV7tme6v3oF4kbD0pS2muA,1739
+cmdo/llm/parser.py,sha256=8CHuCp-qY71qhrzpRD5Bv3vJ4eUxrZkeASJCr_iqD_s,1740
+cmdo/llm/prompt.py,sha256=LsWq4bXZ5ZsBnDw3dXLc54gcWXqoQsaSjLLWeD8bjg0,2572
+cmdo/safety/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cmdo/safety/classifier.py,sha256=DZJrw2BJcaPZF1xCEVA-BeMwjWNwuXMeBbzfIUwZhnw,2730
+cmdo/safety/forbidden.py,sha256=n6x0BsU5uye5gzS6h_opIV25vYY8exj9YHYVERFsoP8,986
+cmdo_cli-0.1.0.dist-info/licenses/LICENSE,sha256=jjc_D9cf5Mv3Lkf4EJAKytg4rN65jZIl6J5LHvys0x4,1064
+cmdo_cli-0.1.0.dist-info/METADATA,sha256=FWjqSsLV80wlRb8RMrsUeZG7WOJJqZ0j8mDfJ_Vb6H8,4369
+cmdo_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cmdo_cli-0.1.0.dist-info/entry_points.txt,sha256=CzKLGJtjwzHE1lry4iNM6GwKZu9RLW4BzX46R-nKSzI,39
+cmdo_cli-0.1.0.dist-info/top_level.txt,sha256=DMcTFo6H1jZoijIshDn0tX-GKn9ok5q6KXtOnXC_GT4,5
+cmdo_cli-0.1.0.dist-info/RECORD,,

cmdo_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cmdo_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cmdo = cmdo.cli:main

cmdo_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yijiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmdo_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmdo