kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/forge.py

@@ -0,0 +1,172 @@
+"""Forge integration through official CLIs (no API tokens in-process).
+
+GitHub work goes through ``gh`` and GitLab through ``glab``; the user's CLI
+login provides credentials, so no token is read or stored by KiwiMateCoder.
+Only create/list/view actions are exposed — merge, close, and delete are
+deliberately absent.
+
+The argument builders are pure so they can be unit-tested, and they know the
+CLI differences: GitLab calls pull requests "merge requests" and uses
+``--description``/``--target-branch`` instead of ``--body``/``--base``.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+from urllib.parse import urlsplit
+
+MAX_OUTPUT = 30_000
+DEFAULT_TIMEOUT = 60
+FORGE_CLIS = {"github": "gh", "gitlab": "glab"}
+READ_ACTIONS = ("pr_list", "pr_view", "issue_list", "issue_view")
+WRITE_ACTIONS = ("pr_create", "issue_create")
+
+
+def _host_from_remote(remote_url: str) -> str:
+    raw = str(remote_url).strip()
+    if not raw:
+        return ""
+    if "://" in raw:
+        return (urlsplit(raw).hostname or "").lower().rstrip(".")
+    if "@" in raw and ":" in raw:
+        return raw.split("@", 1)[1].split(":", 1)[0].strip().lower().rstrip(".")
+    return raw.split("/", 1)[0].strip().lower().rstrip(".")
+
+
+def detect_forge(remote_url: str | None) -> str | None:
+    """Return ``"github"``/``"gitlab"`` for a known host, else ``None``.
+
+    Recognizes the public hosts (``github.com``, ``gitlab.com``) over https,
+    ssh, and scp-style remotes. Self-hosted instances are not guessed.
+    """
+    host = _host_from_remote(remote_url or "")
+    if host in {"github.com", "www.github.com"}:
+        return "github"
+    if host in {"gitlab.com", "www.gitlab.com"}:
+        return "gitlab"
+    return None
+
+
+def forge_cli(forge: str | None) -> str | None:
+    """The CLI binary for a forge, or ``None`` when unknown."""
+    return FORGE_CLIS.get(str(forge or "").lower())
+
+
+def cli_available(command: str) -> bool:
+    """Whether ``command`` is on ``PATH``."""
+    return shutil.which(command) is not None
+
+
+def _pr_verb(forge: str) -> str:
+    return "mr" if str(forge).lower() == "gitlab" else "pr"
+
+
+def _body_flag(forge: str) -> str:
+    return "--description" if str(forge).lower() == "gitlab" else "--body"
+
+
+def _base_flag(forge: str) -> str:
+    return "--target-branch" if str(forge).lower() == "gitlab" else "--base"
+
+
+def pr_list_args(forge: str = "github") -> list[str]:
+    return [_pr_verb(forge), "list"]
+
+
+def pr_view_args(number: int, forge: str = "github") -> list[str]:
+    return [_pr_verb(forge), "view", str(number)]
+
+
+def pr_create_args(
+    title: str,
+    body: str = "",
+    base: str | None = None,
+    draft: bool = False,
+    forge: str = "github",
+) -> list[str]:
+    args = [
+        _pr_verb(forge),
+        "create",
+        "--title",
+        str(title),
+        _body_flag(forge),
+        str(body),
+    ]
+    if base:
+        args.extend([_base_flag(forge), str(base)])
+    if draft:
+        args.append("--draft")
+    return args
+
+
+def issue_list_args() -> list[str]:
+    return ["issue", "list"]
+
+
+def issue_view_args(number: int) -> list[str]:
+    return ["issue", "view", str(number)]
+
+
+def issue_create_args(title: str, body: str = "", forge: str = "github") -> list[str]:
+    return [
+        "issue",
+        "create",
+        "--title",
+        str(title),
+        _body_flag(forge),
+        str(body),
+    ]
+
+
+def build_write_args(forge: str, args: dict[str, Any]) -> list[str]:
+    """Build the argv for a ``forge_write`` call, raising ``ValueError``."""
+    action = str(args.get("action") or "").strip().lower()
+    title = str(args.get("title") or "").strip()
+    body = str(args.get("body") or "")
+    base = str(args["base"]).strip() if args.get("base") else None
+    if action == "pr_create":
+        if not title:
+            raise ValueError("A non-empty 'title' is required for pr_create.")
+        return pr_create_args(title, body, base, bool(args.get("draft")), forge=forge)
+    if action == "issue_create":
+        if not title:
+            raise ValueError("A non-empty 'title' is required for issue_create.")
+        return issue_create_args(title, body, forge=forge)
+    raise ValueError(f"Unknown forge_write action '{action}'.")
+
+
+def current_remote_url(session: Any) -> str | None:
+    """Return the ``origin`` remote URL for the session workspace, if any."""
+    from kiwimatecoder import git as git_module
+
+    code, output = git_module.run_git(["remote", "get-url", "origin"], session)
+    if code != 0:
+        return None
+    text = output.strip()
+    return text.splitlines()[0].strip() if text else None
+
+
+def run_forge(
+    cli: str, args: list[str], session: Any, timeout: int = DEFAULT_TIMEOUT
+) -> tuple[int, str]:
+    """Run a forge CLI command in the workspace; never raises, never a shell."""
+    command = [cli, *(str(arg) for arg in args)]
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=str(session.workspace_root),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError:
+        return 127, f"{cli} is not installed or not on PATH."
+    except subprocess.TimeoutExpired:
+        return 124, f"{cli} timed out after {timeout}s."
+    output = proc.stdout or ""
+    if proc.stderr:
+        output = f"{output}\n{proc.stderr}" if output else proc.stderr
+    return proc.returncode, output

kiwimatecoder/git.py

@@ -0,0 +1,164 @@
+"""Git helpers: pure argument builders and a subprocess runner.
+
+Only safe, non-destructive actions are exposed. ``push``, ``reset``, and
+``clean`` are deliberately absent: mutating the remote or discarding work is
+not something an agent should do through this surface.
+
+Argument builders return argv lists so callers pass values as separate
+arguments. That removes any shell-quoting surface: the runner never uses
+``shell=True``.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import subprocess
+from typing import Any
+
+DEFAULT_TIMEOUT = 30
+MAX_OUTPUT = 30_000
+LOG_LIMIT_MIN = 1
+LOG_LIMIT_MAX = 100
+WRITE_ACTIONS = ("stage", "unstage", "commit", "checkout_branch")
+
+_BRANCH_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+
+
+def status_args(*, short: bool = True) -> list[str]:
+    """``git status`` argv, short format by default."""
+    return ["status", "--short"] if short else ["status"]
+
+
+def diff_args(
+    *, staged: bool = False, path: str | None = None, ref: str | None = None
+) -> list[str]:
+    """``git diff`` argv for unstaged/staged changes, optionally against ``ref``."""
+    args = ["diff"]
+    if staged:
+        args.append("--staged")
+    if ref:
+        args.append(str(ref))
+    if path:
+        args.extend(["--", str(path)])
+    return args
+
+
+def log_args(
+    limit: int = 20, *, path: str | None = None, oneline: bool = True
+) -> list[str]:
+    """``git log`` argv with a clamped ``limit`` (1-100)."""
+    try:
+        count = int(limit)
+    except (TypeError, ValueError):
+        count = 20
+    count = max(LOG_LIMIT_MIN, min(count, LOG_LIMIT_MAX))
+    args = ["log", f"-{count}", "--no-color"]
+    if oneline:
+        args.append("--oneline")
+    if path:
+        args.extend(["--", str(path)])
+    return args
+
+
+def show_args(ref: str = "HEAD") -> list[str]:
+    """``git show`` argv for one commit."""
+    return ["show", "--no-color", str(ref or "HEAD")]
+
+
+def branch_args() -> list[str]:
+    """``git branch`` argv listing local branches."""
+    return ["branch", "--list", "--no-color"]
+
+
+def valid_branch(name: str) -> bool:
+    """Whether ``name`` is a safe, plausible branch name.
+
+    Mirrors the common ``git check-ref-format --branch`` rules that matter
+    here without shelling out: no leading dash, no ``..``/``@{``/``//``, and
+    no trailing ``/``, ``.``, or ``.lock``.
+    """
+    cleaned = str(name).strip()
+    if not cleaned or cleaned.startswith("-"):
+        return False
+    if not _BRANCH_RE.match(cleaned):
+        return False
+    if ".." in cleaned or "@{" in cleaned or "//" in cleaned:
+        return False
+    return not cleaned.endswith(("/", ".", ".lock"))
+
+
+def _clean_paths(raw: Any) -> list[str]:
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise ValueError("'paths' must be a list of paths.")
+    paths: list[str] = []
+    for item in raw:
+        text = str(item).strip()
+        if not text:
+            raise ValueError("'paths' entries must be non-empty.")
+        paths.append(text)
+    return paths
+
+
+def build_write_args(args: dict[str, Any]) -> list[str]:
+    """Build the argv for a ``git_write`` call, raising ``ValueError`` when invalid."""
+    action = str(args.get("action") or "").strip().lower()
+    if action in {"stage", "unstage"}:
+        paths = _clean_paths(args.get("paths"))
+        if not paths:
+            raise ValueError(f"'paths' is required for {action}.")
+        if action == "stage":
+            return ["add", "--", *paths]
+        return ["restore", "--staged", "--", *paths]
+    if action == "commit":
+        message = str(args.get("message") or "").strip()
+        if not message:
+            raise ValueError("A non-empty 'message' is required for commit.")
+        return ["commit", "-m", message]
+    if action == "checkout_branch":
+        branch = str(args.get("branch") or "").strip()
+        if not valid_branch(branch):
+            raise ValueError(f"Invalid branch name '{branch}'.")
+        return ["checkout", "-b", branch]
+    raise ValueError(f"Unknown git_write action '{action}'.")
+
+
+def run_git(
+    args: list[str], session: Any, timeout: int = DEFAULT_TIMEOUT
+) -> tuple[int, str]:
+    """Run ``git`` with ``args`` in the session workspace.
+
+    Returns ``(returncode, output)`` where output is stdout plus stderr. Never
+    raises: a missing binary and a timeout become synthetic exit codes so the
+    tool can report them as text.
+    """
+    command = ["git", *(str(arg) for arg in args)]
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=str(session.workspace_root),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError:
+        return 127, "git is not installed or not on PATH."
+    except subprocess.TimeoutExpired:
+        return 124, f"git timed out after {timeout}s."
+    output = proc.stdout or ""
+    if proc.stderr:
+        output = f"{output}\n{proc.stderr}" if output else proc.stderr
+    return proc.returncode, output
+
+
+def preview(args: dict[str, Any], session: Any) -> str:
+    """Return the exact ``git ...`` command line for the approval prompt."""
+    del session
+    try:
+        command = build_write_args(args)
+    except ValueError as exc:
+        return str(exc)
+    return "git " + " ".join(shlex.quote(part) for part in command)

