ferrum-cli 0.1.1__tar.gz → 0.1.2__tar.gz

{ferrum_cli-0.1.1/ferrum_cli.egg-info → ferrum_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-cli
-Version: 0.1.1
+Version: 0.1.2
 Summary: A lightweight coding harness for low-level and systems programming: inspect, understand, patch, verify.
 Author: Ferrum contributors
 License-Expression: Apache-2.0

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/__init__.py

@@ -3,4 +3,4 @@
 Understand -> Change -> Build -> Verify.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/agent.py

@@ -13,7 +13,7 @@ from ferrum.apply_patch import ApplyPatch
 from ferrum.config import Config
 from ferrum.context import ProjectContext
 from ferrum.model import ModelProvider, ModelResponse
-from ferrum.toolcalls import MALFORMED_JSON, extract_tool_calls
+from ferrum.toolcalls import MALFORMED_JSON, ToolCall, extract_tool_calls
 from ferrum.tools import ToolRegistry, ToolResult
 from ferrum.ui import Console
 from ferrum.verifier import Verifier
@@ -33,13 +33,15 @@ READ_ONLY_NOTE = (
     "Read-only mode: investigate thoroughly before answering. A directory "
     "listing alone is not an answer — read the relevant source files and "
     "search for the relevant names; several tool calls are expected. You "
-    "cannot modify files, so do not call apply_patch."
+    "cannot modify files, so do not call apply_patch; run_command is "
+    "available for builds, tests, and running the program."
 )
 
 FIX_NOTE = (
     "Fix mode: inspect thoroughly before patching — read the file you are "
     "about to change and its callers; several tool calls are expected. "
-    "Call apply_patch only with text you have read in this session."
+    "Reproduce the failure with run_command first when a build or test can "
+    "show it. Call apply_patch only with text you have read in this session."
 )
 
 DRY_RUN_NOTE = (
@@ -66,6 +68,7 @@ PROGRESS = {
     "list_files": "inspecting the project",
     "read_file": "reading",
     "search_code": "searching",
+    "run_command": "running",
     "apply_patch": "proposing a patch to",
 }
 
@@ -147,7 +150,9 @@ class Agent:
             edit=edit,
         )
 
-    def _run_tools(self, response, state: _TurnState) -> list[dict[str, Any]]:
+    def _run_tools(
+        self, response: ModelResponse, state: _TurnState
+    ) -> list[dict[str, Any]]:
         """Run every requested tool, one tool message per call."""
         state.used_tools = True
         messages: list[dict[str, Any]] = []
@@ -205,7 +210,7 @@ class Agent:
         with self.ui.live(f"asking {model}"):
             return self.provider.complete(messages, tools)
 
-    def _execute(self, call) -> ToolResult:
+    def _execute(self, call: ToolCall) -> ToolResult:
         if MALFORMED_JSON in call.arguments:
             raw = str(call.arguments[MALFORMED_JSON])[:500]
             return ToolResult.failure(
@@ -217,12 +222,14 @@ class Agent:
             return ToolResult.failure("tool call had no name")
         return self.registry.execute(call.name, call.arguments)
 
-    def _progress(self, call) -> None:
+    def _progress(self, call: ToolCall) -> None:
         label = PROGRESS.get(call.name, call.name)
         if call.name in ("read_file", "apply_patch"):
             detail = f" {call.arguments.get('path', '')}"
         elif call.name == "search_code":
             detail = f" {call.arguments.get('pattern', '')!r}"
+        elif call.name == "run_command":
+            detail = f" {str(call.arguments.get('command', ''))[:60]}"
         else:
             detail = ""
         text = f"{label}{detail}"
@@ -231,7 +238,9 @@ class Agent:
         elif self.printer is not None:
             self.printer(f"Ferrum > {text}...")
 
-    def _finish(self, text: str, turns: int, *, capped: bool, edit: bool) -> AgentResult:
+    def _finish(
+        self, text: str, turns: int, *, capped: bool, edit: bool
+    ) -> AgentResult:
         if not text:
             text = "The model returned no answer."
         patched = bool(self.apply_tool and self.apply_tool.applied)
@@ -277,7 +286,9 @@ def _nudge_for(response: ModelResponse, state: _TurnState) -> str | None:
     return None
 
 
-def _merge_tool_calls(native: list, extracted: list) -> list:
+def _merge_tool_calls(
+    native: list[ToolCall], extracted: list[ToolCall]
+) -> list[ToolCall]:
     """Native calls first, then JSON-from-text calls that are not duplicates."""
     seen = {(c.name, json.dumps(c.arguments, sort_keys=True)) for c in native}
     merged = list(native)

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/apply_patch.py

@@ -16,7 +16,7 @@ from ferrum.patch import Patch, format_unified_diff
 from ferrum.safety import PathEscapeError, is_denied, safe_join
 from ferrum.tools import Tool, ToolError, ToolResult, _require_string
 from ferrum.ui import Console
-from ferrum.verifier import Verifier, VerifyOutcome
+from ferrum.verifier import Verifier, VerifyOutcome, run_command
 
 DRY_RUN_RESULT = (
     "Dry run: the patch was NOT applied to {rel}"
@@ -25,10 +25,11 @@ DRY_RUN_RESULT = (
 )
 
 DECLINED_RESULT = (
-    "The user declined this patch. Do not apply it. "
-    "Ask what they would prefer or stop."
+    "The user declined this patch. Do not apply it. Ask what they would prefer or stop."
 )
 
+GIT_TIMEOUT = 15
+
 
 class ApplyPatch(Tool):
     name = "apply_patch"
@@ -36,7 +37,9 @@ class ApplyPatch(Tool):
         "Replace exact text in a project file after showing the diff and "
         "asking the user. The old text must match the file verbatim and "
         "uniquely. After a successful patch the project is built and "
-        "tested; the verification output comes back in the result."
+        "tested; in a git work tree the result also carries git's status "
+        "and diff for the file, and the verification output comes back "
+        "afterwards."
     )
     parameters: ClassVar[dict[str, Any]] = {
         "type": "object",
@@ -102,6 +105,9 @@ class ApplyPatch(Tool):
         report = f"Patch applied to {rel}."
         if description:
             report += f" ({description})"
+        git_section = _git_report(self.root, rel)
+        if git_section:
+            report += "\n\n--- git ---\n" + git_section
         if self.verifier is None:
             return report + "\n(verification unavailable)"
         live = (
@@ -166,3 +172,26 @@ def _write(target: Path, updated: str, crlf: bool, rel: str) -> None:
         target.write_bytes(out.encode("utf-8"))
     except OSError as exc:
         raise ToolError(f"cannot write {rel}: {exc}") from exc
+
+
+def _git_report(root: Path, rel: str) -> str | None:
+    """What git sees for this file after the write.
+
+    Returns None when git is missing or root is not a work tree, so projects
+    outside version control never pay for the extra sections.
+    """
+    probe = run_command(
+        ["git", "rev-parse", "--is-inside-work-tree"], root, timeout=GIT_TIMEOUT
+    )
+    if not probe.ok or probe.stdout.strip() != "true":
+        return None
+    status = run_command(
+        ["git", "status", "--porcelain", "--", rel], root, timeout=GIT_TIMEOUT
+    )
+    lines = [status.stdout.strip() or "(no changes against the index)"]
+    diff = run_command(
+        ["git", "diff", "--no-color", "--", rel], root, timeout=GIT_TIMEOUT
+    )
+    if diff.stdout.strip():
+        lines.append(diff.stdout.strip())
+    return "\n".join(lines)

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/builtin_tools.py

@@ -1,8 +1,10 @@
-"""The read-only tools the model calls: list, read, search."""
+"""The tools the model calls: list, read, search, and run one command."""
 
 from __future__ import annotations
 
+import os
 import re
+import shlex
 from collections.abc import Mapping
 from pathlib import Path, PurePosixPath
 from typing import Any, ClassVar
@@ -11,9 +13,14 @@ from ferrum.config import Config
 from ferrum.context import collect_files, limit_entries
 from ferrum.safety import PathEscapeError, is_denied, safe_join
 from ferrum.tools import Tool, ToolError, ToolRegistry, ToolResult, _require_string
+from ferrum.verifier import run_command
 
 MAX_LINE_CHARS = 300
 
+# Shell plumbing is refused: commands run as one program with its arguments,
+# so a model cannot chain, pipe, or redirect its way past the project root.
+SHELL_CHARS = frozenset(";|&<>`\n")
+
 
 class ListFiles(Tool):
     name = "list_files"
@@ -167,9 +174,7 @@ class SearchCode(Tool):
             raise ToolError(f"invalid regular expression: {exc}") from exc
         return pattern, start, rx
 
-    def _search(
-        self, rx: re.Pattern[str], start: Path
-    ) -> tuple[list[str], bool]:
+    def _search(self, rx: re.Pattern[str], start: Path) -> tuple[list[str], bool]:
         """path:line snippets, stopping once the result cap is reached."""
         matches: list[str] = []
         truncated = False
@@ -194,10 +199,128 @@ class SearchCode(Tool):
         return matches, truncated
 
 
+class RunCommand(Tool):
+    name = "run_command"
+    description = (
+        "Run one build, test, or analysis command in the project and return "
+        "its output and exit code. One command per call; shell features "
+        "(pipes, redirection, chaining) are not supported. Use it to "
+        "reproduce a failure, read real compiler diagnostics, or run the "
+        "program before and after a patch."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": (
+                    "The command line to run, e.g. `make test` or "
+                    "`clang -Wall -o main main.c`."
+                ),
+            },
+            "cwd": {
+                "type": "string",
+                "description": (
+                    "Optional subdirectory to run in, relative to the project root."
+                ),
+            },
+            "timeout": {
+                "type": "integer",
+                "description": (
+                    "Seconds to wait before killing the command "
+                    "(capped at the configured command timeout)."
+                ),
+            },
+        },
+        "required": ["command"],
+    }
+
+    def __init__(self, root: Path, config: Config | None = None) -> None:
+        self.root = Path(root)
+        self.config = config or Config()
+
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        argv = _split_command(_require_string(arguments, "command"))
+        cwd = self._cwd(arguments)
+        timeout = self._timeout(arguments)
+        return ToolResult.success(run_command(argv, cwd, timeout=timeout).render())
+
+    def _cwd(self, arguments: Mapping[str, Any]) -> Path:
+        sub = arguments.get("cwd") or ""
+        if not isinstance(sub, str):
+            raise ToolError("cwd must be a string")
+        if not sub:
+            return self.root
+        if is_denied(PurePosixPath(sub.replace("\\", "/"))):
+            raise ToolError(f"refused: {sub} is excluded")
+        try:
+            start = safe_join(self.root, sub)
+        except PathEscapeError as exc:
+            raise ToolError(str(exc)) from exc
+        if not start.is_dir():
+            raise ToolError(f"not a directory: {sub}")
+        return start
+
+    def _timeout(self, arguments: Mapping[str, Any]) -> int:
+        limit = self.config.command_timeout
+        raw = arguments.get("timeout")
+        if raw is None:
+            return limit
+        if isinstance(raw, bool) or not isinstance(raw, int) or raw <= 0:
+            raise ToolError(f"timeout must be a positive integer, got {raw!r}")
+        return min(raw, limit)
+
+
+def _split_command(command: str) -> list[str]:
+    """One command line -> argv, refusing shell plumbing outside quotes."""
+    outside = _unquoted(command)
+    if (SHELL_CHARS & set(outside)) or "$(" in outside:
+        raise ToolError(
+            "shell features are not supported (pipes, redirection, chaining); "
+            "run a single command with its arguments"
+        )
+    try:
+        argv = shlex.split(command, posix=os.name != "nt")
+    except ValueError as exc:
+        raise ToolError(f"cannot parse command: {exc}") from exc
+    if os.name == "nt":
+        # posix=False keeps the quotes in the token; drop the matched pair.
+        argv = [
+            token[1:-1]
+            if len(token) > 1 and token[0] == token[-1] and token[0] in "\"'"
+            else token
+            for token in argv
+        ]
+    if not argv:
+        raise ToolError("command is empty")
+    return argv
+
+
+def _unquoted(command: str) -> str:
+    """The command with quoted spans removed, so payload text is not scanned."""
+    out: list[str] = []
+    quote: str | None = None
+    for char in command:
+        if quote is not None:
+            if char == quote:
+                quote = None
+            continue
+        if char in "\"'":
+            quote = char
+            continue
+        out.append(char)
+    return "".join(out)
+
+
 def default_tools(root: Path, config: Config | None = None) -> ToolRegistry:
-    """The standard read-only set."""
+    """The standard set: three readers plus one runner."""
     config = config or Config()
     registry = ToolRegistry()
-    for tool in (ListFiles(root, config), ReadFile(root, config), SearchCode(root, config)):
+    for tool in (
+        ListFiles(root, config),
+        ReadFile(root, config),
+        SearchCode(root, config),
+        RunCommand(root, config),
+    ):
         registry.register(tool)
     return registry

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/cli.py

@@ -134,7 +134,7 @@ def _dispatch(args: argparse.Namespace, console: Console) -> int:
 
     if args.dry_run:
         print(
-            "error: --dry-run only applies to: ferrum fix --dry-run \"<task>\"",
+            'error: --dry-run only applies to: ferrum fix --dry-run "<task>"',
             file=sys.stderr,
         )
         return EXIT_ERROR
@@ -171,11 +171,13 @@ def _force_utf8_streams() -> None:
     # piped. Line buffering keeps stdout and stderr in the order they were
     # written, so `ferrum ... | tee log` still reads top to bottom.
     for stream in (sys.stdout, sys.stderr):
+        # reconfigure only exists on TextIOWrapper, not on a redirected pipe.
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
         try:
-            stream.reconfigure(
-                encoding="utf-8", errors="replace", line_buffering=True
-            )
-        except (AttributeError, ValueError, OSError):
+            reconfigure(encoding="utf-8", errors="replace", line_buffering=True)
+        except (ValueError, OSError):
             pass
 
 

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/commands/config.py

@@ -13,6 +13,7 @@ from ferrum.config import (
     LOCAL_PRESET_URL,
     PROFILES,
     STR_FIELDS,
+    Config,
     ConfigError,
     config_file_path,
     load_config,
@@ -89,7 +90,13 @@ def show() -> int:
     return EXIT_OK
 
 
-def _displayed(config, stored, name, key, active) -> tuple[str, str]:
+def _displayed(
+    config: Config,
+    stored: dict[str, dict[str, str]],
+    name: str,
+    key: str,
+    active: str,
+) -> tuple[str, str]:
     """Value and source for one row: the active profile resolves, others show."""
     if name == active:
         value = getattr(config, key)
@@ -105,8 +112,7 @@ def get(key: str) -> int:
     known = {**STR_FIELDS, **INT_FIELDS}
     if key not in known:
         print(
-            f"error: unknown setting {key!r}; choose from: "
-            + ", ".join(sorted(known)),
+            f"error: unknown setting {key!r}; choose from: " + ", ".join(sorted(known)),
             file=sys.stderr,
         )
         return EXIT_ERROR
@@ -187,10 +193,11 @@ def preset(kind: str, rest: list[str]) -> int:
         print(note, file=sys.stderr)
     if kind == "cloud":
         _warn_if_cloud_key_missing()
-    print("next: ferrum config setup    (api key and model, guided)",
-          file=sys.stderr)
-    print("  or: ferrum config models   then  ferrum config set model <name>",
-          file=sys.stderr)
+    print("next: ferrum config setup    (api key and model, guided)", file=sys.stderr)
+    print(
+        "  or: ferrum config models   then  ferrum config set model <name>",
+        file=sys.stderr,
+    )
     return EXIT_OK
 
 
@@ -211,7 +218,7 @@ def _warn_if_cloud_key_missing() -> None:
 # -- shared helpers -------------------------------------------------------
 
 
-def _load():
+def _load() -> Config | None:
     """The active profile's settings, or None after reporting the problem."""
     try:
         return load_config()
@@ -225,5 +232,3 @@ def _env_override_note(key: str) -> str | None:
     if var and os.environ.get(var):
         return f"note: {var} is set in the environment and overrides the file"
     return None
-
-

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/commands/doctor.py

@@ -80,14 +80,17 @@ def _probe_endpoint(config: Config, console: Console) -> tuple[list[str], list[s
 
 def _toolchain_report() -> list[str]:
     """Print the build tools found; note what fix mode cannot verify."""
-    found = [tool for tool in ("clang", "gcc", "make", "cargo", "cmake")
-             if shutil.which(tool)]
+    found = [
+        tool
+        for tool in ("clang", "gcc", "make", "cargo", "cmake")
+        if shutil.which(tool)
+    ]
     print(f"{'toolchain':<12}{', '.join(found) if found else 'nothing found'}")
     warnings: list[str] = []
     if not {"clang", "gcc"} & set(found):
         warnings.append("no C compiler — fix mode cannot verify C builds")
     if not found:
-        warnings.append("nothing to verify builds with; run commands are unavailable")
+        warnings.append("no build tool found — fix mode cannot verify a fix")
     return warnings
 
 

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/commands/setup.py

@@ -36,7 +36,7 @@ def run(console: Console, profile: str | None = None) -> int:
         _print_needs_terminal()
         return EXIT_ERROR
     profile, current = _setup_target(profile)
-    if current is None:
+    if profile is None or current is None:
         return EXIT_ERROR
 
     print(f"Ferrum setup — {profile} profile, Enter keeps [brackets].")

{ferrum_cli-0.1.1 → ferrum_cli-0.1.2}/ferrum/commands/task.py

@@ -36,9 +36,7 @@ def inspect_target(target: str, console: Console) -> int:
     return EXIT_OK
 
 
-def run_task(
-    task: str, *, edit: bool, dry_run: bool = False, console: Console
-) -> int:
+def run_task(task: str, *, edit: bool, dry_run: bool = False, console: Console) -> int:
     """`ferrum "<task>"` or `ferrum fix "<task>"`: one conversation."""
     config = _load_config()
     if config is None:
@@ -84,9 +82,7 @@ def _describe_project(root: Path, config: Config, console: Console) -> ProjectCo
     host = host_of(config.base_url)
     console.step(f"model: {config.model} at {host} [{config.profile}]")
     if not config.api_key and not config.local:
-        console.step(
-            f"no api_key set for {host} — the endpoint may refuse the request"
-        )
+        console.step(f"no api_key set for {host} — the endpoint may refuse the request")
     return context
 
 
@@ -141,10 +137,10 @@ def _report_missing(config: Config, missing: list[str]) -> int:
     """Nothing to ask the model with — say so in commands the user can type."""
     print(f"error: {', '.join(missing)} is not set.", file=sys.stderr)
     print(file=sys.stderr)
-    print(f"  ferrum config setup {config.profile:<25} base_url, api_key, and model",
-          file=sys.stderr)
-    print("  ferrum config models        list models at the current endpoint",
-          file=sys.stderr)
+    print(f"  ferrum config setup {config.profile}", file=sys.stderr)
+    print("      interactive wizard: base_url, api_key, and model", file=sys.stderr)
+    print("  ferrum config models", file=sys.stderr)
+    print("      list models at the current endpoint", file=sys.stderr)
     print("  ferrum config set model <name>", file=sys.stderr)
     print(f"  (or export {', '.join(missing)}=... for this shell)", file=sys.stderr)
     _print_available_models(config)
@@ -169,11 +165,14 @@ def _provider_hint(exc: ProviderError) -> None:
     """Turn the raw endpoint failure into the one command that fixes it."""
     if isinstance(exc, AuthenticationError):
         print("  the endpoint rejected the api key:", file=sys.stderr)
-        print("    ferrum config set api_key <key>   (or: ferrum config setup)",
-              file=sys.stderr)
+        print(
+            "    ferrum config set api_key <key>   (or: ferrum config setup)",
+            file=sys.stderr,
+        )
     elif isinstance(exc, RateLimitError):
-        print("  the endpoint is rate limiting — wait a moment and retry",
-              file=sys.stderr)
+        print(
+            "  the endpoint is rate limiting — wait a moment and retry", file=sys.stderr
+        )
 
 
 def confirm(prompt: str, console: Console | None = None) -> bool: