ferrum-cli 0.1.0__py3-none-any.whl

ferrum/patch.py

@@ -0,0 +1,65 @@
+"""Exact-text patches against a single file, with stale-source detection.
+
+The model must copy the old source verbatim; we verify it still matches
+the file before anything is written.
+"""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+
+
+class PatchError(Exception):
+    pass
+
+
+class StaleSourceError(PatchError):
+    pass
+
+
+class AmbiguousPatchError(PatchError):
+    pass
+
+
+@dataclass(frozen=True)
+class Patch:
+    rel: str  # project-relative, for display
+    old: str
+    new: str
+    description: str = ""
+
+    def occurrences(self, current: str) -> int:
+        return current.count(self.old)
+
+    def verify(self, current: str) -> None:
+        count = self.occurrences(current)
+        if count == 0:
+            raise StaleSourceError(
+                f"old text not found in {self.rel}: the source changed "
+                "since analysis, or the old text was not copied verbatim"
+            )
+        if count > 1:
+            raise AmbiguousPatchError(
+                f"old text matches {count} times in {self.rel}; "
+                "include more surrounding context"
+            )
+
+    def apply(self, current: str) -> str:
+        self.verify(current)
+        return current.replace(self.old, self.new, 1)
+
+
+def format_unified_diff(original: str, updated: str, rel: str) -> str:
+    lines = difflib.unified_diff(
+        original.splitlines(keepends=True),
+        updated.splitlines(keepends=True),
+        fromfile=f"a/{rel}",
+        tofile=f"b/{rel}",
+    )
+    text = "".join(lines)
+    if not text:
+        return f"(no text change in {rel})"
+    if not text.endswith("\n"):
+        text += "\n"
+    return text

ferrum/prompts/system.md

@@ -0,0 +1,89 @@
+# Ferrum system prompt
+
+You are **Ferrum**, a coding harness for low-level and systems programming.
+You work inside a real repository on behalf of a developer who asked for a
+specific, bounded task.
+
+**You cannot answer from memory.** Before any conclusion, call the tools:
+`list_files` to see the project, `read_file` to read the relevant source,
+`search_code` to find references. Every claim must come from files you
+actually read in this session, cited as `path:line`. Inventing functions,
+line numbers, or behavior is the worst possible answer.
+
+Your job is to inspect, understand, make the smallest change that fixes the
+problem, and prove the change works.
+
+## Non-negotiable rules
+
+1. **Inspect before you modify.** Never edit code you have not read. Read the
+   surrounding code, not just the line you think is wrong.
+2. **Evidence over guessing.** Cite file paths and line numbers
+   (`main.c:42`). If you have not read a file, do not describe its contents.
+3. **Minimal changes.** Prefer the smallest diff that fixes the reported
+   problem. Do not reformat, rename, refactor, or "improve" unrelated code.
+4. **Respect the existing architecture.** Match the project's style,
+   idioms, naming, error-handling conventions, and build setup. If the code
+   base uses goto-based cleanup, keep using it. Do not introduce new
+   dependencies.
+5. **Never claim a fix is verified unless it was actually verified.** Only a
+   build or test that really ran and passed makes a fix "verified". Saying
+   "fixed" after merely applying a patch is forbidden.
+
+## Think like a systems programmer
+
+- **Memory:** every pointer has an owner and a lifetime. Ask: who allocates,
+  who frees, who may hold a dangling reference? Check for use-after-free,
+  double free, buffer overruns, off-by-one indexing, integer overflow and
+  truncation, uninitialized reads, and stack lifetimes that outlive their
+  frame.
+- **Undefined behavior:** signed overflow, strict aliasing violations,
+  shift counts >= width, unaligned access, data races, reading beyond a
+  NUL terminator, violating the strict-aliasing rule with type punning.
+- **Ownership and lifetimes (Rust/C++):** who owns the value, what does
+  `&mut` exclude, where does a borrow or reference escape its scope, does a
+  move leave a usable object behind?
+- **ABI/API compatibility:** struct layout and packing, calling conventions,
+  enum sizes, exported symbol visibility, header include order, `extern "C"`
+  linkage, versioned interfaces, and callers you cannot see.
+- **Compiler diagnostics are free evidence.** Read warnings and errors
+  closely; they often point directly at the bug. Mention diagnostics you saw
+  and what they imply.
+
+## Workflow
+
+**Inspect → Understand → Patch → Verify.**
+
+1. **Inspect.** Use the read-only tools (`list_files`, `read_file`,
+   `search_code`) to find the relevant code. Look for the build system and
+   the tests so you know how the change will be checked later.
+2. **Understand.** State the likely cause as a hypothesis backed by the code
+   you actually read. Explain the failure mechanism, not just the symptom.
+3. **Patch.** Produce one minimal `apply_patch` with the exact old source and
+   the exact new source. The old source must be copied verbatim from the
+   file, including indentation, so the patch can be verified against the
+   file. One concern per patch.
+4. **Verify.** After the patch is applied, the harness builds and tests the
+   project. Feed on compiler and test output: if verification fails,
+   diagnose from that output and iterate with another minimal patch. If you
+   cannot make it pass, say so plainly.
+
+If your backend does not send native tool calls, invoke a tool by writing
+exactly one JSON object in your reply: `{"name": "<tool>", "arguments": {...}}`.
+
+## Honesty and reporting
+
+- Distinguish clearly between *observed* (you read it), *inferred* (you
+  reasoned about it), and *verified* (a command actually ran and passed).
+- If the evidence is ambiguous, say what else you would check.
+- If you are not sure a patch fixes the root cause, say exactly that.
+- Never invent tool output, file contents, line numbers, or test results.
+
+## Tone
+
+Be terse and concrete. Prefer:
+
+> Found a NULL dereference at main.c:42: `ptr` is used after `read_input()`
+> returned NULL on EOF. The likely cause is a missing error check.
+
+over prose about how programming works. The developer reading you already
+knows how to program; they want the diagnosis and the fix.

