naturally-linux 0.1.0__tar.gz

naturally_linux-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: naturally-linux
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: groq>=1.0.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: typer>=0.21.1

naturally_linux-0.1.0/naturally_linux/__init__.py

@@ -0,0 +1,4 @@
+"""Naturally Linux package initializer."""
+
+# Expose the Typer app at package level if needed by external callers.
+from .cli import app  # noqa: F401

naturally_linux-0.1.0/naturally_linux/__main__.py

@@ -0,0 +1,12 @@
+"""Run the Typer app with python -m naturally_linux."""
+
+from .cli import app
+
+
+def main() -> None:
+    # Ensure help shows the intended CLI name when invoked via python -m.
+    app(prog_name="naturally-linux")
+
+
+if __name__ == "__main__":
+    main()

naturally_linux-0.1.0/naturally_linux/cli.py

@@ -0,0 +1,91 @@
+"""Typer CLI entrypoint for Naturally Linux."""
+
+import typer
+
+from .executor import run_command
+from .generator import explain_command, generate_command
+from .safety import is_safe_command
+
+# Create the Typer app instance.
+# This object registers and groups all CLI commands.
+app = typer.Typer(
+    help="Naturally Linux: run shell tasks using natural language.")
+
+
+@app.command()
+def run(
+    prompt: str = typer.Argument(...,
+                                 help="Natural language task description."),
+    auto_approve: bool = typer.Option(
+        False, "--yes", "-y", help="Auto-approve without confirmation."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview command without executing it."
+    ),
+):
+    """
+    Convert a natural-language instruction into a shell command,
+    display it, and optionally execute it.
+    """
+
+    # Step 1: Ask the generator to produce a shell command.
+    command = generate_command(prompt)
+
+    # Step 2: Run safety checks on the generated command.
+    if not is_safe_command(command):
+        typer.secho("Potentially unsafe command detected.",
+                    fg=typer.colors.RED)
+        if not auto_approve and not typer.confirm("Proceed anyway?", default=False):
+            raise typer.Abort()
+
+    # Step 3: Show the user the proposed command.
+    typer.secho("Proposed command:", fg=typer.colors.CYAN)
+    typer.echo(command)
+
+    # Step 4: If dry-run, explain the command and optionally execute.
+    if dry_run:
+        try:
+            explanation = explain_command(command)
+            if explanation:
+                typer.secho("\nExplanation:", fg=typer.colors.GREEN)
+                typer.echo(explanation)
+        except RuntimeError as exc:
+            typer.secho(str(exc), fg=typer.colors.YELLOW)
+
+        safety_label = "SAFE" if is_safe_command(command) else "UNSAFE"
+        safety_color = typer.colors.GREEN if safety_label == "SAFE" else typer.colors.RED
+        typer.secho(f"\nSafety check: {safety_label}", fg=safety_color)
+
+        if auto_approve or typer.confirm("Run this command now?", default=False):
+            stdout, stderr, returncode = run_command(command)
+
+            if stdout:
+                typer.echo(stdout)
+
+            if stderr:
+                typer.secho(stderr, fg=typer.colors.YELLOW)
+
+            if returncode != 0:
+                raise typer.Exit(code=returncode)
+
+        typer.secho(
+            "\nDry run mode — command not executed.",
+            fg=typer.colors.YELLOW,
+        )
+        return
+
+    # Step 5: Ask for confirmation unless auto-approved.
+    if not auto_approve and not typer.confirm("Run this command?", default=False):
+        raise typer.Abort()
+
+    # Step 6: Execute the command and surface output.
+    stdout, stderr, returncode = run_command(command)
+
+    if stdout:
+        typer.echo(stdout)
+
+    if stderr:
+        typer.secho(stderr, fg=typer.colors.YELLOW)
+
+    if returncode != 0:
+        raise typer.Exit(code=returncode)

naturally_linux-0.1.0/naturally_linux/executor.py

@@ -0,0 +1,23 @@
+"""Command execution helpers."""
+
+import subprocess
+from typing import Tuple
+
+
+def run_command(command: str) -> Tuple[str, str, int]:
+    """
+    Execute a shell command and return (stdout, stderr, returncode).
+
+    TODO:
+    - Consider a safer execution strategy (no shell, explicit args).
+    - Add timeouts and resource limits.
+    """
+
+    result = subprocess.run(
+        command,
+        shell=True,
+        text=True,
+        capture_output=True,
+    )
+
+    return result.stdout, result.stderr, result.returncode

naturally_linux-0.1.0/naturally_linux/generator.py

