shellmate-cli 3.0.0__py3-none-any.whl

shellmate/orchestration/state.py

@@ -0,0 +1,35 @@
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class AnalysisState(TypedDict, total=False):
+    # Existing v2 fields
+    command: str
+    sanitized: Optional[Dict[str, Any]]
+    parsed: Optional[Dict[str, Any]]
+    rule_match: Optional[Dict[str, Any]]
+    cached: Optional[Dict[str, Any]]
+    needs_context: bool
+    watcher_context: Optional[Dict[str, Any]]
+    librarian_context: Optional[Dict[str, Any]]
+    merged_context: Optional[Dict[str, Any]]
+    risk_analysis: Optional[Dict[str, Any]]
+    remediation: Optional[Dict[str, Any]]
+    output: Optional[Dict[str, Any]]
+    errors: List[str]
+    stages: Dict[str, float]
+    agent_latency: Dict[str, float]
+    early_exit: Optional[str]
+    supervisor_decision: Optional[Dict[str, Any]]
+    supervisor_fallback: bool
+    supervisor_warning: Optional[str]
+    command_guide: Optional[Dict[str, Any]]
+    
+    # NEW v3 fields
+    environment_context: Optional[Dict[str, Any]]  # From EnvironmentAgent
+    command_chain: List[Dict[str, Any]]           # Recent commands
+    chain_patterns: Dict[str, Any]                # Detected workflow patterns
+    user_queries: List[str]                       # Parsed [?...] queries
+    query_responses: Dict[str, str]               # Query answers
+    overrides: Dict[str, Any]                     # [@...] user overrides
+    risk_factors: Dict[str, float]                # Risk breakdown %
+    consequence_preview: Optional[Dict[str, Any]]  # Structured what-will-happen preview from consequence_builder

shellmate/parser/command_parser.py