kiwimatecoder/headless.py

@@ -0,0 +1,255 @@
+"""Headless one-shot agent runs shared by the CLI and the SDK.
+
+The CLI's ``-p/--print`` mode and :mod:`kiwimatecoder.sdk` both drive the
+regular :class:`~kiwimatecoder.agent.Agent` through this module so session
+construction, event collection, and cost accounting live in one place.
+
+Rendering stays with the caller: pass ``on_event`` to receive
+``(name, payload)`` notifications for every emitted event and ``console`` for
+the agent's own tool/progress output. Without a console the run is silent.
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from rich.console import Console
+
+from kiwimatecoder import config, ui
+from kiwimatecoder.agent import Agent
+from kiwimatecoder.permissions import ConfirmFn, PermissionMode
+from kiwimatecoder.pricing import estimate_cost
+from kiwimatecoder.session import Session
+
+EventCallback = Callable[[str, dict[str, Any]], None]
+
+
+@dataclass
+class RunOutcome:
+    """Everything one headless run produces for its caller."""
+
+    text: str = ""
+    usage: dict[str, int] = field(default_factory=dict)
+    cost_usd: float | None = None
+    provider: str = ""
+    model: str = ""
+    mode: str = ""
+    tools_used: list[str] = field(default_factory=list)
+    messages: int = 0
+    success: bool = True
+    error: str | None = None
+
+
+def _resolve_workspace(workspace: str | Path | None) -> Path:
+    root = Path(workspace).expanduser() if workspace is not None else Path.cwd()
+    if not root.is_dir():
+        raise ValueError(f"Workspace is not a directory: {root}")
+    return root.resolve()
+
+
+def build_session(
+    *,
+    workspace: str | Path | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    mode: PermissionMode | str | None = None,
+) -> Session:
+    """Build a fresh session exactly like the interactive launch path.
+
+    ``provider``/``model``/``mode`` override the configured values for this
+    run only; nothing is persisted. An overriding ``provider`` becomes the
+    primary, ahead of the configured roster. Raises ``ValueError`` for an
+    unknown workspace or mode, ``config.ModelNotChosenError`` (a
+    ``ValueError``) when no model was passed or chosen for the provider, and
+    ``KeyError`` for an unknown provider.
+    """
+    cfg = config.load_config()
+    provider_id = provider or config.get_selected_provider_id(cfg)
+    provider_cfg = config.get_provider_config(provider_id, cfg)
+    resolved_model = config.require_model(provider_cfg, cfg, override=model)
+    roster = config.get_active_provider_ids(cfg)
+    active_provider_ids = [provider_id, *(pid for pid in roster if pid != provider_id)]
+    if mode is None:
+        try:
+            resolved_mode = PermissionMode.from_str(str(cfg.get("default_mode", "ask")))
+        except ValueError:
+            resolved_mode = PermissionMode.ASK
+    else:
+        resolved_mode = PermissionMode.from_str(mode) if isinstance(mode, str) else mode
+    return Session(
+        provider_id=provider_id,
+        model=resolved_model,
+        mode=resolved_mode,
+        workspace_root=_resolve_workspace(workspace),
+        active_provider_ids=active_provider_ids,
+        always_allowed=set(config.get_always_allowed_tools(cfg)),
+        output_style=config.get_output_style(cfg),
+        custom_system_prompt=config.get_system_prompt(cfg),
+        command_rules=config.get_command_rules(cfg),
+        trusted_workspace=config.get_trusted_workspace(cfg),
+        verify_command=config.get_verify_command(cfg),
+        compact_at_tokens=config.get_compact_at_tokens(cfg),
+        context_window=config.get_context_window(cfg),
+    )
+
+
+def _apply_overrides(
+    session: Session,
+    *,
+    workspace: str | Path | None,
+    provider: str | None,
+    model: str | None,
+    mode: PermissionMode | str | None,
+) -> None:
+    """Apply per-run overrides to an existing session.
+
+    Raises ``config.ModelNotChosenError`` when switching to a provider with no
+    model passed or chosen.
+    """
+    if mode is not None:
+        session.mode = PermissionMode.from_str(mode) if isinstance(mode, str) else mode
+    if provider and provider != session.provider_id:
+        provider_cfg = config.get_provider_config(provider)
+        session.set_provider(provider, config.require_model(provider_cfg, override=model))
+        session.active_provider_ids = [
+            provider,
+            *(pid for pid in session.active_provider_ids if pid != provider),
+        ]
+    elif model:
+        session.model = model
+    if workspace is not None:
+        session.workspace_root = _resolve_workspace(workspace)
+
+
+def _deny(summary: str, preview: str | None) -> bool:
+    """Default approval behavior for runs with no interactive user."""
+    return False
+
+
+def _final_text(session: Session, deltas: list[str]) -> str:
+    """The last assistant message, falling back to the streamed text."""
+    for message in reversed(session.messages):
+        if message.get("role") == "assistant" and message.get("content"):
+            return str(message["content"])
+    return "".join(deltas)
+
+
+def shutdown_runtime() -> None:
+    """Stop anything a headless run lazily started (MCP, LSP, browser)."""
+    from kiwimatecoder import browser, lsp, mcp
+
+    manager = mcp.get_manager()
+    if manager is not None:
+        mcp.set_manager(None)
+        manager.shutdown()
+    lsp_manager = lsp.get_manager()
+    if lsp_manager is not None:
+        lsp.set_manager(None)
+        lsp_manager.shutdown()
+    browser.reset_driver()
+
+
+async def run_agent_once(
+    prompt: str,
+    *,
+    workspace: str | Path | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    mode: PermissionMode | str | None = None,
+    confirm: ConfirmFn | None = None,
+    on_event: EventCallback | None = None,
+    max_turns: int | None = 30,
+    console: Console | None = None,
+    session: Session | None = None,
+    render_text: bool = True,
+    output_mode: str | None = None,
+) -> RunOutcome:
+    """Drive one agent turn and return its outcome.
+
+    Approvals are denied when ``confirm`` is omitted. Text deltas are written
+    to ``console`` unless ``render_text`` is False; every emitted event is
+    forwarded to ``on_event``. Lazily started managers are shut down before
+    returning.
+    """
+    if session is None:
+        session = build_session(
+            workspace=workspace, provider=provider, model=model, mode=mode
+        )
+    else:
+        _apply_overrides(
+            session, workspace=workspace, provider=provider, model=model, mode=mode
+        )
+
+    if console is None:
+        console = Console(file=io.StringIO(), no_color=True, highlight=False)
+
+    text_parts: list[str] = []
+    tools_used: list[str] = []
+    errors: list[str] = []
+    done_reasons: list[str] = []
+
+    def collect(name: str, payload: dict[str, Any]) -> None:
+        if name == "text_delta":
+            text_parts.append(str(payload.get("text") or ""))
+        elif name == "tool_start":
+            tool = str(payload.get("tool") or "")
+            if tool and tool not in tools_used:
+                tools_used.append(tool)
+        elif name == "error":
+            errors.append(str(payload.get("error") or "provider error"))
+        elif name == "done":
+            reason = str(payload.get("reason") or "")
+            done_reasons.append(reason)
+            if reason == "budget" and payload.get("error"):
+                errors.append(str(payload["error"]))
+        if on_event is not None:
+            on_event(name, payload)
+
+    ui_config = ui.ui_config()
+    agent = Agent(
+        session,
+        console,
+        confirm if confirm is not None else _deny,
+        ascii_mode=ui_config["ascii"],
+        output_mode=output_mode or ui_config["output_mode"],
+        event_handler=collect,
+        max_turns=max_turns,
+        render_text=render_text,
+        spinner=ui_config["spinner"],
+    )
+
+    try:
+        await agent.run_turn(prompt)
+    finally:
+        shutdown_runtime()
+
+    if max_turns is not None and "max_turns" in done_reasons:
+        errors.append(
+            f"Reached the maximum of {max_turns} tool-loop turn(s) without a "
+            "final answer."
+        )
+    error = errors[0] if errors else None
+    return RunOutcome(
+        text=_final_text(session, text_parts),
+        usage={
+            "prompt_tokens": session.prompt_tokens,
+            "completion_tokens": session.completion_tokens,
+        },
+        cost_usd=estimate_cost(
+            session.prompt_tokens,
+            session.completion_tokens,
+            session.model,
+            session.provider_id,
+            is_local=session.provider.is_local,
+        ),
+        provider=session.provider_id,
+        model=session.model,
+        mode=session.mode.value,
+        tools_used=tools_used,
+        messages=len(session.messages),
+        success=error is None,
+        error=error,
+    )