ferrum-cli 0.1.0__py3-none-any.whl

ferrum/cli.py

@@ -0,0 +1,479 @@
+"""ferrum command line: inspect a directory, diagnose a task, or fix one."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from ferrum import __version__
+from ferrum.agent import Agent
+from ferrum.config import (
+    CLOUD_PRESET_URL,
+    INT_FIELDS,
+    LOCAL_PRESET_URL,
+    STR_FIELDS,
+    Config,
+    ConfigError,
+    config_file_path,
+    load_config,
+    mask_secret,
+    read_config_file,
+    setting_source,
+    write_config_value,
+    write_config_values,
+)
+from ferrum.context import discover, find_project_root
+from ferrum.model import (
+    OpenAICompatibleProvider,
+    ProviderError,
+    list_models,
+    probe_endpoint,
+)
+from ferrum.tools import default_tools
+from ferrum.verifier import Verifier
+
+PROG = "ferrum"
+DESCRIPTION = "Ferrum — a coding harness for low-level and systems programming."
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+
+EPILOG = """examples:
+  ferrum .                 inspect a project
+  ferrum "task"            diagnose with the model (read-only)
+  ferrum fix "task"        patch, build, and verify
+  ferrum fix --dry-run "t"  show the proposed patch, write nothing
+  ferrum doctor            check config, endpoint, and toolchain
+  ferrum config            show base_url / model / api_key
+  ferrum config local      switch to Ollama on localhost
+  ferrum config cloud      switch to the cloud endpoint
+  ferrum config models     list models at the current endpoint
+"""
+
+CONFIG_USAGE = """usage:
+  ferrum config                     show current settings
+  ferrum config get <key>           print one setting
+  ferrum config set <key> <value>   save one setting ('' clears it)
+  ferrum config models              list models at the current endpoint
+  ferrum config local               use Ollama at http://localhost:11434/v1
+  ferrum config cloud [url]         use the cloud endpoint
+keys: base_url, model, api_key, """ + ", ".join(sorted(INT_FIELDS))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=PROG,
+        description=DESCRIPTION,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"{PROG} {__version__}",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="enable debug logging on stderr",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="with fix: show the proposed patch but never write files",
+    )
+    parser.add_argument(
+        "target",
+        nargs="?",
+        metavar="TARGET",
+        help="directory to inspect, or a task for the model",
+    )
+    parser.add_argument(
+        "extra",
+        nargs="*",
+        help=argparse.SUPPRESS,
+    )
+    return parser
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Quiet by default; -v turns on debug output."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+        force=True,
+    )
+
+
+def _force_utf8_streams() -> None:
+    # Without this, the box-drawing line in the summary dies when output is piped.
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError, OSError):
+            pass
+
+
+def _inspect(target: str) -> int:
+    path = Path(target)
+    if not path.is_dir():
+        print(
+            f"error: not a directory: {target} (pass a directory to inspect)",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+    context = discover(find_project_root(path), load_config())
+    print(context.summary())
+    return EXIT_OK
+
+
+def _env_override_note(key: str) -> str | None:
+    var = STR_FIELDS.get(key) or INT_FIELDS.get(key)
+    if var and os.environ.get(var):
+        return f"note: {var} is set in the environment and overrides the file"
+    return None
+
+
+def _config_show() -> int:
+    try:
+        config = load_config()
+        path = config_file_path()
+        sources = {key: setting_source(key) for key in STR_FIELDS}
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    for key in ("base_url", "model", "api_key"):
+        value = getattr(config, key)
+        if key == "api_key":
+            display = mask_secret(value)
+        else:
+            display = value or "(not set)"
+        print(f"{key:<9} = {display}  [{sources[key]}]")
+    suffix = "" if path.exists() else " (not created yet)"
+    print(f"config file: {path}{suffix}")
+    return EXIT_OK
+
+
+def _config_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)),
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+    try:
+        value = getattr(load_config(), key)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    if value == "" or value is None:
+        print(f"{key} is not set.", file=sys.stderr)
+        return EXIT_ERROR
+    print(value)
+    return EXIT_OK
+
+
+def _config_set(key: str, value: str) -> int:
+    try:
+        path = write_config_value(key, value)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    if value == "":
+        print(f"{key} cleared ({path})")
+    else:
+        display = mask_secret(value) if key == "api_key" else value
+        print(f"{key} = {display}  [saved to {path}]")
+    note = _env_override_note(key)
+    if note:
+        print(note, file=sys.stderr)
+    return EXIT_OK
+
+
+def _config_models() -> int:
+    try:
+        config = load_config()
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    try:
+        available = list_models(config.base_url, timeout=15, api_key=config.api_key)
+    except ProviderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    if not available:
+        print(
+            f"no models listed at {config.base_url}"
+            " (the server may not support GET /models,"
+            " or the api_key is wrong)",
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+    for name in available:
+        print(name)
+    print(f"\nset one: ferrum config set model {available[0]}", file=sys.stderr)
+    return EXIT_OK
+
+
+def _config_preset(kind: str, rest: list[str]) -> int:
+    # The api_key is never touched: local servers ignore it, and clearing it
+    # would force re-entering the cloud key on every switch back.
+    if kind == "local":
+        url = LOCAL_PRESET_URL
+    else:
+        url = rest[0] if rest else CLOUD_PRESET_URL
+    try:
+        path = write_config_values({"base_url": url})
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    print(f"base_url = {url}  [saved to {path}]")
+    note = _env_override_note("base_url")
+    if note:
+        print(note, file=sys.stderr)
+    if kind == "cloud" and not os.environ.get("FERRUM_API_KEY") and not _file_api_key():
+        print(
+            "warning: api_key is not set —"
+            " ferrum config set api_key <key>",
+            file=sys.stderr,
+        )
+    print("pick a model: ferrum config models"
+          "  then  ferrum config set model <name>", file=sys.stderr)
+    return EXIT_OK
+
+
+def _file_api_key() -> str:
+    value = read_config_file().get("api_key", "")
+    return value if isinstance(value, str) else ""
+
+
+def _config_command(words: list[str]) -> int:
+    if not words:
+        return _config_show()
+    cmd = words[0]
+    if cmd == "get":
+        if len(words) != 2:
+            print("error: usage: ferrum config get <key>", file=sys.stderr)
+            return EXIT_ERROR
+        return _config_get(words[1])
+    if cmd == "set":
+        if len(words) < 3:
+            print("error: usage: ferrum config set <key> <value>", file=sys.stderr)
+            return EXIT_ERROR
+        return _config_set(words[1], " ".join(words[2:]))
+    if cmd == "models":
+        return _config_models()
+    if cmd in {"local", "cloud"}:
+        return _config_preset(cmd, words[1:])
+    print(f"error: unknown config command: {cmd}", file=sys.stderr)
+    print(CONFIG_USAGE, file=sys.stderr)
+    return EXIT_ERROR
+
+
+def _doctor() -> int:
+    """One screen that answers: can ferrum run a task here, and if not, why?"""
+    problems: list[str] = []
+    warnings: list[str] = []
+
+    print(f"{'python':<12}{sys.version.split()[0]} (need >= 3.10)")
+    keys = ("base_url", "model", "api_key")
+    try:
+        config = load_config()
+        sources = {key: setting_source(key) for key in keys}
+    except ConfigError as exc:
+        print(f"{'config':<12}broken — {exc}")
+        problems.append("fix or delete the config file")
+        config = Config()  # defaults, so the rest of the report still runs
+        sources = {key: "default" for key in keys}
+
+    path = config_file_path()
+    print(f"{'config file':<12}{path}{' ' if path.exists() else ' (not created yet)'}")
+    for key in keys:
+        value = getattr(config, key)
+        display = mask_secret(value) if key == "api_key" else (value or "(not set)")
+        print(f"{key:<12}{display}  [{sources[key]}]")
+        if key == "model" and not value:
+            problems.append("model is not set — ferrum config set model <name>")
+    if not config.api_key and not config.base_url.startswith("http://localhost"):
+        warnings.append("cloud endpoints usually need an api_key")
+
+    models, error = probe_endpoint(config.base_url, timeout=10, api_key=config.api_key)
+    if error:
+        print(f"{'endpoint':<12}unreachable — {error}")
+        problems.append(f"cannot reach {config.base_url} (is the server running?)")
+    elif models:
+        print(f"{'endpoint':<12}ok — {len(models)} models listed")
+    else:
+        print(f"{'endpoint':<12}answered, but listed no models")
+        warnings.append("the server listed no models; chat may still work")
+
+    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'}")
+    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")
+
+    print()
+    for line in problems:
+        print(f"problem: {line}")
+    for line in warnings:
+        print(f"warning: {line}")
+    if problems:
+        print("verdict: not ready")
+        return EXIT_ERROR
+    print("verdict: ready")
+    return EXIT_OK
+
+
+def _confirm(prompt: str) -> bool:
+    try:
+        answer = input(prompt)
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return answer.strip().lower() in {"y", "yes"}
+
+
+def _agent_task(task: str, *, edit: bool, dry_run: bool = False) -> int:
+    try:
+        config = load_config()
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    missing = config.missing()
+    if missing:
+        print(f"error: {', '.join(missing)} is not set.", file=sys.stderr)
+        print(
+            f"  point it at a model served by {config.base_url}:",
+            file=sys.stderr,
+        )
+        print("    ferrum config models", file=sys.stderr)
+        print("    ferrum config set model <name>", file=sys.stderr)
+        print(
+            f"  (or export {', '.join(missing)}=... for this shell)",
+            file=sys.stderr,
+        )
+        try:
+            available = list_models(
+                config.base_url, timeout=15, api_key=config.api_key
+            )
+        except ProviderError:
+            available = []
+        if available:
+            print(f"  available: {', '.join(available)}", file=sys.stderr)
+        else:
+            print(f"  ferrum cannot see any model at {config.base_url}", file=sys.stderr)
+        return EXIT_ERROR
+
+    root = find_project_root(Path.cwd())
+    context = discover(root, config)
+    provider = OpenAICompatibleProvider(
+        config.base_url,
+        config.model,
+        config.api_key,
+        config.request_timeout,
+        config.max_tokens,
+    )
+    agent = Agent(
+        config,
+        provider,
+        default_tools(root, config),
+        printer=print,
+        verifier=Verifier(root, timeout=config.command_timeout),
+    )
+    try:
+        result = agent.run(task, context, edit=edit, confirm=_confirm, dry_run=dry_run)
+    except ProviderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+    if result.text:
+        print()
+        print(result.text)
+    if result.patched:
+        print()
+        if result.verified:
+            print("✓ Fix verified")
+        elif result.verified is False:
+            print("✗ Fix not verified — build or tests did not pass")
+    if dry_run:
+        print()
+        print("(dry run — no files were changed)")
+    if result.capped:
+        return EXIT_ERROR
+    if result.patched and result.verified is False:
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Plain white text, always: Python 3.14+ colours argparse help and
+    # tracebacks on a terminal otherwise.
+    os.environ["PYTHON_COLORS"] = "0"
+    _force_utf8_streams()
+    args_list = list(sys.argv[1:] if argv is None else argv)
+
+    parser = build_parser()
+    args = parser.parse_args(args_list)
+    setup_logging(args.verbose)
+
+    if args.target is None:
+        if args.dry_run:
+            print(
+                'error: usage: ferrum fix --dry-run "<task>"',
+                file=sys.stderr,
+            )
+            return EXIT_ERROR
+        parser.print_help()
+        return EXIT_OK
+
+    if args.target == "fix":
+        task = " ".join(args.extra).strip()
+        if not task:
+            print('error: usage: ferrum fix "<task>"', file=sys.stderr)
+            return EXIT_ERROR
+        return _agent_task(task, edit=True, dry_run=args.dry_run)
+
+    if args.dry_run:
+        print(
+            'error: --dry-run only applies to: ferrum fix --dry-run "<task>"',
+            file=sys.stderr,
+        )
+        return EXIT_ERROR
+
+    if args.target == "config":
+        return _config_command(args.extra)
+
+    if args.target == "doctor":
+        if args.extra:
+            print("error: usage: ferrum doctor", file=sys.stderr)
+            return EXIT_ERROR
+        return _doctor()
+
+    target = args.target
+    path = Path(target)
+    if path.is_dir():
+        return _inspect(target)
+    if path.exists():
+        return _inspect(target)  # prints the not-a-directory error
+    if "/" in target or "\\" in target or target.startswith("."):
+        print(f"error: no such directory: {target}", file=sys.stderr)
+        return EXIT_ERROR
+
+    task = " ".join([target, *args.extra])
+    return _agent_task(task, edit=False)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ferrum/config.py

@@ -0,0 +1,178 @@
+"""Harness settings: model endpoint plus the limits that keep Ferrum small.
+
+Settings resolve in layers: environment variable > config file > default.
+The file lives outside the project (Windows: %APPDATA%\\ferrum\\config.json,
+else $XDG_CONFIG_HOME/ferrum/config.json) so switching between a local
+Ollama server and a cloud endpoint is one ``ferrum config`` command away.
+Local models need no API key; every secret is optional.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+LOCAL_PRESET_URL = "http://localhost:11434/v1"
+CLOUD_PRESET_URL = "https://api.routeway.ai/v1"
+
+
+class ConfigError(Exception):
+    pass
+
+
+INT_FIELDS = {
+    "max_file_bytes": "FERRUM_MAX_FILE_BYTES",
+    "max_context_bytes": "FERRUM_MAX_CONTEXT_BYTES",
+    "max_files": "FERRUM_MAX_FILES",
+    "max_search_results": "FERRUM_MAX_SEARCH_RESULTS",
+    "max_iterations": "FERRUM_MAX_ITERATIONS",
+    "max_tokens": "FERRUM_MAX_TOKENS",
+    "request_timeout": "FERRUM_TIMEOUT",
+    "command_timeout": "FERRUM_COMMAND_TIMEOUT",
+}
+STR_FIELDS = {
+    "base_url": "FERRUM_BASE_URL",
+    "model": "FERRUM_MODEL",
+    "api_key": "FERRUM_API_KEY",
+}
+
+
+def config_file_path() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA")
+        root = Path(base) if base else Path.home() / ".config"
+    else:
+        root = Path(os.environ.get("XDG_CONFIG_HOME")) if os.environ.get(
+            "XDG_CONFIG_HOME"
+        ) else Path.home() / ".config"
+    return root / "ferrum" / "config.json"
+
+
+def read_config_file() -> dict[str, object]:
+    path = config_file_path()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise ConfigError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must contain a JSON object")
+    return data
+
+
+def write_config_values(values: dict[str, str]) -> Path:
+    """Merge settings into the config file; an empty value removes the key."""
+    known = {**STR_FIELDS, **INT_FIELDS}
+    for key in values:
+        if key not in known:
+            raise ConfigError(
+                f"unknown setting {key!r}; choose from: "
+                + ", ".join(sorted(known))
+            )
+    path = config_file_path()
+    data = read_config_file()
+    for key, value in values.items():
+        if value == "":
+            data.pop(key, None)
+        elif key in INT_FIELDS:
+            try:
+                data[key] = int(value)
+            except ValueError as exc:
+                raise ConfigError(
+                    f"{key} must be an integer, got {value!r}"
+                ) from exc
+        else:
+            data[key] = value
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def write_config_value(key: str, value: str) -> Path:
+    return write_config_values({key: value})
+
+
+def mask_secret(value: str) -> str:
+    if not value:
+        return "(not set)"
+    if len(value) <= 8:
+        return "*" * len(value)
+    return value[:6] + "..." + value[-4:]
+
+
+@dataclass(frozen=True)
+class Config:
+    max_file_bytes: int = 256 * 1024  # one file
+    max_context_bytes: int = 400_000  # whole listing
+    max_files: int = 500
+    max_search_results: int = 200
+    max_iterations: int = 25  # agent loop cap
+    max_tokens: int = 2048  # per model response
+    request_timeout: int = 120  # per model request (CPU-served models are slow)
+    command_timeout: int = 300  # per build/test command
+
+    base_url: str = LOCAL_PRESET_URL
+    model: str = ""
+    api_key: str = ""
+
+    def __post_init__(self) -> None:
+        for name in INT_FIELDS:
+            value = getattr(self, name)
+            if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+                raise ConfigError(f"{name} must be a positive integer, got {value!r}")
+        if not isinstance(self.base_url, str) or not self.base_url.strip():
+            raise ConfigError(f"base_url must be a non-empty string, got {self.base_url!r}")
+
+    def missing(self) -> list[str]:
+        """Env/file keys that must be set before the model can be used."""
+        missing = []
+        if not self.model:
+            missing.append(STR_FIELDS["model"])
+        return missing
+
+
+def setting_source(name: str) -> str:
+    """Where a setting's effective value comes from: env, file, or default."""
+    var = STR_FIELDS.get(name) or INT_FIELDS.get(name)
+    if var and os.environ.get(var):
+        return f"env {var}"
+    if name in read_config_file():
+        return "file"
+    return "default"
+
+
+def load_config(**overrides: object) -> Config:
+    values: dict[str, object] = {}
+    path = config_file_path()
+    for name, raw in read_config_file().items():
+        if name in STR_FIELDS:
+            if not isinstance(raw, str):
+                raise ConfigError(f"{path}: {name} must be a string")
+            if raw:
+                values[name] = raw
+        elif name in INT_FIELDS:
+            if not isinstance(raw, int) or isinstance(raw, bool):
+                raise ConfigError(f"{path}: {name} must be an integer")
+            values[name] = raw
+        else:
+            raise ConfigError(f"{path}: unknown setting {name!r}")
+    for name, var in STR_FIELDS.items():
+        raw = os.environ.get(var)
+        if raw:
+            values[name] = raw
+    for name, var in INT_FIELDS.items():
+        raw = os.environ.get(var)
+        if raw:
+            try:
+                values[name] = int(raw)
+            except ValueError as exc:
+                raise ConfigError(f"{var} must be an integer, got {raw!r}") from exc
+    values.update(overrides)
+    try:
+        return Config(**values)
+    except TypeError as exc:
+        raise ConfigError(str(exc)) from exc