@@ -0,0 +1,111 @@
+import shlex
+import re
+
+PIPE_PATTERN = re.compile(r"(\||&&|;|\|\|)")
+REDIRECT_PATTERN = re.compile(r"(?:^|[^<>])([<>]{1,2}|>&|<>|>>|<<)")
+
+SUPPORTED_SUBCOMMANDS = {
+    "git": ["add", "commit", "push", "pull", "clone", "checkout", "branch", "merge", "rebase", "log", "status", "diff", "fetch", "remote", "stash", "tag", "init", "config", "reset"],
+    "npm": ["install", "run", "test", "build", "start", "publish", "update", "audit", "init", "link", "uninstall"],
+    "docker": ["run", "exec", "build", "push", "pull", "ps", "images", "stop", "start", "restart", "rm", "logs", "compose"],
+    "kubectl": ["get", "apply", "delete", "describe", "logs", "exec", "create", "port-forward", "rollout"],
+    "pip": ["install", "uninstall", "list", "show", "freeze", "check"],
+    "brew": ["install", "uninstall", "update", "upgrade", "list", "search", "info", "services"],
+    "cargo": ["build", "run", "test", "check", "clippy", "add", "remove", "publish", "update"],
+    "go": ["run", "build", "test", "mod", "get", "install", "fmt", "vet"],
+    "uv": ["run", "add", "remove", "sync", "lock", "tool", "pip", "python"],
+    "pnpm": ["install", "add", "remove", "run", "test", "build", "start"],
+    "bun": ["run", "install", "add", "remove", "test", "build", "start"],
+    "deno": ["run", "test", "compile", "fmt", "lint", "cache", "bundle"],
+    "systemctl": ["start", "stop", "restart", "status", "enable", "disable", "daemon-reload"],
+    "service": ["start", "stop", "restart", "status"],
+    "apt": ["install", "remove", "update", "upgrade", "autoremove", "search"],
+    "yum": ["install", "remove", "update", "search", "list"],
+    "pacman": ["-S", "-R", "-Rns", "-U", "-Sy", "-Syu", "-Ss", "-Qs"],
+    "mkfs": [],  # mkfs has no subcommands, but needs to be recognized
+    "mkfs.ext4": [],  # Common mkfs variant
+}
+
+
+def parse_command(command_string):
+    stripped = command_string.strip()
+    if not stripped:
+        return {"program": None, "subcommand": None, "flags": [], "arguments": []}
+
+    segments = PIPE_PATTERN.split(stripped)
+    commands = []
+    current = ""
+    for segment in segments:
+        if segment in ("|", "&&", ";", "||"):
+            commands.append(("pipe" if segment == "|" else "operator", segment))
+        else:
+            if current:
+                commands.append(("command", _parse_single(current.strip())))
+                current = ""
+            current = segment.strip()
+
+    if current:
+        commands.append(("command", _parse_single(current.strip())))
+
+    if len(commands) == 1 and commands[0][0] == "command":
+        return commands[0][1]
+
+    return {
+        "pipeline": True,
+        "segments": commands,
+    }
+
+
+def _parse_single(command):
+    if not command or not command.strip():
+        return {"program": None, "subcommand": None, "flags": [], "arguments": []}
+
+    try:
+        tokens = shlex.split(command)
+    except ValueError as e:
+        return {
+            "program": None,
+            "subcommand": None,
+            "flags": [],
+            "arguments": [command],
+            "error": str(e),
+        }
+
+    if not tokens:
+        return {"program": None, "subcommand": None, "flags": [], "arguments": []}
+
+    program = tokens[0]
+    flags = []
+    arguments = []
+    subcommand = None
+
+    known_subcommands = SUPPORTED_SUBCOMMANDS.get(program, [])
+    i = 1
+    while i < len(tokens):
+        token = tokens[i]
+        if token.startswith("-"):
+            if "=" in token:
+                flag, _, value = token.partition("=")
+                flags.append({"flag": flag, "value": value})
+            else:
+                flags.append({"flag": token, "value": None})
+                if i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+                    if any(p in program for p in ("find", "grep", "sed", "awk")):
+                        flags[-1] = {"flag": token, "value": tokens[i + 1]}
+                        i += 1
+        else:
+            if subcommand is None and known_subcommands:
+                if token in known_subcommands:
+                    subcommand = token
+                else:
+                    arguments.append(token)
+            else:
+                arguments.append(token)
+        i += 1
+
+    return {
+        "program": program,
+        "subcommand": subcommand,
+        "flags": flags,
+        "arguments": arguments,
+    }

shellmate/plugins/base.py

@@ -0,0 +1,80 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ShellMatePlugin(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def version(self) -> str:
+        pass
+
+    @property
+    def author(self) -> str:
+        return "Unknown"
+
+    @property
+    def description(self) -> str:
+        return ""
+
+    @abstractmethod
+    def initialize(self, context: dict) -> None:
+        pass
+
+
+class RulePlugin(ShellMatePlugin):
+    @abstractmethod
+    def get_rules(self) -> list[dict]:
+        pass
+
+
+class DocumentationProviderPlugin(ShellMatePlugin):
+    @abstractmethod
+    async def retrieve(self, tool: str, query: str = None) -> dict:
+        pass
+
+
+class AIProviderPlugin(ShellMatePlugin):
+    @abstractmethod
+    def analyze_risk(self, command: str, context: dict = None) -> dict:
+        pass
+
+    @abstractmethod
+    def generate_remediation(self, command: str, risk: dict, context: dict = None) -> dict:
+        pass
+
+
+class TerminalAdapterPlugin(ShellMatePlugin):
+    @abstractmethod
+    def get_hook_script(self, shell: str) -> str:
+        pass
+
+    @abstractmethod
+    def get_supported_shells(self) -> list[str]:
+        pass
+
+
+PLUGIN_METADATA_SCHEMA = {
+    "name": str,
+    "version": str,
+    "author": str,
+    "description": str,
+    "entry_point": str,
+    "type": str,
+}
+
+
+def validate_plugin_metadata(metadata: dict) -> bool:
+    for key, expected_type in PLUGIN_METADATA_SCHEMA.items():
+        if key not in metadata:
+            return False
+        if not isinstance(metadata[key], expected_type):
+            return False
+    valid_types = {"rule", "documentation", "ai_provider", "terminal_adapter"}
+    if metadata.get("type") not in valid_types:
+        return False
+    return True

shellmate/plugins/loader.py

@@ -0,0 +1,41 @@
+import importlib
+import logging
+import os
+import sys
+from shellmate.config.defaults import get_default_config
+
+logger = logging.getLogger("shellmate.plugins")
+
+
+def discover_plugins():
+    config = get_default_config()
+    plugin_dir = config["plugins"]["directory"]
+
+    if not os.path.isdir(plugin_dir):
+        return []
+
+    if plugin_dir not in sys.path:
+        sys.path.insert(0, plugin_dir)
+
+    plugins = []
+    for item in sorted(os.listdir(plugin_dir)):
+        item_path = os.path.join(plugin_dir, item)
+        if os.path.isdir(item_path) and os.path.exists(os.path.join(item_path, "__init__.py")):
+            try:
+                module = importlib.import_module(item)
+                if hasattr(module, "register_plugin"):
+                    plugin = module.register_plugin()
+                    plugins.append(plugin)
+                    logger.info(f"Loaded plugin: {plugin.name} v{plugin.version}")
+                else:
+                    logger.debug(f"Skipping {item}: no register_plugin() function")
+            except Exception as e:
+                logger.error(f"Failed to load plugin {item}: {e}")
+
+    return plugins
+
+
+def load_plugin_class(entry_point: str):
+    module_name, class_name = entry_point.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)()

