forgex-cli 0.1.0__py3-none-any.whl

forgex/tools/git.py

@@ -0,0 +1,239 @@
+"""Git primitives and agent tools (spec section 21).
+
+The checkpoint system: `git_checkpoint` commits all current work with a
+'forgex:' message (identity falls back to FORGEX <forgex@localhost> when
+the user has none configured). Non-destructive: commits preserve work.
+Checkpoint metadata + `forgex checkpoint/rollback` CLI arrive in Phase 6.
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("forgex.git")
+
+MAX_DIFF_BYTES = 50_000
+_EXCLUDE_FORGEX = [":(exclude).forgex"]
+
+
+@dataclass
+class GitResult:
+    rc: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.rc == 0
+
+
+def _git(args: list[str], cwd: Path) -> GitResult | None:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        return GitResult(rc=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def has_git_repo(root: Path) -> bool:
+    return (root / ".git").exists()
+
+
+def current_branch(root: Path) -> str | None:
+    r = _git(["rev-parse", "--abbrev-ref", "HEAD"], root)
+    return r.stdout.strip() if r and r.ok else None
+
+
+def is_dirty(root: Path) -> bool | None:
+    r = _git(["status", "--porcelain"], root)
+    if r is None or not r.ok:
+        return None
+    lines = [ln for ln in r.stdout.splitlines() if ".forgex" not in ln]
+    return bool(lines)
+
+
+def git_status(root: Path) -> str:
+    if not has_git_repo(root):
+        return "not a git repository"
+    r = _git(["status", "--short"], root)
+    return r.stdout.strip() if r and r.ok else "git status failed"
+
+
+def git_diff(root: Path, *, staged: bool = False) -> str:
+    if not has_git_repo(root):
+        return "not a git repository"
+    args = ["diff"] + (["--cached"] if staged else []) + ["--", "."] + _EXCLUDE_FORGEX
+    r = _git(args, root)
+    if r is None or not r.ok:
+        return "git diff failed"
+    out = r.stdout
+    if len(out) > MAX_DIFF_BYTES:
+        out = out[:MAX_DIFF_BYTES] + "\n... [diff truncated]"
+    return out
+
+
+def git_diff_range(root: Path, base_commit: str) -> str:
+    if not has_git_repo(root):
+        return "not a git repository"
+    args = ["diff", base_commit, "HEAD", "--", "."] + _EXCLUDE_FORGEX
+    r = _git(args, root)
+    if r is None or not r.ok:
+        return "(no diff available)"
+    out = r.stdout
+    if len(out) > MAX_DIFF_BYTES:
+        out = out[:MAX_DIFF_BYTES] + "\n... [diff truncated]"
+    return out
+
+
+def git_diff_stat(root: Path, target_commit: str) -> str:
+    r = _git(["diff", "--stat", "HEAD", target_commit], root)
+    return r.stdout.strip() if r and r.ok else "(no diff preview available)"
+
+
+def git_changed_files(root: Path, base_commit: str | None = None) -> list[str]:
+    if not has_git_repo(root):
+        return []
+    if base_commit:
+        r = _git(["diff", "--name-only", base_commit, "HEAD", "--", "."] + _EXCLUDE_FORGEX, root)
+        if r is None or not r.ok:
+            return []
+        return [ln.strip() for ln in r.stdout.splitlines() if ln.strip()]
+
+    r = _git(["status", "--porcelain"], root)
+    if r is None or not r.ok:
+        return []
+    files: list[str] = []
+    for line in r.stdout.splitlines():
+        if not line.strip():
+            continue
+        # Format: XY filename or XY orig -> new
+        name = line[3:].strip()
+        if " -> " in name:
+            name = name.split(" -> ")[1].strip()
+        if name.startswith(".forgex/") or name == ".forgex":
+            continue
+        files.append(name)
+    return files
+
+
+def git_log(root: Path, limit: int = 10) -> str:
+    if not has_git_repo(root):
+        return "not a git repository"
+    r = _git(["log", f"-n{limit}", "--format=%H %s"], root)
+    return r.stdout.strip() if r and r.ok else "git log failed"
+
+
+def _has_user_identity(root: Path) -> bool:
+    name = _git(["config", "user.name"], root)
+    email = _git(["config", "user.email"], root)
+    return bool(name and name.ok and name.stdout.strip() and email and email.ok and email.stdout.strip())
+
+
+def _ensure_git_exclude_forgex(root: Path) -> None:
+    exclude_file = root / ".git" / "info" / "exclude"
+    if exclude_file.is_file():
+        try:
+            content = exclude_file.read_text(encoding="utf-8")
+            if ".forgex" not in content:
+                exclude_file.write_text(content.rstrip() + "\n.forgex\n.forgex/**\n", encoding="utf-8")
+        except Exception:
+            pass
+
+
+def git_checkpoint(root: Path, label: str) -> str | None:
+    if not has_git_repo(root):
+        return None
+
+    _ensure_git_exclude_forgex(root)
+
+    # Check current HEAD commit before committing
+    head_before = _git(["rev-parse", "HEAD"], root)
+
+    _git(["add", "-A", "--", ".", ":(exclude).forgex"], root)
+    commit_args = ["commit", "-m", f"forgex: {label}", "--allow-empty-message"]
+    if not _has_user_identity(root):
+        commit_args = [
+            "-c", "user.name=FORGEX",
+            "-c", "user.email=forgex@localhost",
+            *commit_args,
+        ]
+    _git(commit_args, root)
+    head_after = _git(["rev-parse", "HEAD"], root)
+
+    if head_after and head_after.ok:
+        return head_after.stdout.strip()
+    return head_before.stdout.strip() if head_before and head_before.ok else None
+
+
+def git_reset_hard(root: Path, commit: str) -> bool:
+    r = _git(["reset", "--hard", commit], root)
+    return bool(r and r.ok)
+
+
+# Agent tools factory
+def create_tools() -> list[Any]:
+    from forgex.sandbox.permissions import Permission
+    from forgex.tools.base import SimpleTool, ToolCall, ToolContext, ToolResult
+
+    async def _tool_status(call: ToolCall, ctx: ToolContext) -> ToolResult:
+        st = git_status(ctx.workspace)
+        return ToolResult(ok=True, output=st)
+
+    async def _tool_diff(call: ToolCall, ctx: ToolContext) -> ToolResult:
+        staged = bool(call.arguments.get("staged", False))
+        diff = git_diff(ctx.workspace, staged=staged)
+        return ToolResult(ok=True, output=diff)
+
+    async def _tool_log(call: ToolCall, ctx: ToolContext) -> ToolResult:
+        limit = int(call.arguments.get("limit", 10))
+        lg = git_log(ctx.workspace, limit=limit)
+        return ToolResult(ok=True, output=lg)
+
+    async def _tool_checkpoint(call: ToolCall, ctx: ToolContext) -> ToolResult:
+        label = str(call.arguments.get("label", "manual"))
+        c = git_checkpoint(ctx.workspace, label)
+        if c is None:
+            return ToolResult(ok=False, error="git checkpoint failed (no git repo or commit error)")
+        return ToolResult(ok=True, output=f"checkpoint created: {c[:8]} ({label})", data={"commit": c})
+
+    return [
+        SimpleTool(
+            name="git_status",
+            handler=_tool_status,
+            permissions={Permission.GIT},
+            description="Show the working tree status.",
+            parameters={"type": "object", "properties": {}, "additionalProperties": False},
+        ),
+        SimpleTool(
+            name="git_diff",
+            handler=_tool_diff,
+            permissions={Permission.GIT},
+            description="Show changes between commits, commit and working tree, etc.",
+            parameters={"type": "object", "properties": {"staged": {"type": "boolean"}}, "additionalProperties": False},
+        ),
+        SimpleTool(
+            name="git_log",
+            handler=_tool_log,
+            permissions={Permission.GIT},
+            description="Show recent commit logs.",
+            parameters={"type": "object", "properties": {"limit": {"type": "integer"}}, "additionalProperties": False},
+        ),
+        SimpleTool(
+            name="git_checkpoint",
+            handler=_tool_checkpoint,
+            permissions={Permission.GIT},
+            description="Create a Git checkpoint of current workspace changes.",
+            parameters={"type": "object", "properties": {"label": {"type": "string"}}, "required": ["label"], "additionalProperties": False},
+        ),
+    ]

forgex/tools/project.py

@@ -0,0 +1,39 @@
+"""project_info tool — what an agent first sees about the repository."""
+
+from __future__ import annotations
+
+from forgex.project import detect_project
+from forgex.sandbox.permissions import Permission
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+from forgex.tools.git import current_branch, is_dirty
+
+
+async def _project_info(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    detection = detect_project(ctx.workspace)
+    branch = current_branch(ctx.workspace)
+    dirty = is_dirty(ctx.workspace) if branch else None
+    git_state = f"{branch} ({'dirty' if dirty else 'clean'})" if branch else "not a git repository"
+    output = "\n".join(
+        [
+            f"Project:    {detection.summary()}",
+            f"Workspace:  {ctx.workspace}",
+            f"Git:        {git_state}",
+        ]
+    )
+    return ToolResult(
+        ok=True,
+        output=output,
+        data={**detection.as_dict(), "git": {"branch": branch, "dirty": dirty}},
+    )
+
+
+def create_tools() -> list[Tool]:
+    return [
+        SimpleTool(
+            name="project_info",
+            handler=_project_info,
+            permissions={Permission.READ},
+            description="Overview of the project: languages, frameworks, package managers, git state.",
+            parameters={"type": "object", "properties": {}, "additionalProperties": False},
+        ),
+    ]

forgex/tools/search.py

@@ -0,0 +1,205 @@
+"""Search tools (spec sections 3, 18, 46): ripgrep when available, pure-Python fallback."""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import re
+import shutil
+from pathlib import Path
+
+from forgex.sandbox.permissions import Permission
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+from forgex.tools.filesystem import IGNORED_DIRS, is_secret_file
+from forgex.utils.redact import redact_patterns
+
+MAX_MATCHES = 200
+MAX_SCAN_FILES = 5_000
+TEXT_SUFFIX_SKIP = {
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".pdf", ".zip",
+    ".gz", ".tar", ".bin", ".exe", ".dll", ".so", ".dylib", ".db",
+    ".sqlite", ".sqlite3", ".woff", ".woff2", ".ttf", ".class",
+}
+
+
+def _rg_available() -> bool:
+    return shutil.which("rg") is not None
+
+
+async def _rg_search(
+    root: Path, query: str, glob: str | None, *, regex: bool, limit: int
+) -> tuple[list[str], bool]:
+    argv = [
+        "rg",
+        "--line-number",
+        "--no-heading",
+        "--color",
+        "never",
+        "--smart-case" if regex else "--fixed-strings",
+    ]
+    for ignored in IGNORED_DIRS:
+        argv.extend(["--glob", f"!{ignored}/**"])
+    argv.extend(["--glob", "!.env*"])
+    if glob:
+        argv.extend(["--glob", glob])
+    argv.extend(["--", query, str(root)])
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *argv, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=30)
+    except (TimeoutError, OSError):
+        return [], False
+
+    lines = stdout.decode("utf-8", errors="replace").splitlines()
+    truncated = len(lines) > limit
+    cleaned: list[str] = []
+    root_str = str(root.resolve())
+    for line in lines[:limit]:
+        if line.startswith(root_str):
+            line = line[len(root_str) :].lstrip("/\\")
+        cleaned.append(line)
+
+    return cleaned, truncated
+
+
+def _python_search(
+    root: Path, query: str, glob: str | None, *, regex: bool, limit: int
+) -> tuple[list[str], bool]:
+    pattern = re.compile(query, re.IGNORECASE) if regex else None
+    matches: list[str] = []
+    truncated = False
+    scanned = 0
+
+    for path in sorted(root.rglob("*")):
+        if scanned >= MAX_SCAN_FILES:
+            truncated = True
+            break
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            continue
+        if any(p in IGNORED_DIRS for p in rel.parts):
+            continue
+        if is_secret_file(path.name):
+            continue
+        if not path.is_file():
+            continue
+        if path.suffix.lower() in TEXT_SUFFIX_SKIP:
+            continue
+        if glob and not fnmatch.fnmatch(path.name, glob):
+            continue
+
+        scanned += 1
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        for idx, line in enumerate(content.splitlines(), start=1):
+            matched = bool(pattern.search(line)) if pattern else (query in line)
+            if matched:
+                matches.append(f"{rel.as_posix()}:{idx}: {line.strip()[:200]}")
+                if len(matches) >= limit:
+                    truncated = True
+                    return matches, truncated
+
+    return matches, truncated
+
+
+async def _search_code(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    query = call.arguments.get("query")
+    if not query:
+        return ToolResult(ok=False, error="missing required argument: query")
+
+    regex = bool(call.arguments.get("regex", False))
+    glob = call.arguments.get("glob")
+    limit = int(call.arguments.get("limit", MAX_MATCHES))
+
+    if _rg_available():
+        engine = "ripgrep"
+        matches, truncated = await _rg_search(ctx.workspace, str(query), glob, regex=regex, limit=limit)
+    else:
+        engine = "python"
+        matches, truncated = _python_search(ctx.workspace, str(query), glob, regex=regex, limit=limit)
+
+    redacted_matches = [redact_patterns(m) for m in matches]
+    output = "\n".join(redacted_matches) if redacted_matches else "(no matches)"
+
+    return ToolResult(
+        ok=True,
+        output=output,
+        data={"matches": len(matches), "truncated": truncated, "engine": engine},
+    )
+
+
+async def _search_files(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    pattern = call.arguments.get("pattern")
+    if not pattern:
+        return ToolResult(ok=False, error="missing required argument: pattern")
+
+    sub = str(call.arguments.get("path", ".") or ".")
+    try:
+        from forgex.utils.paths import resolve_in_workspace
+        target = resolve_in_workspace(ctx.workspace, sub)
+    except Exception as exc:
+        return ToolResult(ok=False, error=str(exc))
+
+    matches: list[str] = []
+    truncated = False
+
+    for path in sorted(target.rglob("*")):
+        try:
+            rel = path.relative_to(ctx.workspace)
+        except ValueError:
+            continue
+        if any(p in IGNORED_DIRS for p in rel.parts):
+            continue
+        if is_secret_file(path.name):
+            continue
+        if fnmatch.fnmatch(path.name, str(pattern)):
+            matches.append(rel.as_posix())
+            if len(matches) >= MAX_MATCHES:
+                truncated = True
+                break
+
+    output = "\n".join(matches) if matches else "(no files matched)"
+    return ToolResult(ok=True, output=output, data={"count": len(matches), "truncated": truncated})
+
+
+def create_tools() -> list[Tool]:
+    return [
+        SimpleTool(
+            name="search_code",
+            handler=_search_code,
+            permissions={Permission.READ},
+            description="Search for text or regex in workspace code files.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "String or regex pattern to search for"},
+                    "regex": {"type": "boolean", "description": "Whether query is a regex"},
+                    "glob": {"type": "string", "description": "Optional file glob filter, e.g. *.py"},
+                    "limit": {"type": "integer", "description": "Maximum match count"},
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+        ),
+        SimpleTool(
+            name="search_files",
+            handler=_search_files,
+            permissions={Permission.READ},
+            description="Find files in the workspace matching a name glob pattern.",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string", "description": "Filename pattern to match, e.g. *test*.py"},
+                    "path": {"type": "string", "description": "Subdirectory to search inside"},
+                },
+                "required": ["pattern"],
+                "additionalProperties": False,
+            },
+        ),
+    ]

forgex/tools/terminal.py

@@ -0,0 +1,81 @@
+"""run_command tool (spec section 19) — gated through policy → approval → executor."""
+
+from __future__ import annotations
+
+import shlex
+
+from forgex.sandbox.permissions import Permission
+from forgex.schemas.error import ToolError
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+
+
+async def _run_command(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    command = call.arguments.get("command")
+    if command is None:
+        raise ToolError("missing required argument: command")
+
+    cwd = str(call.arguments.get("cwd", ".") or ".")
+    timeout = call.arguments.get("timeout")
+    env = call.arguments.get("env")
+
+    result = await ctx.executor.run(
+        command,
+        cwd=cwd,
+        timeout=float(timeout) if timeout is not None else None,
+        env=env,
+    )
+
+    head = f"$ {shlex.join(result.argv)}"
+    status = "killed (timeout)" if result.timed_out else f"exit code {result.exit_code}"
+    sections = [
+        head,
+        status,
+        "--- stdout ---",
+        result.stdout or "(empty)",
+        "--- stderr ---",
+        result.stderr or "(empty)",
+    ]
+    return ToolResult(
+        ok=(result.exit_code == 0 and not result.timed_out),
+        output="\n".join(sections),
+        data={
+            "command": result.argv,
+            "exit_code": result.exit_code,
+            "timed_out": result.timed_out,
+            "duration_ms": round(result.duration_ms, 1),
+            "truncated": result.truncated,
+        },
+    )
+
+
+def create_tools() -> list[Tool]:
+    return [
+        SimpleTool(
+            name="run_command",
+            handler=_run_command,
+            permissions={Permission.TERMINAL},
+            description=(
+                "Run a command in the project workspace. Prefer an argv array "
+                "(['python', '-m', 'pytest']). Strings are parsed with shlex — NO shell "
+                "features (no pipes, &&, or redirects). The child environment is sanitized."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "description": "Argv array (preferred) or shlex-parsable string.",
+                        "oneOf": [{"type": "array", "items": {"type": "string"}}, {"type": "string"}],
+                    },
+                    "cwd": {"type": "string", "description": "Workspace-relative working directory"},
+                    "timeout": {"type": "integer", "description": "Timeout in seconds"},
+                    "env": {
+                        "type": "object",
+                        "additionalProperties": {"type": "string"},
+                        "description": "Extra environment variables (parent env is NOT inherited)",
+                    },
+                },
+                "required": ["command"],
+                "additionalProperties": False,
+            },
+        ),
+    ]

forgex/tools/testing.py

@@ -0,0 +1,100 @@
+"""run_tests tool + test-command detection (spec section 10)."""
+
+from __future__ import annotations
+
+import json
+import shlex
+from pathlib import Path
+
+from forgex.project import detect_project
+from forgex.sandbox.permissions import Permission
+from forgex.tools.base import SimpleTool, Tool, ToolCall, ToolContext, ToolResult
+
+
+def detect_test_command(root: Path) -> list[str] | None:
+    detection = detect_project(root)
+    langs = detection.languages
+    frameworks = detection.test_frameworks
+
+    if "Python" in langs:
+        if "Pytest" in frameworks:
+            return ["python", "-m", "pytest", "-q"]
+        if "unittest" in frameworks:
+            return ["python", "-m", "unittest", "discover", "-s", "."]
+        return None
+
+    if "JavaScript" in langs or "TypeScript" in langs:
+        pkg = root / "package.json"
+        if pkg.is_file():
+            try:
+                scripts = json.loads(pkg.read_text(encoding="utf-8")).get("scripts") or {}
+                if scripts.get("test"):
+                    return ["npm", "test"]
+            except (OSError, json.JSONDecodeError):
+                return None
+        return None
+
+    if "Rust" in langs:
+        return ["cargo", "test"]
+
+    if "Go" in langs:
+        return ["go", "test", "./..."]
+
+    return None
+
+
+async def _run_tests(call: ToolCall, ctx: ToolContext) -> ToolResult:
+    command = detect_test_command(ctx.workspace)
+    if command is None:
+        return ToolResult(
+            ok=False,
+            error="No test command detected for this project (expected pytest / npm test / cargo test / go test).",
+        )
+
+    extra = call.arguments.get("extra_args") or []
+    full_cmd = list(command) + [str(a) for a in extra]
+
+    result = await ctx.executor.run(full_cmd, cwd=".")
+    status = "killed (timeout)" if result.timed_out else f"exit code {result.exit_code}"
+    output = "\n".join(
+        [
+            f"$ {shlex.join(result.argv)}",
+            status,
+            "--- stdout ---",
+            result.stdout or "(empty)",
+            "--- stderr ---",
+            result.stderr or "(empty)",
+        ]
+    )
+    return ToolResult(
+        ok=(result.exit_code == 0 and not result.timed_out),
+        output=output,
+        data={
+            "command": result.argv,
+            "exit_code": result.exit_code,
+            "timed_out": result.timed_out,
+            "duration_ms": round(result.duration_ms, 1),
+        },
+    )
+
+
+def create_tools() -> list[Tool]:
+    return [
+        SimpleTool(
+            name="run_tests",
+            handler=_run_tests,
+            permissions={Permission.TEST},
+            description="Run the project's test suite (auto-detected: pytest, npm test, cargo test, go test).",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "extra_args": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Extra arguments appended to the test command",
+                    }
+                },
+                "additionalProperties": False,
+            },
+        ),
+    ]