bugpilot 0.1.0__py3-none-any.whl

bugpilot/cli_json.py

@@ -0,0 +1,173 @@
+"""The ``--json`` envelope: bugpilot's machine-facing output contract.
+
+Lives in the CLI layer, not in ``core``, because rendering is an adapter's job
+(design invariant 3). The VS Code extension consumes this; the MCP server gets
+the same data as Python objects and never goes through here.
+
+Contract, from ``docs/adapter_design.md`` section 5.1:
+
+- Exactly one JSON object on stdout, whether the command succeeded or failed.
+- ``schema_version`` from the first release, so the extension can refuse a
+  version it does not understand instead of misreading fields.
+- On failure the human-readable message still goes to stderr and the exit code
+  is still non-zero. The two channels are additive, not alternatives.
+- Consumers branch on ``error.code`` and never parse ``error.message``.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+SCHEMA_VERSION = 1
+
+
+def success(command: str, **fields: object) -> dict[str, object]:
+    """Build a success envelope. ``fields`` are merged in as-is."""
+    payload: dict[str, object] = {
+        "schema_version": SCHEMA_VERSION,
+        "ok": True,
+        "command": command,
+    }
+    payload.update(fields)
+    payload.setdefault("warnings", [])
+    return payload
+
+
+def failure(command: str, code: str, message: str, **fields: object) -> dict[str, object]:
+    """Build a failure envelope carrying a stable code and a human message."""
+    payload: dict[str, object] = {
+        "schema_version": SCHEMA_VERSION,
+        "ok": False,
+        "command": command,
+        "error": {"code": code, "message": message},
+    }
+    payload.update(fields)
+    return payload
+
+
+def _utf8_stdout() -> None:
+    """Make stdout UTF-8 before JSON is written to it.
+
+    JSON between programs is UTF-8 (RFC 8259), and the VS Code extension
+    decodes it as UTF-8. Python on Windows writes a pipe in the ANSI code page
+    (cp1252) unless PYTHONIOENCODING or UTF-8 mode says otherwise: a "→" in an
+    instructions file or a Chinese bug title failed the command with "'charmap'
+    codec can't encode", and an "é" arrived as a byte the extension could not
+    decode. A console is unaffected — Python
+    writes it as UTF-16 — and a stream that is UTF-8 already is left alone.
+    """
+    stream = sys.stdout
+    encoding = (getattr(stream, "encoding", None) or "").lower().replace("-", "").replace("_", "")
+    reconfigure = getattr(stream, "reconfigure", None)
+    if encoding == "utf8" or reconfigure is None:
+        return
+    try:
+        reconfigure(encoding="utf-8")
+    except (ValueError, OSError):
+        pass
+
+
+def emit(payload: dict[str, object]) -> None:
+    """Write one envelope to stdout.
+
+    ``ensure_ascii=False`` so a Chinese bug title stays readable in a terminal
+    and in an editor's output pane; the stream is made UTF-8 first.
+    """
+    _utf8_stdout()
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def emit_failure(command: str, code: str, message: str, **fields: object) -> None:
+    """Write a failure envelope to stdout and the same message to stderr.
+
+    Callers still return a non-zero exit code: a consumer that ignores JSON and
+    only checks the exit status must see the failure too.
+    """
+    emit(failure(command, code, message, **fields))
+    print(f"ERROR: {message}", file=sys.stderr)
+
+
+class JsonLinesEmitter:
+    """Streams one JSON object per line while a run is in progress.
+
+    The two output channels have different jobs, per design section 5.1:
+    JSONL is live events for as long as the process runs, and
+    ``run.json`` is the state that survives it. A consumer follows
+    the stream for progress and re-reads the file after a restart.
+
+    ``run_investigation``'s progress callback fires *before* each step, so
+    completion is inferred: the next ``step_started`` closes the previous step,
+    and :meth:`finish` closes the last one. A step that raises is never closed,
+    which is what distinguishes it from one that finished.
+    """
+
+    def __init__(self, work_item_id: str, source: str) -> None:
+        self._open_step: str | None = None
+        self._emit({"type": "started", "work_item_id": work_item_id, "source": source})
+
+    def _emit(self, event: dict[str, object]) -> None:
+        payload: dict[str, object] = {"schema_version": SCHEMA_VERSION}
+        payload.update(event)
+        _utf8_stdout()
+        print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+    def skipped(self, steps: list[str]) -> None:
+        for step in steps:
+            self._emit({"type": "step_skipped", "step": step, "reason": "plan"})
+
+    def progress(self, event: str) -> None:
+        """Callback for ``run_investigation(progress=...)``.
+
+        Non-step events (the clean phase) are reported under their own type so a
+        consumer can show them without mistaking them for pipeline steps.
+        """
+        if event.startswith("clean_"):
+            self._emit({"type": "phase", "phase": event})
+            return
+        self._close_open_step()
+        self._open_step = event
+        self._emit({"type": "step_started", "step": event})
+
+    def _close_open_step(self) -> None:
+        if self._open_step is not None:
+            self._emit({"type": "step_completed", "step": self._open_step})
+            self._open_step = None
+
+    def finish(self, generated_files: list[str], warnings: list[str] | None = None) -> None:
+        self._close_open_step()
+        for path in generated_files:
+            self._emit({"type": "artifact", "path": path})
+        # Carried on the terminal event rather than as a new event type: a
+        # consumer that has not been taught about `warnings` ignores the extra
+        # key, where an unknown event type is a shape it has to decide about.
+        completed: dict[str, object] = {"type": "completed", "ok": True}
+        if warnings:
+            completed["warnings"] = list(warnings)
+        self._emit(completed)
+
+    def fail(self, code: str, message: str) -> None:
+        """End the stream without closing the step that raised."""
+        self._emit({"type": "completed", "ok": False, "error": {"code": code, "message": message}})
+
+
+def emit_stream_failure(code: str, message: str) -> None:
+    """Close a --json-lines stream that failed before or outside a run.
+
+    A consumer waits for a terminal event; without one an aborted run is
+    indistinguishable from a process that is still working.
+    """
+    _utf8_stdout()
+    print(
+        json.dumps(
+            {
+                "schema_version": SCHEMA_VERSION,
+                "type": "completed",
+                "ok": False,
+                "error": {"code": code, "message": message},
+            },
+            ensure_ascii=False,
+        ),
+        flush=True,
+    )
+    print(f"ERROR: {message}", file=sys.stderr)

bugpilot/core/__init__.py

@@ -0,0 +1 @@
+"""Core modules for bugpilot."""

bugpilot/core/agent_runner.py

@@ -0,0 +1,138 @@
+"""Deprecated: launching a coding agent from bugpilot.
+
+**This module is deprecated as of V1 and will be removed in a future
+release** (design section 9, phase 7). It still works, and nothing that
+depends on it has been changed.
+
+It exists because bugpilot originally launched Claude in a terminal after
+preparing a package. That is no longer the default: `bugpilot bug` prepares and
+stops, and this module runs only when a command line asks for it with
+``--launch-agent claude`` or ``--launch-agent copilot``. The three-entry architecture made that the odd one out:
+the MCP server is *called by* an agent, and the VS Code extension hands the
+package over on a human's click. In both, deciding to involve a model is a
+separate act from preparing the context — which is requirement R5, and the
+reason this path is going away rather than being extended.
+
+What to use instead:
+
+- ``bugpilot bug <ID>`` (prepare-only is the default), then hand ``.ai/<ID>/task.md`` to
+  whatever agent you use. The extension's "Copy handoff prompt" does exactly
+  this, and the Claude Code skill in ``skills/`` tells the agent to do it
+  itself.
+- The handoff wording now lives in :mod:`bugpilot.core.handoff`, shared with
+  the MCP prompt and the skill.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import AppConfig, load_config
+from .executables import child_environment, find_executable
+from .handoff import handoff_prompt, retry_handoff_prompt
+
+# Kept as format strings because callers use `.format(...)` on them, but the
+# wording now comes from `handoff.py` — the one place that says what an agent is
+# told to do with a prepared package (design 5.5: a skill and an MCP prompt
+# carrying the same instructions in two files will drift).
+HANDOFF_PROMPT = handoff_prompt("{issue_key}")
+RETRY_HANDOFF_PROMPT = retry_handoff_prompt("{prompt_file}")
+
+# What `bugpilot bug --launch-agent` accepts. The flag is the only way the CLI
+# starts an agent: there is no implicit default one.
+LAUNCHABLE_AGENTS: tuple[str, ...] = ("claude", "copilot")
+
+
+@dataclass
+class AgentRunResult:
+    agent: str
+    ran: bool
+    command: list[str]
+    returncode: int | None = None
+    skipped_reason: str | None = None
+
+
+def build_agent_command(agent: str, issue_key: str, config: AppConfig, prompt: str | None = None) -> list[str]:
+    prompt = prompt or HANDOFF_PROMPT.format(issue_key=issue_key)
+    if agent == "claude":
+        base = [config.claude_command, *shlex.split(config.claude_args)]
+    elif agent == "copilot":
+        base = [config.copilot_command, *shlex.split(config.copilot_args)]
+    else:
+        raise ValueError(f"Unknown agent: {agent}")
+    return [*base, prompt]
+
+
+def run_agent(
+    repo_root: Path,
+    issue_key: str,
+    agent: str,
+    config: AppConfig | None = None,
+    prompt: str | None = None,
+) -> AgentRunResult:
+    _warn_deprecated(agent)
+    config = config if config is not None else load_config(repo_root)
+    command = build_agent_command(agent, issue_key, config, prompt)
+    launch = _resolve_launch_command(command)
+    if launch is None:
+        return AgentRunResult(
+            agent=agent,
+            ran=False,
+            command=command,
+            skipped_reason=f"{command[0]} was not found on PATH.",
+        )
+    # Inherit the terminal so the agent runs interactively and the developer can
+    # watch it work. Run in the target repo root (the current working directory),
+    # with the current directory out of the agent's own program lookups.
+    completed = subprocess.run(launch, cwd=repo_root, env=child_environment())
+    return AgentRunResult(
+        agent=agent,
+        ran=True,
+        command=command,
+        returncode=completed.returncode,
+    )
+
+
+def _warn_deprecated(agent: str) -> None:
+    """Tell the developer, on stderr, that this path is going away.
+
+    A ``DeprecationWarning`` would be the library-shaped answer and invisible
+    here: Python hides those by default, and the audience is a person watching a
+    terminal. stderr also keeps requirement R1 intact — the human-readable
+    stdout of every existing command is untouched.
+    """
+    print(
+        f"NOTE: launching {agent} from bugpilot is deprecated and will be removed "
+        "in a future release.",
+        file=sys.stderr,
+    )
+    print(
+        "      Prefer leaving out --launch-agent (prepare-only is the default) and handing "
+        "task.md over yourself (the VS Code extension's Copy handoff prompt does this).",
+        file=sys.stderr,
+    )
+
+
+def _resolve_launch_command(command: list[str]) -> list[str] | None:
+    """Resolve the executable to a runnable form for the current OS.
+
+    `find_executable` honors PATHEXT (so it finds `claude.cmd` on Windows) and,
+    unlike shutil.which, never looks in the current directory — the repository.
+    CreateProcess cannot launch a .cmd/.bat directly, so a
+    Windows batch shim runs through the system's own cmd.exe, by absolute path.
+    """
+    resolved = find_executable(command[0])
+    if resolved is None:
+        return None
+    rest = command[1:]
+    if sys.platform == "win32" and resolved.lower().endswith((".cmd", ".bat")):
+        shell = find_executable(os.environ.get("ComSpec") or "") or find_executable("cmd")
+        if shell is None:
+            return None
+        return [shell, "/c", resolved, *rest]
+    return [resolved, *rest]