shellmate/providers/base.py

@@ -0,0 +1,97 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+# Env var names users configure via `sm config`
+PROVIDER_CREDENTIAL_KEYS = {
+    "groq": "GROQ_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "xai": "XAI_API_KEY",
+}
+
+
+class AIProvider(ABC):
+    @abstractmethod
+    def analyze_risk(self, command: str, context: Optional[dict] = None) -> dict:
+        pass
+
+    @abstractmethod
+    def generate_remediation(self, command: str, risk: dict, context: Optional[dict] = None) -> dict:
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        pass
+
+    async def close(self):
+        pass
+
+
+class ProviderError(Exception):
+    def __init__(self, message: str, provider: str, status_code: Optional[int] = None):
+        self.provider = provider
+        self.status_code = status_code
+        super().__init__(message)
+
+
+def credential_key_for(provider: str) -> str:
+    return PROVIDER_CREDENTIAL_KEYS.get(provider, f"{provider.upper()}_API_KEY")
+
+
+def _extract_status_code(exc: BaseException) -> Optional[int]:
+    for attr in ("status_code", "status", "http_status"):
+        val = getattr(exc, attr, None)
+        if isinstance(val, int):
+            return val
+    body = getattr(exc, "body", None)
+    if isinstance(body, dict):
+        err = body.get("error") or {}
+        if isinstance(err, dict) and err.get("code") == "invalid_api_key":
+            return 401
+    text = str(exc)
+    if "401" in text or "invalid_api_key" in text.lower() or "invalid api key" in text.lower():
+        return 401
+    if "403" in text:
+        return 403
+    if "429" in text:
+        return 429
+    return None
+
+
+def format_provider_failure(provider: str, exc: BaseException, purpose: str = "AI analysis") -> str:
+    """
+    User-facing error that names which credential failed.
+
+    Example: "AI analysis unavailable: GROQ_API_KEY is invalid (401). Run: sm config"
+    """
+    key = credential_key_for(provider)
+    status = getattr(exc, "status_code", None) if isinstance(exc, ProviderError) else None
+    if status is None:
+        status = _extract_status_code(exc)
+    raw = str(exc)
+
+    if status == 401 or "invalid_api_key" in raw.lower() or "invalid api key" in raw.lower():
+        return (
+            f"{purpose} unavailable: {key} is invalid or unauthorized (401). "
+            f"Update it with: sm config"
+        )
+    if status == 403:
+        return f"{purpose} unavailable: {key} was rejected (403). Check permissions or run: sm config"
+    if status == 429:
+        return f"{purpose} unavailable: {key} hit rate limits (429). Retry later."
+    if "not set" in raw.lower() or "environment variable" in raw.lower():
+        return f"{purpose} unavailable: {key} is not set. Configure with: sm config"
+    # Keep message short — avoid dumping provider JSON blobs
+    brief = raw.split(" - ", 1)[0].strip()
+    if len(brief) > 120:
+        brief = brief[:117] + "..."
+    return f"{purpose} unavailable ({key}): {brief}"
+
+
+def wrap_provider_exception(exc: BaseException, provider: str) -> ProviderError:
+    """Normalize SDK exceptions into ProviderError with status_code when possible."""
+    if isinstance(exc, ProviderError):
+        if exc.status_code is None:
+            exc.status_code = _extract_status_code(exc)
+        return exc
+    return ProviderError(str(exc), provider, status_code=_extract_status_code(exc))