ferrum/safety.py

@@ -0,0 +1,124 @@
+"""Guards for poking around in someone else's repository.
+
+Every path is resolved against the project root and checked against a deny
+list: no .. escapes, no .env files, no binaries.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+# Directories that never hold anything we want to show the model.
+DENIED_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".venv",
+        "venv",
+        ".tox",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".idea",
+        ".vscode",
+        "node_modules",
+        "target",
+        "build",
+        "dist",
+    }
+)
+
+# Generated binaries and other junk that isn't source.
+DENIED_SUFFIXES = (
+    ".pyc",
+    ".pyo",
+    ".o",
+    ".obj",
+    ".so",
+    ".dll",
+    ".dylib",
+    ".a",
+    ".lib",
+    ".exe",
+    ".pdb",
+    ".class",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".pdf",
+    ".zip",
+    ".gz",
+    ".tar",
+    ".7z",
+    ".woff",
+    ".woff2",
+    ".ttf",
+)
+
+# Might contain secrets. Never hand these to a model.
+SENSITIVE_PATTERNS = (
+    ".env",
+    ".env.*",
+    "*.pem",
+    "*.key",
+    "*.pfx",
+    "*.p12",
+    "id_rsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    "*.keystore",
+)
+
+
+class SafetyError(Exception):
+    pass
+
+
+class PathEscapeError(SafetyError):
+    pass
+
+
+def is_within(root: Path, path: Path) -> bool:
+    """True if path resolves to somewhere inside root."""
+    try:
+        root = root.resolve()
+        path = path.resolve()
+    except OSError:
+        return False
+    return path == root or root in path.parents
+
+
+def safe_join(root: Path, *parts: str) -> Path:
+    """Join parts onto root, refusing anything that lands outside it."""
+    root = root.resolve()
+    target = root
+    for part in parts:
+        piece = str(part)
+        if not piece:
+            continue
+        p = Path(piece)
+        if p.is_absolute() or p.drive or p.root:
+            raise PathEscapeError(f"absolute path is not allowed here: {piece!r}")
+        target = target / p
+    target = target.resolve()
+    if target != root and root not in target.parents:
+        raise PathEscapeError(
+            f"path escapes project root: {'/'.join(parts)!r} -> {target}"
+        )
+    return target
+
+
+def is_denied(rel_path: str | PurePosixPath) -> bool:
+    """True if this root-relative path should never reach the model."""
+    rel = PurePosixPath(str(rel_path).replace("\\", "/"))
+    if any(part in DENIED_DIRS for part in rel.parts):
+        return True
+    if any(rel.match(p) or PurePosixPath(rel.as_posix().lower()).match(p)
+           for p in SENSITIVE_PATTERNS):
+        return True
+    name = rel.name.lower()
+    return any(name.endswith(suffix) for suffix in DENIED_SUFFIXES)

ferrum/tools.py

@@ -0,0 +1,296 @@
+"""The tools the model can call. Everything here only reads."""
+
+from __future__ import annotations
+
+import logging
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, ClassVar
+
+from ferrum.config import Config
+from ferrum.context import collect_files, limit_entries
+from ferrum.safety import PathEscapeError, is_denied, safe_join
+
+log = logging.getLogger(__name__)
+
+MAX_LINE_CHARS = 300
+
+
+class ToolError(Exception):
+    """A normal, reportable failure: bad path, denied file, that sort of thing."""
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    ok: bool
+    text: str
+
+    @classmethod
+    def success(cls, text: str) -> ToolResult:
+        return cls(ok=True, text=text)
+
+    @classmethod
+    def failure(cls, text: str) -> ToolResult:
+        return cls(ok=False, text=text)
+
+    def to_model_message(self) -> str:
+        return self.text if self.ok else f"ERROR: {self.text}"
+
+
+class Tool(ABC):
+    name: ClassVar[str] = ""
+    description: ClassVar[str] = ""
+    parameters: ClassVar[dict[str, Any]] = {"type": "object", "properties": {}}
+
+    @abstractmethod
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        """Do the thing. Expected failures should raise ToolError."""
+
+    def schema(self) -> dict[str, Any]:
+        """OpenAI-style function schema, which is what most APIs expect."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+class ToolRegistry:
+    """Looks tools up by name and turns their mistakes into error results."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if not tool.name:
+            raise ValueError("tool must define a non-empty name")
+        if tool.name in self._tools:
+            raise ValueError(f"tool already registered: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [tool.schema() for tool in self._tools.values()]
+
+    def execute(self, name: str, arguments: Mapping[str, Any]) -> ToolResult:
+        tool = self._tools.get(name)
+        if tool is None:
+            return ToolResult.failure(
+                f"unknown tool {name!r}; available tools: "
+                + (", ".join(sorted(self._tools)) or "(none)")
+            )
+        if not isinstance(arguments, Mapping):
+            return ToolResult.failure(
+                f"tool {name!r} expects an object of arguments, "
+                f"got {type(arguments).__name__}"
+            )
+        try:
+            return tool.execute(arguments)
+        except ToolError as exc:
+            log.info("tool %s reported: %s", name, exc)
+            return ToolResult.failure(str(exc))
+        except Exception as exc:
+            log.exception("tool %s crashed", name)
+            return ToolResult.failure(f"internal tool error: {exc}")
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._tools
+
+
+def _require_string(arguments: Mapping[str, Any], key: str) -> str:
+    value = arguments.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ToolError(f"{key} is required and must be a non-empty string")
+    return value
+
+
+class ListFiles(Tool):
+    name = "list_files"
+    description = (
+        "List source and build files in the project, respecting .gitignore "
+        "and size limits. Returns one relative path per line."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Optional subdirectory relative to the project root.",
+            }
+        },
+    }
+
+    def __init__(self, root: Path, config: Config | None = None) -> None:
+        self.root = root
+        self.config = config or Config()
+
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        sub = arguments.get("path") or ""
+        if not isinstance(sub, str):
+            raise ToolError("path must be a string")
+        try:
+            start = safe_join(self.root, sub) if sub else self.root
+        except PathEscapeError as exc:
+            raise ToolError(str(exc)) from exc
+        if not start.is_dir():
+            raise ToolError(f"not a directory: {sub}")
+        entries = limit_entries(
+            collect_files(self.root, self.config, start=start), self.config
+        )
+        if not entries:
+            return ToolResult.success("(no files matched)")
+        paths = [entry.path for entry in entries]
+        return ToolResult.success("\n".join(paths) + f"\n\n{len(paths)} file(s)")
+
+
+class ReadFile(Tool):
+    name = "read_file"
+    description = (
+        "Read a single project file as UTF-8 text. Paths are relative to the "
+        "project root; secrets, binaries and oversized files are refused. "
+        "Line endings are normalized to \\n."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "File path relative to the project root.",
+            }
+        },
+        "required": ["path"],
+    }
+
+    def __init__(self, root: Path, config: Config | None = None) -> None:
+        self.root = root
+        self.config = config or Config()
+
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        rel = _require_string(arguments, "path")
+        if is_denied(PurePosixPath(rel.replace("\\", "/"))):
+            raise ToolError(f"refused: {rel} is excluded (secret, binary, or ignored)")
+        try:
+            target = safe_join(self.root, rel)
+        except PathEscapeError as exc:
+            raise ToolError(str(exc)) from exc
+        if target.is_dir():
+            raise ToolError(f"is a directory: {rel} (use list_files)")
+        if not target.exists():
+            raise ToolError(f"file not found: {rel}")
+        try:
+            size = target.stat().st_size
+            if size > self.config.max_file_bytes:
+                raise ToolError(
+                    f"file too large: {rel} ({size} bytes > limit "
+                    f"{self.config.max_file_bytes})"
+                )
+            data = target.read_bytes()
+        except OSError as exc:
+            raise ToolError(f"cannot read {rel}: {exc}") from exc
+        if b"\x00" in data[:8192]:
+            raise ToolError(f"refused: {rel} looks like a binary file")
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ToolError(f"not valid UTF-8 text: {rel}") from exc
+        return ToolResult.success(text.replace("\r\n", "\n").replace("\r", "\n"))
+
+
+class SearchCode(Tool):
+    name = "search_code"
+    description = (
+        "Search project source files for a string or regular expression. "
+        "Returns matches as path:line: content. Case-sensitive by default."
+    )
+    parameters: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "Text or regular expression to search for.",
+            },
+            "path": {
+                "type": "string",
+                "description": "Optional subdirectory to restrict the search.",
+            },
+            "regex": {
+                "type": "boolean",
+                "description": "Treat pattern as a regular expression (default false).",
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    def __init__(self, root: Path, config: Config | None = None) -> None:
+        self.root = root
+        self.config = config or Config()
+
+    def execute(self, arguments: Mapping[str, Any]) -> ToolResult:
+        pattern = _require_string(arguments, "pattern")
+        sub = arguments.get("path") or ""
+        if not isinstance(sub, str):
+            raise ToolError("path must be a string")
+        regex_mode = arguments.get("regex", False)
+        if not isinstance(regex_mode, bool):
+            raise ToolError("regex must be a boolean")
+        try:
+            start = safe_join(self.root, sub) if sub else self.root
+        except PathEscapeError as exc:
+            raise ToolError(str(exc)) from exc
+        if not start.is_dir():
+            raise ToolError(f"not a directory: {sub}")
+        try:
+            rx = re.compile(pattern if regex_mode else re.escape(pattern))
+        except re.error as exc:
+            raise ToolError(f"invalid regular expression: {exc}") from exc
+
+        matches: list[str] = []
+        truncated = False
+        for entry in collect_files(self.root, self.config, start=start):
+            try:
+                content = (self.root / entry.path).read_text(
+                    encoding="utf-8", errors="replace"
+                )
+            except OSError:
+                continue
+            for lineno, line in enumerate(content.splitlines(), start=1):
+                if rx.search(line):
+                    snippet = line.strip()
+                    if len(snippet) > MAX_LINE_CHARS:
+                        snippet = snippet[: MAX_LINE_CHARS - 3] + "..."
+                    matches.append(f"{entry.path}:{lineno}: {snippet}")
+                    if len(matches) >= self.config.max_search_results:
+                        truncated = True
+                        break
+            if truncated:
+                break
+
+        if not matches:
+            return ToolResult.success(f"no matches for {pattern!r}")
+        text = "\n".join(matches)
+        if truncated:
+            text += f"\n... truncated at {self.config.max_search_results} results"
+        return ToolResult.success(text)
+
+
+def default_tools(root: Path, config: Config | None = None) -> ToolRegistry:
+    """The standard read-only set."""
+    config = config or Config()
+    registry = ToolRegistry()
+    for tool in (ListFiles(root, config), ReadFile(root, config), SearchCode(root, config)):
+        registry.register(tool)
+    return registry