bugpilot/core/artifact_io.py

@@ -0,0 +1,40 @@
+"""Writes into `.ai/<work item>/` that another process may be reading."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from .safe_paths import refuse_link
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write via a temp file and one rename, so a reader never sees half a file.
+
+    The retry is for Windows: ``os.replace`` onto a path another process has open
+    fails with ``PermissionError`` there, and the readers of these files are
+    exactly that — an extension restoring its checklist, an MCP ``get_status``
+    call. Those reads last microseconds, so a couple of retries clear it.
+
+    If it still fails, write in place rather than raising: a torn read costs one
+    stale checklist, while a raised exception costs the whole step.
+
+    A target that is itself a symbolic link or junction is refused before
+    anything is written: the fallback below would follow it.
+    """
+    refuse_link(path)
+    temp = path.with_name(path.name + f".tmp{os.getpid()}")
+    temp.write_text(text, encoding="utf-8")
+    for attempt in range(4):
+        try:
+            os.replace(temp, path)
+            return
+        except PermissionError:
+            if attempt == 3:
+                break
+            time.sleep(0.05)
+    try:
+        path.write_text(text, encoding="utf-8")
+    finally:
+        temp.unlink(missing_ok=True)

bugpilot/core/artifacts.py

@@ -0,0 +1,47 @@
+"""The standard BugPilot artifact contract: what a work item directory holds.
+
+One place for the names, because every reader and writer has to agree on them
+and a filename spelled out in five modules is five chances to drift.
+
+    issue.json       the normalized bug and the guidance a run was given
+    retrieval.json   search terms, relevant files and their matched lines
+    context.md       the context an agent reads first
+    task.md          the task package handed to the coding agent
+    run.json         runtime state: step lifecycle, agent state
+    fix_report.md    optional, only once a fix produced something to report
+    review_report.md optional, only once somebody recorded a review's result
+    verification_report.md
+                     optional, only once somebody recorded verification evidence
+
+Every JSON artifact carries ``schema_version``. There is deliberately no
+migration and no reader for any earlier layout: BugPilot is pre-release, and a
+work item prepared under an older layout is re-prepared rather than upgraded.
+"""
+
+from __future__ import annotations
+
+ARTIFACT_SCHEMA_VERSION = 1
+
+ISSUE_ARTIFACT = "issue.json"
+RETRIEVAL_ARTIFACT = "retrieval.json"
+CONTEXT_ARTIFACT = "context.md"
+TASK_ARTIFACT = "task.md"
+RUN_ARTIFACT = "run.json"
+FIX_REPORT_ARTIFACT = "fix_report.md"
+REVIEW_REPORT_ARTIFACT = "review_report.md"
+VERIFICATION_REPORT_ARTIFACT = "verification_report.md"
+
+
+class WorkItemNotFoundError(FileNotFoundError):
+    """The work item directory does not exist."""
+
+
+# What a normal prepare-only run leaves behind once every batch has landed.
+# The reports are not here: each exists only once something wrote it.
+CORE_ARTIFACTS: tuple[str, ...] = (
+    ISSUE_ARTIFACT,
+    RETRIEVAL_ARTIFACT,
+    CONTEXT_ARTIFACT,
+    TASK_ARTIFACT,
+    RUN_ARTIFACT,
+)