shellmate/providers/groq_command_guide.py

@@ -0,0 +1,108 @@
+import asyncio
+import json
+import os
+import logging
+from typing import Optional
+
+from groq import AsyncGroq
+
+logger = logging.getLogger("shellmate.providers.groq_command_guide")
+
+COMMAND_GUIDE_PROMPT = '''You help a terminal user understand a shell command they typed.
+Respond ONLY with valid JSON:
+{{"intent_guess": "Maybe you're trying to ...", "when_to_use": "...", "parameters": ["arg: what it means"], "suggested_command": "full corrected command", "example_command": "git cherry-pick abc123"}}
+
+intent_guess: Start with "Maybe you're trying to" — infer what the user meant from their command, naming each token they typed and what it likely represents.
+when_to_use: 1-2 sentences on when to use this command.
+parameters: explain flags/positional args the user typed OR common ones for this tool; format "name: meaning".
+suggested_command: best guess of what they meant — fill paths/names from context (cwd, git branch, project files).
+example_command: a concrete runnable example using context when available.
+
+Command: {command}
+{risk_context}{context}'''
+
+
+class CommandGuideError(Exception):
+    pass
+
+
+def _parse_guide_json(content: str) -> dict:
+    content = content.strip()
+    if content.startswith("```"):
+        content = content.split("\n", 1)[1] if "\n" in content else content
+        if content.endswith("```"):
+            content = content[:-3]
+        content = content.strip()
+    data = json.loads(content)
+    return {
+        "intent_guess": str(data.get("intent_guess", "")),
+        "when_to_use": str(data.get("when_to_use", "")),
+        "parameters": list(data.get("parameters", [])),
+        "suggested_command": str(data.get("suggested_command", "")),
+        "example_command": str(data.get("example_command", "")),
+    }
+
+
+def alternatives_from_guide(guide: dict) -> list:
+    """Build user-facing suggestions from a command guide dict."""
+    if not guide:
+        return []
+    items = []
+    if guide.get("intent_guess"):
+        items.append(guide["intent_guess"])
+    for param in (guide.get("parameters") or [])[:4]:
+        items.append(param)
+    cmd = guide.get("suggested_command") or guide.get("example_command")
+    if cmd:
+        items.append(f"Try: {cmd}")
+    return items
+
+
+async def generate_command_guide(
+    command: str,
+    *,
+    context: Optional[str] = None,
+    risk_reason: Optional[str] = None,
+    model: Optional[str] = None,
+    timeout_ms: Optional[float] = None,
+) -> dict:
+    from shellmate.config.credentials import load_env
+
+    env = load_env()
+    api_key = os.environ.get("GROQ_API_KEY") or env.get("GROQ_API_KEY")
+    if not api_key:
+        raise CommandGuideError("GROQ_API_KEY not set")
+
+    if timeout_ms is None:
+        timeout_ms = float(os.environ.get("GROQ_COMMAND_GUIDE_TIMEOUT_MS", "2000"))
+
+    model = model or os.environ.get("GROQ_COMMAND_GUIDE_MODEL", "qwen/qwen3.8-27b")
+    client = AsyncGroq(api_key=api_key)
+    ctx = f"\n\nContext:\n{context}" if context else ""
+    risk_ctx = f"\nAnalysis note: {risk_reason}" if risk_reason else ""
+    prompt = COMMAND_GUIDE_PROMPT.format(command=command, risk_context=risk_ctx, context=ctx)
+
+    try:
+        async def _call():
+            response = await client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.0,
+                max_tokens=384,
+            )
+            return response.choices[0].message.content
+
+        content = await asyncio.wait_for(_call(), timeout=timeout_ms / 1000.0)
+        return _parse_guide_json(content)
+    except asyncio.TimeoutError:
+        raise CommandGuideError(f"Command guide timed out after {timeout_ms}ms")
+    except json.JSONDecodeError as e:
+        raise CommandGuideError(f"Invalid JSON: {e}")
+    except Exception as e:
+        raise CommandGuideError(str(e))
+    finally:
+        close = getattr(client, "aclose", None) or getattr(client, "close", None)
+        if close:
+            result = close()
+            if asyncio.iscoroutine(result):
+                await result

