Add command validation system with strict mode and CLI options

- Implement validator module with OS/shell compatibility checks
- Add --no-strict-validation flag for translate and run commands
- Support environment variable overrides for validation settings
- Include comprehensive unit tests for command validation
- Update documentation with new validation options and examples

Author: siddhantparadox

README.md

@@ -84,6 +84,7 @@ CommandRex can be invoked using either `commandrex` or `python -m commandrex` fo
 For example:
 - `commandrex run` - Start interactive mode with multi-command selection
 - `commandrex translate "query"` - Translate a natural language query
+- `commandrex translate "query" --no-strict-validation` - Translate without strict env validation (per-invocation)
 - `commandrex explain "command"` - Explain a shell command
 
 ### Interactive Mode
@@ -100,6 +101,7 @@ This launches CommandRex in interactive mode with a welcome screen displaying "C
 
 **Options:**
 - `--debug` or `-d`: Enable debug mode with detailed system information
+- `--no-strict-validation`: Disable strict environment validation for this run/translation
 - `--api-key YOUR_KEY`: Use a specific OpenAI API key for this session
 - `--model MODEL_NAME`: Specify an OpenAI model (default: gpt-4.1-mini-2025-04-14)
 - `--translate "query"` or `-t "query"`: Directly translate a query without entering interactive mode
@@ -122,6 +124,7 @@ commandrex translate "list all files in the current directory including hidden o
 - `--multi-select`: Present multiple command options to choose from interactively
 - `--api-key YOUR_KEY`: Use a specific OpenAI API key for this translation
 - `--model MODEL_NAME`: Specify an OpenAI model (default: gpt-4.1-mini-2025-04-14)
+- `--no-strict-validation`: Disable strict validation for this translation (shows guidance instead of blocking)
 
 **Examples:**
 ```bash

commandrex/config/settings.py

@@ -50,6 +50,14 @@ class Settings:
             "allow_file_operations": True,
             "dangerous_commands_require_confirmation": True,
         },
+        "validation": {
+            # Strictly reject commands incompatible with OS/shell
+            "strict_mode": True,
+            # Phase 2 placeholder: attempt auto transform of incompatible commands
+            "auto_transform": False,
+            # Offer alternative compatible commands when strict_mode blocks
+            "suggest_alternatives": True,
+        },
         "advanced": {
             "debug_mode": False,
             "log_level": "INFO",
@@ -70,6 +78,9 @@ def __init__(self):
         if self.config_file.exists():
             self.load()
 
+        # Apply environment overrides after file load
+        self._apply_env_overrides()
+
     def _get_config_dir(self) -> Path:
         """
         Get the configuration directory for the application.
@@ -188,6 +199,39 @@ def set(self, section: str, key: str, value: Any) -> bool:
             print(f"Error setting {section}.{key}: {e}")
             return False
 
+    def _apply_env_overrides(self) -> None:
+        """
+        Apply environment variable overrides for selected settings.
+
+        Supported overrides:
+          - COMMANDREX_VALIDATION_STRICT_MODE -> validation.strict_mode (bool)
+          - COMMANDREX_VALIDATION_AUTO_TRANSFORM -> validation.auto_transform (bool)
+          - COMMANDREX_VALIDATION_SUGGEST_ALTERNATIVES
+            -> validation.suggest_alternatives (bool)
+        """
+
+        def _env_bool(name: str, default: Optional[bool]) -> Optional[bool]:
+            val = os.environ.get(name)
+            if val is None:
+                return default
+            val_lower = val.strip().lower()
+            if val_lower in {"1", "true", "yes", "on"}:
+                return True
+            if val_lower in {"0", "false", "no", "off"}:
+                return False
+            return default
+
+        strict = _env_bool("COMMANDREX_VALIDATION_STRICT_MODE", None)
+        auto_tf = _env_bool("COMMANDREX_VALIDATION_AUTO_TRANSFORM", None)
+        suggest = _env_bool("COMMANDREX_VALIDATION_SUGGEST_ALTERNATIVES", None)
+
+        if strict is not None:
+            self.set("validation", "strict_mode", strict)
+        if auto_tf is not None:
+            self.set("validation", "auto_transform", auto_tf)
+        if suggest is not None:
+            self.set("validation", "suggest_alternatives", suggest)
+
     def get_all(self) -> Dict[str, Dict[str, Any]]:
         """
         Get all settings.

commandrex/executor/shell_manager.py

@@ -12,6 +12,7 @@
 import threading
 from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
+from commandrex.config.settings import settings
 from commandrex.executor import platform_utils
 from commandrex.executor.command_parser import CommandParser
 
@@ -294,13 +295,24 @@ async def read_stream(stream, chunks, callback):
 
             except asyncio.TimeoutError:
                 # Terminate the process if it times out
-                process.terminate()
+                import inspect
+
+                term = getattr(process, "terminate", None)
+                if callable(term) and inspect.iscoroutinefunction(term):
+                    await term()
+                elif callable(term):
+                    term()
+
                 try:
                     # Give it a chance to terminate gracefully
                     await asyncio.wait_for(process.wait(), 2.0)
                 except asyncio.TimeoutError:
                     # Force kill if it doesn't terminate
-                    process.kill()
+                    kill = getattr(process, "kill", None)
+                    if callable(kill) and inspect.iscoroutinefunction(kill):
+                        await kill()
+                    elif callable(kill):
+                        kill()
                     await process.wait()
 
                 terminated = True
@@ -407,7 +419,7 @@ async def execute_command_safely(
         validation_info = {}
 
         if validate:
-            # Validate the command
+            # Validate the command (syntactic/danger checks from parser)
             validation_info = self.command_parser.validate_command(command)
 
             if not validation_info["is_valid"]:
@@ -418,6 +430,39 @@ async def execute_command_safely(
                 reasons = ", ".join(validation_info["reasons"])
                 raise ValueError(f"Dangerous command: {reasons}")
 
+            # Environment-aware strict validation: ensure command matches OS/shell
+            try:
+                from commandrex.validator.command_validator import (
+                    CommandValidator,  # noqa: E402
+                )
+
+                env_validator = CommandValidator()
+                env = env_validator.detect_environment()
+                shell_name = env.get("shell", "")
+                os_name = env.get("os", "")
+                env_result = env_validator.validate_for_environment(
+                    command, shell_override=shell_name, os_override=os_name
+                )
+                if not env_result.is_valid:
+                    reasons = "; ".join(env_result.reasons)
+                    msg = (
+                        "Incompatible command for environment "
+                        f"(OS={os_name}, shell={shell_name}): {reasons}"
+                    )
+                    # Honor settings toggle: strict_mode controls hard failure
+                    strict_mode = settings.get("validation", "strict_mode", True)
+                    suggest_alts = settings.get(
+                        "validation", "suggest_alternatives", True
+                    )
+                    if strict_mode:
+                        raise ValueError(msg)
+                    # Non-strict: attach reasons to validation_info for UI consumption
+                    if suggest_alts:
+                        validation_info["env_issues"] = env_result.reasons
+            except ImportError:
+                # If validator is unavailable, skip strict env validation
+                pass
+
         # Execute the command
         result = await self.execute_command(
             command, stdout_callback, stderr_callback, timeout, cwd, env

commandrex/main.py

@@ -372,6 +372,11 @@ def translate(
         "--multi-select",
         help="Present multiple command options to choose from before executing.",
     ),
+    no_strict_validation: bool = typer.Option(
+        False,
+        "--no-strict-validation",
+        help="Disable strict environment validation for this translation.",
+    ),
 ) -> None:
     """
     Translate natural language to a shell command.
@@ -401,6 +406,12 @@ def translate(
     # Create OpenAI client
     client = openai_client.OpenAIClient(api_key=api_key, model=model)
 
+    # Apply per-invocation toggle for strict validation
+    if no_strict_validation:
+        from commandrex.config.settings import settings as _settings
+
+        _settings.set("validation", "strict_mode", False)
+
     # Create prompt builder
     pb = prompt_builder.PromptBuilder()
 
@@ -812,6 +823,11 @@ def run(
         "-t",
         help="Directly translate a natural language query without interactive mode.",
     ),
+    no_strict_validation: bool = typer.Option(
+        False,
+        "--no-strict-validation",
+        help="Disable strict environment validation for this session.",
+    ),
 ) -> None:
     """
     Start the CommandRex terminal interface.
@@ -925,6 +941,10 @@ def signal_handler(sig, frame):
         if not check_api_key():
             raise typer.Exit(1)
 
+    # Apply per-invocation toggle for strict validation (session-wide)
+    if no_strict_validation:
+        settings.settings.set("validation", "strict_mode", False)
+
     # Display welcome screen for interactive mode (only when no direct query/translate)
     if not query and not translate_arg:
         display_welcome_screen(console)

commandrex/translator/openai_client.py

@@ -16,6 +16,7 @@
 
 # Import from our own modules
 from commandrex.config import api_manager
+from commandrex.config.settings import settings
 
 # Set up logging
 logger = logging.getLogger(__name__)
@@ -299,36 +300,72 @@ async def translate_to_command(
                 is_dangerous = response_data.get("is_dangerous", False)
                 alternatives = response_data.get("alternatives", [])
 
-                # Post-generation validation (phase 1 lite):
-                # Basic checks for forbidden tokens and path separators.
-                issues: List[str] = []
-                shell_rules = strict_rules.get(shell_key) if rules else None
-                if shell_rules:
-                    # Forbidden tokens
-                    for fbd in shell_rules["forbidden"]:
-                        # simple token existence check
-                        if f"{fbd} " in command or command.lower().startswith(fbd):
-                            issues.append(f"Forbidden command for {shell_key}: {fbd}")
-
-                    # Path separator check (only if command seems to contain a path)
-                    wrong_sep = shell_rules["wrong_sep"]
-                    right_sep = shell_rules["path_sep"]
-                    if wrong_sep in command and right_sep not in command:
-                        issues.append(
-                            f"Wrong path separator '{wrong_sep}' for shell {shell_key}"
-                        )
-
-                if issues:
-                    logger.warning(
-                        "LLM command did not pass environment validation: %s",
-                        issues,
+                # Post-generation validation (Phase 1 strict):
+                # Enforce environment-aware validation and reject incompatible commands.
+                # Respect settings toggles for strictness and suggestions.
+                strict_mode = settings.get("validation", "strict_mode", True)
+                suggest_alts = settings.get("validation", "suggest_alternatives", True)
+                try:
+                    from commandrex.validator.command_validator import (  # noqa: E402
+                        CommandValidator,
                     )
-                    # We do not auto-correct here in phase 1; only surface info.
-                    explanation = (
-                        explanation
-                        + "\nEnvironment validation issues detected: "
-                        + "; ".join(issues)
+
+                    validator = CommandValidator()
+                    # Use detected shell/os where possible
+                    os_name_val = os_name
+                    shell_name_val = shell_key
+                    validation = validator.validate_for_environment(
+                        command, shell_override=shell_name_val, os_override=os_name_val
                     )
+                    if not validation.is_valid:
+                        issues_text = "; ".join(validation.reasons)
+                        logger.error(
+                            "Rejected command due to environment validation: %s",
+                            issues_text,
+                        )
+                        if strict_mode:
+                            raise ValueError(
+                                "Generated command is incompatible with the current "
+                                f"environment: {issues_text}"
+                            )
+                        # Non-strict mode: keep the command but annotate explanation
+                        if suggest_alts:
+                            explanation = (
+                                f"{explanation}\nEnvironment validation issues: "
+                                + issues_text
+                            )
+                except ImportError:
+                    # If validator module is unavailable, fall back to previous
+                    # lite checks while keeping lines within E501 limits.
+                    issues: List[str] = []
+                    shell_rules = strict_rules.get(shell_key) if rules else None
+                    if shell_rules:
+                        for fbd in shell_rules["forbidden"]:
+                            starts_forbidden = command.lower().startswith(fbd)
+                            has_token = f"{fbd} " in command
+                            if has_token or starts_forbidden:
+                                issues.append(
+                                    f"Forbidden command for {shell_key}: {fbd}"
+                                )
+                        wrong_sep = shell_rules["wrong_sep"]
+                        right_sep = shell_rules["path_sep"]
+                        wrong_only = wrong_sep in command and right_sep not in command
+                        if wrong_only:
+                            issues.append(
+                                "Wrong path separator "
+                                f"'{wrong_sep}' for shell {shell_key}"
+                            )
+                    if issues:
+                        logger.warning(
+                            "LLM command did not pass environment validation "
+                            "(fallback): %s",
+                            issues,
+                        )
+                    if issues and suggest_alts:
+                        explanation = (
+                            f"{explanation}\nEnvironment validation issues detected: "
+                            + "; ".join(issues)
+                        )
 
                 return CommandTranslationResult(
                     command=command,