bugpilot/core/attachments.py

@@ -0,0 +1,247 @@
+"""Files a developer hands to the agent alongside the prepared package.
+
+A crash log, a screenshot of the broken dialog, a config that reproduces it —
+things that are not in the repository and not in the Jira description, and that
+often decide whether a diagnosis is right.
+
+Two rules shape this module, and both come from the same principle the rest of
+the pipeline follows: **the agent must never be told about something it cannot
+read.**
+
+ 1. An attachment that could not be copied is not listed in the task file. It
+    is reported back instead, so the developer learns it did not make it rather
+    than believing the agent saw it.
+ 2. Copying is byte-for-byte and makes no encoding assumption. A PNG is a PNG;
+    a log written by a Windows tool in cp1252 stays exactly as it was.
+
+The files land in ``.ai/<work_item>/attachments/``, inside the directory the
+agent is already pointed at, so nothing has to be given a path outside it.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from .safe_paths import refuse_link
+
+ATTACHMENTS_DIR = "attachments"
+
+# Per file. A crash dump or a video of the repro is not an attachment, it is a
+# download — and copying one into `.ai/` bloats the repository the artifacts
+# directory lives in.
+MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024
+
+# Past this it is a directory, not a set of attachments, and an agent handed
+# thirty files reads none of them properly.
+MAX_ATTACHMENTS = 10
+
+# A description says why a file matters — a sentence or two — and is not a
+# second bug description. Longer text is cut, not refused: the file is still
+# worth attaching.
+MAX_ATTACHMENT_NOTE_CHARS = 500
+
+
+@dataclass
+class AttachmentResult:
+    """What was copied, and what was not and why."""
+
+    # Names inside `attachments/`, in the order they were given.
+    copied: list[str] = field(default_factory=list)
+    # ``(what the developer asked for, why it did not make it)``.
+    skipped: list[tuple[str, str]] = field(default_factory=list)
+    # The developer's description of a copied file, by its name in
+    # `attachments/`. Only files that arrived and were described appear here.
+    notes: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def relative_paths(self) -> list[str]:
+        return [f"{ATTACHMENTS_DIR}/{name}" for name in self.copied]
+
+
+def normalize_attachment_note(text: str | None) -> str:
+    """A description as the task file carries it: one line, bounded.
+
+    One line because it sits under a heading in ``task.md``: a pasted newline
+    followed by ``##`` must not become a section of its own.
+    """
+    if not text:
+        return ""
+    return " ".join(text.split())[:MAX_ATTACHMENT_NOTE_CHARS].rstrip()
+
+
+def copy_attachments(
+    target: Path, paths: Sequence[str], descriptions: Sequence[str] | None = None
+) -> AttachmentResult:
+    """Copy each path into ``target/attachments/``.
+
+    ``descriptions`` pairs with ``paths`` by position — the Nth describes the
+    Nth file; a blank one, or none, means no description. A description follows
+    its file to the name it was copied under, and is dropped with a file that
+    did not make it.
+
+    Never raises for a bad input: a missing or oversized file costs itself and
+    nothing else, because losing a whole investigation over one unreadable
+    screenshot would be the wrong trade. The caller surfaces ``skipped``.
+    """
+    result = AttachmentResult()
+    if not paths:
+        return result
+
+    directory = target / ATTACHMENTS_DIR
+    used: set[str] = set()
+    described = list(descriptions or [])
+
+    for index, raw in enumerate(paths):
+        if len(result.copied) >= MAX_ATTACHMENTS:
+            result.skipped.append((raw, f"more than {MAX_ATTACHMENTS} attachments"))
+            continue
+
+        source = Path(raw).expanduser()
+        try:
+            if not source.is_file():
+                result.skipped.append((raw, "not a file"))
+                continue
+            size = source.stat().st_size
+        except OSError as exc:
+            result.skipped.append((raw, f"could not be read: {exc.strerror or exc}"))
+            continue
+
+        if size > MAX_ATTACHMENT_BYTES:
+            megabytes = MAX_ATTACHMENT_BYTES // (1024 * 1024)
+            result.skipped.append((raw, f"larger than {megabytes} MB"))
+            continue
+
+        name = _unique_name(source.name, used)
+        try:
+            # Never into, or through, a link: the folder and
+            # the file are checked before the copy, which would follow either.
+            refuse_link(directory)
+            directory.mkdir(parents=True, exist_ok=True)
+            refuse_link(directory)
+            # copyfile, not copy2: the metadata of the developer's original is
+            # theirs, and a copied mtime makes the artifact look older than the
+            # run that produced it.
+            shutil.copyfile(source, refuse_link(directory / name))
+        except OSError as exc:
+            result.skipped.append((raw, f"could not be copied: {exc.strerror or exc}"))
+            continue
+
+        used.add(name.lower())
+        result.copied.append(name)
+        note = normalize_attachment_note(described[index] if index < len(described) else None)
+        if note:
+            result.notes[name] = note
+
+    return result
+
+
+def merge_attachment_notes(previous: Mapping[str, str], result: AttachmentResult) -> dict[str, str]:
+    """The descriptions a work item carries after this run.
+
+    A file this run copied carries this run's description, or none — the
+    developer may have cleared it. A file from an earlier run that this one did
+    not re-copy keeps the description it had, because it is still on disk and
+    the task file still names it.
+    """
+    merged = dict(previous)
+    for name in result.copied:
+        if name in result.notes:
+            merged[name] = result.notes[name]
+        else:
+            merged.pop(name, None)
+    return merged
+
+
+def _unique_name(name: str, used: set[str]) -> str:
+    """A file name that does not collide with one already copied.
+
+    Two attachments chosen from different directories can share a basename, and
+    the second silently overwriting the first is the kind of loss nobody
+    notices until the agent quotes the wrong log. Compared case-insensitively,
+    because the artifact directory may live on Windows.
+    """
+    # `Path.name` cannot contain a separator, so this cannot escape the
+    # directory; the fallback only matters for a pathological empty name.
+    candidate = name or "attachment"
+    if candidate.lower() not in used:
+        return candidate
+
+    stem = Path(candidate).stem
+    suffix = Path(candidate).suffix
+    for index in range(2, MAX_ATTACHMENTS + 2):
+        attempt = f"{stem}-{index}{suffix}"
+        if attempt.lower() not in used:
+            return attempt
+    return f"{stem}-{len(used) + 1}{suffix}"
+
+
+def is_plain_attachment_name(name: str) -> bool:
+    """A single file name: no separator, no drive, not ``.``/``..``, nothing that leaves the folder."""
+    return (
+        bool(name)
+        and name not in {".", ".."}
+        and "/" not in name
+        and "\\" not in name
+        and ":" not in name
+        and Path(name).name == name
+    )
+
+
+def remove_attachments(target: Path, names: Sequence[str]) -> list[str]:
+    """Delete these files from ``target/attachments/``, and nothing else; return what went.
+
+    Only ever called with names BugPilot itself recorded as copied — never with
+    whatever happens to be in the folder — and each one is refused unless it is
+    a plain file name naming a regular file (or a link, which is removed and not
+    followed) directly inside that folder, and the folder is inside ``target``.
+    A name that fails any check is skipped, not "cleaned": it is not ours to
+    guess about.
+    """
+    directory = target / ATTACHMENTS_DIR
+    try:
+        if not directory.is_dir() or directory.resolve().parent != target.resolve():
+            return []
+    except OSError:
+        return []
+    removed: list[str] = []
+    for name in names:
+        if not is_plain_attachment_name(name):
+            continue
+        candidate = directory / name
+        try:
+            if candidate.is_symlink() or candidate.is_file():
+                candidate.unlink()
+                removed.append(name)
+        except OSError:
+            # Locked or already gone: the record no longer names it either way.
+            continue
+    return removed
+
+
+def listed_attachments(target: Path, recorded: Sequence[str] | None) -> list[str]:
+    """The attachments a task file names: the recorded selection, else the folder.
+
+    A work item prepared by the extension records which files it currently
+    has (``guidance.attachment_files``); then only those are named — and only
+    the ones still on disk. One prepared before the record existed, or only
+    ever by an additive CLI run, falls back to reading the folder as before.
+    """
+    if recorded is None:
+        return attachment_names(target)
+    directory = target / ATTACHMENTS_DIR
+    return [name for name in recorded if is_plain_attachment_name(name) and (directory / name).is_file()]
+
+
+def attachment_names(target: Path) -> list[str]:
+    """What is in the attachments directory now, sorted.
+
+    Read from disk rather than remembered, so a `--resume` run lists what a
+    previous run copied.
+    """
+    directory = target / ATTACHMENTS_DIR
+    if not directory.is_dir():
+        return []
+    return sorted(path.name for path in directory.iterdir() if path.is_file())