shellmate/providers/groq_provider.py

@@ -0,0 +1,127 @@
+import os
+import json
+import asyncio
+from typing import Optional
+from groq import AsyncGroq
+from .base import AIProvider, ProviderError
+
+
+def _format_context(context: Optional[dict]) -> str:
+    if not context:
+        return ""
+    parts = []
+    watcher = context.get("watcher", {})
+    if watcher:
+        parts.append("System Context:")
+        if watcher.get("os"):
+            parts.append(f"  OS: {watcher['os']}")
+        if watcher.get("shell"):
+            parts.append(f"  Shell: {watcher['shell']}")
+        if watcher.get("current_directory"):
+            parts.append(f"  Directory: {watcher['current_directory']}")
+        git = watcher.get("git_context")
+        if git:
+            git_parts = []
+            if git.get("branch"):
+                git_parts.append(f"branch={git['branch']}")
+            if git.get("staged"):
+                git_parts.append(f"staged={git['staged']}")
+            if git.get("unstaged"):
+                git_parts.append(f"unstaged={git['unstaged']}")
+            if git_parts:
+                parts.append(f"  Git: {', '.join(git_parts)}")
+        stack = watcher.get("tech_stack")
+        if stack:
+            parts.append(f"  Tech stack: {', '.join(stack[:5])}")
+    librarian = context.get("librarian", {})
+    if librarian and librarian.get("matches"):
+        parts.append("\nRelevant project files:")
+        for m in librarian["matches"][:3]:
+            path = m.get("file", m.get("path", "?"))
+            snippet = m.get("content", m.get("snippet", ""))[:200]
+            parts.append(f"  - {path}: {snippet}")
+    if not parts:
+        return ""
+    return "\n" + "\n".join(parts)
+
+
+class GroqProvider(AIProvider):
+    def __init__(self):
+        self.api_key = os.environ.get("GROQ_API_KEY")
+        self.client = None
+        self.model = os.environ.get("GROQ_MODEL", "qwen/qwen3.8-27b")
+
+    def _ensure_client(self):
+        if not self.api_key:
+            raise ProviderError("GROQ_API_KEY environment variable not set", "groq")
+        if self.client is None:
+            self.client = AsyncGroq(api_key=self.api_key)
+
+    async def analyze_risk(self, command: str, context: Optional[dict] = None) -> dict:
+        self._ensure_client()
+
+        context_str = _format_context(context)
+        prompt = (
+            "You are a command safety analyzer. Analyze the following shell command and classify its risk level. "
+            "Respond ONLY with valid JSON in this exact format:\n"
+            '{"risk": "SAFE|LOW|MEDIUM|HIGH|CRITICAL", "confidence": 0.0-1.0, "reason": "brief explanation"}\n\n'
+            f"Command: {command}"
+            f"{context_str}"
+        )
+
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.1,
+                max_tokens=256,
+            )
+
+            content = response.choices[0].message.content.strip()
+            if content.startswith("```"):
+                content = content.split("\n", 1)[1] if "\n" in content else content
+                if content.endswith("```"):
+                    content = content[:-3]
+                content = content.strip()
+
+            result = json.loads(content)
+            result["provider"] = "groq"
+            result["model"] = self.model
+            return result
+
+        except json.JSONDecodeError as e:
+            raise ProviderError(f"Invalid JSON response: {e}", "groq")
+        except ProviderError:
+            raise
+        except Exception as e:
+            from .base import wrap_provider_exception
+            raise wrap_provider_exception(e, "groq")
+
+    async def generate_remediation(self, command: str, risk: dict, context: Optional[dict] = None) -> dict:
+        raise NotImplementedError("Groq provider only handles risk analysis")
+
+    async def close(self):
+        if self.client is not None:
+            close = getattr(self.client, "aclose", None) or getattr(self.client, "close", None)
+            if close:
+                result = close()
+                if asyncio.iscoroutine(result):
+                    await result
+            self.client = None
+
+    def is_available(self) -> bool:
+        return bool(self.api_key)
+
+    async def list_available_models(self) -> Optional[list]:
+        """Model ids this key can access, or None if the listing call fails.
+
+        Used by the daemon startup check to detect a configured model that the
+        account cannot reach (which would otherwise silently fall back to a
+        static MEDIUM rating). Never raises.
+        """
+        try:
+            self._ensure_client()
+            response = await self.client.models.list()
+            return [m.id for m in response.data]
+        except Exception:
+            return None