@@ -0,0 +1,78 @@
+"""Prompt → command generator (Groq LLM integration)."""
+
+import os
+
+from dotenv import load_dotenv
+from groq import Groq
+
+load_dotenv()
+
+SYSTEM_PROMPT = (
+    "You are a Linux command generator. "
+    "Return ONLY the exact shell command to accomplish the user's task. "
+    "Do NOT include explanations, markdown, code fences, or extra text. "
+    "If multiple commands are required, chain them with &&. "
+    "Assume a POSIX shell."
+)
+
+EXPLAIN_PROMPT = (
+    "You are a Linux command explainer. "
+    "Explain succinctly what the command does and any notable risks. "
+    "Do NOT include markdown, code fences, or extra text beyond the explanation."
+)
+
+
+def generate_command(prompt: str) -> str:
+    """
+    Generate a shell command from a natural language prompt using Groq.
+
+    Requires the GROQ_API_KEY environment variable to be set.
+    """
+
+    api_key = os.environ.get("GROQ_API_KEY")
+    if not api_key:
+        raise RuntimeError("GROQ_API_KEY is not set")
+
+    client = Groq(api_key=api_key)
+
+    chat_completion = client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ],
+        temperature=0.2,
+        max_tokens=200,
+    )
+
+    content = (chat_completion.choices[0].message.content or "").strip()
+
+    # Ensure we return only a single command line.
+    return content.splitlines()[0].strip()
+
+
+def explain_command(command: str) -> str:
+    """
+    Explain a shell command in plain language using Groq.
+
+    Requires the GROQ_API_KEY environment variable to be set.
+    """
+
+    api_key = os.environ.get("GROQ_API_KEY")
+    if not api_key:
+        raise RuntimeError("GROQ_API_KEY is not set")
+
+    client = Groq(api_key=api_key)
+
+    chat_completion = client.chat.completions.create(
+        model="llama-3.3-70b-versatile",
+        messages=[
+            {"role": "system", "content": EXPLAIN_PROMPT},
+            {"role": "user", "content": command},
+        ],
+        temperature=0.2,
+        max_tokens=200,
+    )
+
+    content = (chat_completion.choices[0].message.content or "").strip()
+    return content

naturally_linux-0.1.0/naturally_linux/safety.py

@@ -0,0 +1,29 @@
+"""Safety checks for generated shell commands."""
+
+from typing import Iterable
+
+
+def _dangerous_patterns() -> Iterable[str]:
+    """
+    Return a small blacklist of patterns that should require explicit approval.
+
+    TODO:
+    - Replace with a richer ruleset (regex, parsing, allow/deny lists).
+    - Add OS-specific checks and context-aware risk assessment.
+    """
+
+    return [
+        "rm -rf",  # recursive delete
+        "mkfs",    # format filesystem
+        "dd if=",  # raw disk writes
+        ":(){",    # fork bomb
+        "shutdown",
+        "reboot",
+    ]
+
+
+def is_safe_command(command: str) -> bool:
+    """Return True if the command appears safe, False otherwise."""
+
+    lowered = command.lower()
+    return not any(pattern in lowered for pattern in _dangerous_patterns())

naturally_linux-0.1.0/naturally_linux.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: naturally-linux
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: groq>=1.0.0
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: typer>=0.21.1

naturally_linux-0.1.0/naturally_linux.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+naturally_linux/__init__.py
+naturally_linux/__main__.py
+naturally_linux/cli.py
+naturally_linux/executor.py
+naturally_linux/generator.py
+naturally_linux/safety.py
+naturally_linux.egg-info/PKG-INFO
+naturally_linux.egg-info/SOURCES.txt
+naturally_linux.egg-info/dependency_links.txt
+naturally_linux.egg-info/entry_points.txt
+naturally_linux.egg-info/requires.txt
+naturally_linux.egg-info/top_level.txt
+tests/test_executor.py
+tests/test_generator.py
+tests/test_safety.py

naturally_linux-0.1.0/naturally_linux.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

naturally_linux-0.1.0/naturally_linux.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+naturally-linux = naturally_linux.cli:app

naturally_linux-0.1.0/naturally_linux.egg-info/requires.txt

@@ -0,0 +1,4 @@
+groq>=1.0.0
+pytest>=9.0.2
+python-dotenv>=1.2.1
+typer>=0.21.1

naturally_linux-0.1.0/naturally_linux.egg-info/top_level.txt

@@ -0,0 +1 @@
+naturally_linux

naturally_linux-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "naturally-linux"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "groq>=1.0.0",
+    "pytest>=9.0.2",
+    "python-dotenv>=1.2.1",
+    "typer>=0.21.1",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["naturally_linux*"]
+
+[project.scripts]
+naturally-linux = "naturally_linux.cli:app"

naturally_linux-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

naturally_linux-0.1.0/tests/test_executor.py

@@ -0,0 +1,10 @@
+"""Tests for command execution."""
+
+from naturally_linux.executor import run_command
+
+
+def test_run_command_echo():
+    stdout, stderr, returncode = run_command("echo hello")
+    assert returncode == 0
+    assert "hello" in stdout
+    assert stderr == ""

naturally_linux-0.1.0/tests/test_generator.py

@@ -0,0 +1,33 @@
+"""Tests for command generator."""
+
+from types import SimpleNamespace
+
+import naturally_linux.generator as generator
+
+
+class _FakeGroq:
+    """Minimal fake Groq client for tests."""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+
+    class chat:
+        class completions:
+            @staticmethod
+            def create(*_args, **_kwargs):
+                return SimpleNamespace(
+                    choices=[
+                        SimpleNamespace(
+                            message=SimpleNamespace(content="ls -la")
+                        )
+                    ]
+                )
+
+
+def test_generate_command_returns_string(monkeypatch):
+    monkeypatch.setenv("GROQ_API_KEY", "test-key")
+    monkeypatch.setattr(generator, "Groq", _FakeGroq)
+
+    result = generator.generate_command("list files")
+    assert isinstance(result, str)
+    assert result == "ls -la"

naturally_linux-0.1.0/tests/test_safety.py

@@ -0,0 +1,11 @@
+"""Tests for safety checks."""
+
+from naturally_linux.safety import is_safe_command
+
+
+def test_is_safe_command_allows_benign():
+    assert is_safe_command("ls -la") is True
+
+
+def test_is_safe_command_blocks_dangerous():
+    assert is_safe_command("rm -rf /") is False