shellmate/providers/groq_supervisor.py

@@ -0,0 +1,78 @@
+import asyncio
+import json
+import os
+import logging
+from typing import Optional
+
+from groq import AsyncGroq
+from shellmate.providers.base import ProviderError
+
+logger = logging.getLogger("shellmate.providers.groq_supervisor")
+
+SUPERVISOR_PROMPT = '''You route shell-command analysis to context workers.
+Respond ONLY with valid JSON:
+{{"run_watcher": true|false, "run_librarian": true|false}}
+
+run_watcher: true when command needs OS/shell/git/env context (git, docker, cd, env vars).
+run_librarian: true when command references project files or needs repo search.
+Both can be true. Both can be false for trivial commands (echo hello).
+
+Command: {command}'''
+
+
+class SupervisorError(Exception):
+    pass
+
+
+def _parse_supervisor_json(content: str) -> dict:
+    content = content.strip()
+    if content.startswith("```"):
+        content = content.split("\n", 1)[1] if "\n" in content else content
+        if content.endswith("```"):
+            content = content[:-3]
+        content = content.strip()
+    data = json.loads(content)
+    return {
+        "run_watcher": bool(data.get("run_watcher", False)),
+        "run_librarian": bool(data.get("run_librarian", False)),
+    }
+
+
+async def route_command(
+    command: str,
+    *,
+    model: Optional[str] = None,
+    timeout_ms: float = 500,
+) -> dict:
+    api_key = os.environ.get("GROQ_API_KEY")
+    if not api_key:
+        raise SupervisorError("GROQ_API_KEY not set")
+
+    model = model or os.environ.get("GROQ_SUPERVISOR_MODEL", "qwen/qwen3.8-27b")
+    client = AsyncGroq(api_key=api_key)
+    prompt = SUPERVISOR_PROMPT.format(command=command)
+
+    try:
+        async def _call():
+            response = await client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.0,
+                max_tokens=64,
+            )
+            return response.choices[0].message.content
+
+        content = await asyncio.wait_for(_call(), timeout=timeout_ms / 1000.0)
+        return _parse_supervisor_json(content)
+    except asyncio.TimeoutError:
+        raise SupervisorError(f"Supervisor timed out after {timeout_ms}ms")
+    except json.JSONDecodeError as e:
+        raise SupervisorError(f"Invalid JSON: {e}")
+    except Exception as e:
+        raise SupervisorError(str(e))
+    finally:
+        close = getattr(client, "aclose", None) or getattr(client, "close", None)
+        if close:
+            result = close()
+            if asyncio.iscoroutine(result):
+                await result