auto-code-fixer 0.3.6__py3-none-any.whl → 0.4.0__py3-none-any.whl

auto_code_fixer/cli.py

@@ -9,11 +9,14 @@ from auto_code_fixer.runner import run_code
 from auto_code_fixer.fixer import fix_code_with_gpt
 from auto_code_fixer.installer import check_and_install_missing_lib
 from auto_code_fixer.utils import (
+    changed_py_files,
     discover_all_files,
     is_in_project,
     log,
     set_verbose,
+    snapshot_py_hashes,
 )
+from auto_code_fixer.reporting import FixReport, ReportAttempt, unified_diff
 from auto_code_fixer import __version__
 
 DEFAULT_MAX_RETRIES = 8  # can be overridden via CLI
@@ -35,9 +38,15 @@ def fix_file(
     max_files_changed: int,
     context_files: int,
     approve: bool,
+    max_diff_lines: int,
+    max_file_bytes: int,
+    max_total_bytes: int,
+    post_apply_check: bool,
     fmt: str | None,
     lint: str | None,
     lint_fix: bool,
+    ruff_first: bool,
+    report: FixReport | None,
 ) -> bool:
     log(f"Processing entry file: {file_path}")
 
@@ -67,12 +76,54 @@ def fix_file(
 
     venv_python = create_venv(sandbox_root)
 
+    def _run_ruff_first_pass() -> bool:
+        """Best-effort: run ruff auto-fix + import sorting + formatting before the LLM.
+
+        Returns True if it likely made changes.
+        """
+
+        from auto_code_fixer.command_runner import run_command
+
+        before = snapshot_py_hashes(sandbox_root)
+
+        # 1) Fix lint issues (including isort rules). --select I makes import sorting run
+        # even without an explicit project config.
+        rc1, _out1, err1 = run_command(
+            "python -m ruff check . --fix --select I",
+            timeout_s=max(timeout_s, 60),
+            python_exe=venv_python,
+            cwd=sandbox_root,
+            extra_env={"PYTHONPATH": sandbox_root},
+        )
+        if rc1 != 0:
+            if "No module named" in (err1 or "") and "ruff" in (err1 or ""):
+                log("ruff not installed in sandbox venv; skipping ruff-first", "DEBUG")
+                return False
+
+        # 2) Format (ruff formatter). Ignore failures.
+        run_command(
+            "python -m ruff format .",
+            timeout_s=max(timeout_s, 60),
+            python_exe=venv_python,
+            cwd=sandbox_root,
+            extra_env={"PYTHONPATH": sandbox_root},
+        )
+
+        after = snapshot_py_hashes(sandbox_root)
+        ch = changed_py_files(before, after)
+        if ch:
+            changed_sandbox_files.update({os.path.abspath(p) for p in ch})
+            return True
+        return False
+
     def _run_optional_formatters_and_linters() -> None:
         # Best-effort formatting/linting (only if tools are installed in the sandbox venv).
         from auto_code_fixer.command_runner import run_command
 
+        before = snapshot_py_hashes(sandbox_root)
+
         if fmt == "black":
-            rc, out, err = run_command(
+            rc, _out, err = run_command(
                 "python -m black .",
                 timeout_s=max(timeout_s, 60),
                 python_exe=venv_python,
@@ -92,7 +143,7 @@ def fix_file(
             cmd = "python -m ruff check ."
             if lint_fix:
                 cmd += " --fix"
-            rc, out, err = run_command(
+            rc, _out, err = run_command(
                 cmd,
                 timeout_s=max(timeout_s, 60),
                 python_exe=venv_python,
@@ -107,11 +158,25 @@ def fix_file(
                 else:
                     log(f"ruff reported issues (rc={rc}): {err}", "DEBUG")
 
+        after = snapshot_py_hashes(sandbox_root)
+        ch = changed_py_files(before, after)
+        if ch:
+            changed_sandbox_files.update({os.path.abspath(p) for p in ch})
+
     changed_sandbox_files: set[str] = set()
 
     for attempt in range(max_retries):
         log(f"Run attempt #{attempt + 1}")
 
+        changed_before = set(changed_sandbox_files)
+
+        attempt_report: ReportAttempt | None = None
+        if report is not None:
+            attempt_report = ReportAttempt(
+                index=attempt + 1,
+                run_cmd=run_cmd or f"python {os.path.relpath(sandbox_entry, sandbox_root)}",
+            )
+
         # Ensure local modules resolve inside sandbox
         if run_cmd:
             from auto_code_fixer.command_runner import run_command
@@ -132,6 +197,11 @@ def fix_file(
                 extra_env={"PYTHONPATH": sandbox_root},
             )
 
+        if attempt_report is not None:
+            attempt_report.return_code = int(retcode)
+            attempt_report.stdout = stdout
+            attempt_report.stderr = stderr
+
         if verbose:
             if stdout:
                 log(f"STDOUT:\n{stdout}", "DEBUG")
@@ -141,6 +211,11 @@ def fix_file(
         if retcode == 0:
             log("Script executed successfully ✅")
 
+            if attempt_report is not None and report is not None:
+                delta = sorted({os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)})
+                attempt_report.changed_files = delta
+                report.attempts.append(attempt_report)
+
             # Apply sandbox changes back to project (only if we actually changed something)
             if attempt > 0 and is_in_project(file_path, project_root) and changed_sandbox_files:
                 rel_changes = [os.path.relpath(p, sandbox_root) for p in sorted(changed_sandbox_files)]
@@ -163,6 +238,8 @@ def fix_file(
                     sr = os.path.realpath(os.path.abspath(sandbox_root))
                     pr = os.path.realpath(os.path.abspath(project_root))
 
+                    backups: dict[str, str] = {}
+
                     for p in sorted(changed_sandbox_files):
                         p_real = os.path.realpath(os.path.abspath(p))
 
@@ -192,12 +269,62 @@ def fix_file(
 
                         if os.path.exists(dst_real):
                             bak = backup_file(dst_real)
+                            backups[dst_real] = bak
                             log(f"Backup created: {bak}", "DEBUG")
 
                         os.makedirs(os.path.dirname(dst_real), exist_ok=True)
+
+                        if report is not None:
+                            try:
+                                old_text = ""
+                                if os.path.exists(dst_real):
+                                    old_text = open(dst_real, encoding="utf-8").read()
+                                new_text = open(p_real, encoding="utf-8").read()
+                                rel_report = os.path.relpath(dst_real, project_root)
+                                report.files_touched = sorted(set(report.files_touched + [rel_report]))
+                                report.diffs[rel_report] = unified_diff(
+                                    old=old_text,
+                                    new=new_text,
+                                    fromfile=f"a/{rel_report}",
+                                    tofile=f"b/{rel_report}",
+                                )
+                            except Exception:
+                                pass
+
                         shutil.copy(p_real, dst_real)
                         log(f"File updated: {dst_real}")
 
+                    # Optional post-apply verification: run the same command against the real project files,
+                    # using the sandbox venv for dependencies.
+                    if post_apply_check and run_cmd and changed_sandbox_files:
+                        from auto_code_fixer.command_runner import run_command
+
+                        rc2, out2, err2 = run_command(
+                            run_cmd,
+                            timeout_s=timeout_s,
+                            python_exe=venv_python,
+                            cwd=project_root,
+                            extra_env={"PYTHONPATH": project_root},
+                        )
+                        if verbose:
+                            if out2:
+                                log(f"POST-APPLY STDOUT:\n{out2}", "DEBUG")
+                            if err2:
+                                log(f"POST-APPLY STDERR:\n{err2}", "DEBUG")
+
+                        if rc2 != 0:
+                            log(
+                                "Post-apply command failed; restoring backups (best-effort).",
+                                "ERROR",
+                            )
+                            for dst_real, bak in backups.items():
+                                try:
+                                    shutil.copy(bak, dst_real)
+                                except Exception as e:
+                                    log(f"WARN: failed to restore {dst_real} from {bak}: {e}")
+                            cleanup_sandbox()
+                            return False
+
             cleanup_sandbox()
             log(f"Fix completed in {attempt + 1} attempt(s) 🎉")
             return True
@@ -208,8 +335,55 @@ def fix_file(
         if check_and_install_missing_lib(stderr, python_exe=venv_python, project_root=sandbox_root):
             log("Missing dependency installed (venv), retrying…")
             time.sleep(1)
+            if attempt_report is not None and report is not None:
+                delta = sorted({os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)})
+                attempt_report.changed_files = delta
+                report.attempts.append(attempt_report)
             continue
 
+        # Optional: ruff-first pass before invoking the LLM.
+        if ruff_first:
+            changed = _run_ruff_first_pass()
+            if attempt_report is not None:
+                attempt_report.ruff_first_applied = bool(changed)
+
+            if changed:
+                # Re-run command after ruff fixes.
+                if run_cmd:
+                    from auto_code_fixer.command_runner import run_command
+
+                    rc_r, out_r, err_r = run_command(
+                        run_cmd,
+                        timeout_s=timeout_s,
+                        python_exe=venv_python,
+                        cwd=sandbox_root,
+                        extra_env={"PYTHONPATH": sandbox_root},
+                    )
+                else:
+                    rc_r, out_r, err_r = run_code(
+                        sandbox_entry,
+                        timeout_s=timeout_s,
+                        python_exe=venv_python,
+                        cwd=sandbox_root,
+                        extra_env={"PYTHONPATH": sandbox_root},
+                    )
+
+                if rc_r == 0:
+                    log("Ruff-first fixed the issue; continuing", "DEBUG")
+                    if attempt_report is not None and report is not None:
+                        attempt_report.return_code = int(rc_r)
+                        attempt_report.stdout = out_r
+                        attempt_report.stderr = err_r
+                        delta = sorted({os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)})
+                        attempt_report.changed_files = delta
+                        report.attempts.append(attempt_report)
+                    continue
+                else:
+                    # Use the updated stderr/stdout for the LLM selection.
+                    stdout = out_r
+                    stderr = err_r
+                    retcode = rc_r
+
         # Pick the most relevant local file from the traceback (entry or imported file)
         from auto_code_fixer.traceback_utils import pick_relevant_file
 
@@ -244,6 +418,12 @@ def fix_file(
         except Exception:
             pass
 
+        if attempt_report is not None:
+            try:
+                attempt_report.selected_file = os.path.relpath(target_file, sandbox_root)
+            except Exception:
+                attempt_report.selected_file = target_file
+
         log(f"Sending {os.path.relpath(target_file, sandbox_root)} + error to GPT 🧠", "DEBUG")
 
         applied_any = False
@@ -302,7 +482,14 @@ def fix_file(
                 # Prepare diffs / approvals and apply atomically.
                 sha_by_rel = {pf.path: pf.sha256 for pf in patch_files}
 
-                planned: list[tuple[str, str, str, str]] = []  # (abs_path, rel, old, new)
+                from auto_code_fixer.approval import (
+                    PlannedChange,
+                    UserAbort,
+                    guard_planned_changes,
+                    prompt_approve_file_by_file,
+                )
+
+                planned: list[PlannedChange] = []
                 for abs_path, new_content in resolved:
                     old = ""
                     if os.path.exists(abs_path):
@@ -310,7 +497,14 @@ def fix_file(
                     if new_content.strip() == (old or "").strip():
                         continue
                     rel = os.path.relpath(abs_path, sandbox_root)
-                    planned.append((abs_path, rel, old, new_content))
+                    planned.append(
+                        PlannedChange(
+                            abs_path=abs_path,
+                            rel_path=rel,
+                            old_content=old,
+                            new_content=new_content,
+                        )
+                    )
 
                 if planned:
                     if len(planned) > max_files_changed:
@@ -318,32 +512,28 @@ def fix_file(
                             f"Patch would change {len(planned)} files, exceeding --max-files-changed={max_files_changed}"
                         )
 
-                    if approve:
-                        print("\nPROPOSED CHANGES (patch protocol):")
-                        for _, rel, old, new in planned:
-                            diff = "".join(
-                                difflib.unified_diff(
-                                    (old or "").splitlines(keepends=True),
-                                    (new or "").splitlines(keepends=True),
-                                    fromfile=rel + " (before)",
-                                    tofile=rel + " (after)",
-                                )
-                            )
-                            print(diff)
+                    guard_planned_changes(
+                        planned,
+                        max_file_bytes=max_file_bytes,
+                        max_total_bytes=max_total_bytes,
+                        max_diff_lines=max_diff_lines,
+                    )
 
-                        confirm = input("Apply these changes in the sandbox? (y/n): ").strip().lower()
-                        if confirm != "y":
-                            log("User declined patch application", "WARN")
+                    if approve:
+                        try:
+                            planned = prompt_approve_file_by_file(planned)
+                        except UserAbort:
+                            log("User aborted patch application", "WARN")
                             planned = []
 
-                for abs_path, rel, old, new_content in planned:
-                    expected_sha = sha_by_rel.get(rel)
+                for ch in planned:
+                    expected_sha = sha_by_rel.get(ch.rel_path)
                     if not expected_sha:
                         # Shouldn't happen; keep safe.
-                        raise ValueError(f"Missing sha256 for {rel} in patch protocol payload")
+                        raise ValueError(f"Missing sha256 for {ch.rel_path} in patch protocol payload")
 
-                    atomic_write_verified_sha256(abs_path, new_content, expected_sha)
-                    changed_sandbox_files.add(os.path.abspath(abs_path))
+                    atomic_write_verified_sha256(ch.abs_path, ch.new_content, expected_sha)
+                    changed_sandbox_files.add(os.path.abspath(ch.abs_path))
                     applied_any = True
 
             except Exception as e:
@@ -361,29 +551,48 @@ def fix_file(
                 log("GPT returned no changes. Stopping.", "WARN")
                 break
 
-            if approve:
-                import difflib
+            from auto_code_fixer.approval import (
+                PlannedChange,
+                UserAbort,
+                guard_planned_changes,
+                prompt_approve_file_by_file,
+            )
 
-                old = open(target_file, encoding="utf-8").read()
-                diff = "".join(
-                    difflib.unified_diff(
-                        (old or "").splitlines(keepends=True),
-                        (fixed_code or "").splitlines(keepends=True),
-                        fromfile=os.path.relpath(target_file, sandbox_root) + " (before)",
-                        tofile=os.path.relpath(target_file, sandbox_root) + " (after)",
-                    )
+            old = open(target_file, encoding="utf-8").read()
+            rel = os.path.relpath(target_file, sandbox_root)
+
+            planned = [
+                PlannedChange(
+                    abs_path=target_file,
+                    rel_path=rel,
+                    old_content=old,
+                    new_content=fixed_code,
                 )
-                print("\nPROPOSED CHANGES (legacy mode):")
-                print(diff)
-                confirm = input("Apply this change in the sandbox? (y/n): ").strip().lower()
-                if confirm != "y":
+            ]
+
+            guard_planned_changes(
+                planned,
+                max_file_bytes=max_file_bytes,
+                max_total_bytes=max_total_bytes,
+                max_diff_lines=max_diff_lines,
+            )
+
+            if approve:
+                try:
+                    planned = prompt_approve_file_by_file(planned)
+                except UserAbort:
                     log("User declined patch application", "WARN")
                     cleanup_sandbox()
                     return False
 
+            if not planned:
+                log("No legacy changes approved", "WARN")
+                cleanup_sandbox()
+                return False
+
             from auto_code_fixer.patcher import safe_write
 
-            safe_write(target_file, fixed_code)
+            safe_write(target_file, planned[0].new_content)
             changed_sandbox_files.add(os.path.abspath(target_file))
             applied_any = True
 
@@ -392,11 +601,379 @@ def fix_file(
             log("Code updated by GPT ✏️")
             time.sleep(1)
 
+        if attempt_report is not None and report is not None:
+            delta = sorted({os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)})
+            attempt_report.changed_files = delta
+            report.attempts.append(attempt_report)
+
     log("Failed to auto-fix file after max retries ❌", "ERROR")
     cleanup_sandbox()
     return False
 
 
+def fixpack(
+    target_path: str,
+    project_root: str,
+    api_key: str | None,
+    ask: bool,
+    verbose: bool,
+    *,
+    dry_run: bool,
+    model: str | None,
+    timeout_s: int,
+    max_retries: int,
+    run_cmd: str | None,
+    patch_protocol: bool,
+    max_files_changed: int,
+    context_files: int,
+    approve: bool,
+    max_diff_lines: int,
+    max_file_bytes: int,
+    max_total_bytes: int,
+    post_apply_check: bool,
+    ruff_first: bool,
+    report: FixReport | None,
+) -> bool:
+    """Run a command (pytest by default) in a full-project sandbox and iteratively fix failures."""
+
+    from auto_code_fixer.sandbox import make_sandbox_project
+    from auto_code_fixer.venv_manager import create_venv
+
+    project_root = os.path.abspath(project_root)
+    target_path = os.path.abspath(target_path)
+
+    sandbox_root = make_sandbox_project(project_root=project_root)
+    if report is not None:
+        report.sandbox_root = sandbox_root
+
+    import atexit
+
+    def cleanup_sandbox() -> None:
+        try:
+            shutil.rmtree(sandbox_root)
+        except FileNotFoundError:
+            return
+        except Exception as e:
+            log(f"WARN: failed to delete sandbox dir {sandbox_root}: {e}")
+
+    atexit.register(cleanup_sandbox)
+
+    venv_python = create_venv(sandbox_root)
+    changed_sandbox_files: set[str] = set()
+
+    from auto_code_fixer.command_runner import run_command
+
+    effective_cmd = run_cmd or "pytest -q"
+
+    for attempt in range(max_retries):
+        log(f"Fixpack attempt #{attempt + 1}: running `{effective_cmd}`")
+
+        changed_before = set(changed_sandbox_files)
+
+        attempt_report: ReportAttempt | None = None
+        if report is not None:
+            attempt_report = ReportAttempt(index=attempt + 1, run_cmd=effective_cmd)
+
+        rc, out, err = run_command(
+            effective_cmd,
+            timeout_s=timeout_s,
+            python_exe=venv_python,
+            cwd=sandbox_root,
+            extra_env={"PYTHONPATH": sandbox_root},
+        )
+
+        combined = (out or "") + "\n" + (err or "")
+
+        if attempt_report is not None:
+            attempt_report.return_code = int(rc)
+            attempt_report.stdout = out
+            attempt_report.stderr = err
+
+        if verbose:
+            if out:
+                log(f"STDOUT:\n{out}", "DEBUG")
+            if err:
+                log(f"STDERR:\n{err}", "DEBUG")
+
+        if rc == 0:
+            log("Fixpack command succeeded ✅")
+
+            if attempt_report is not None and report is not None:
+                attempt_report.changed_files = sorted(
+                    {os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)}
+                )
+                report.attempts.append(attempt_report)
+
+            # Apply all changed sandbox files back to the real project.
+            if changed_sandbox_files:
+                rel_changes = [os.path.relpath(p, sandbox_root) for p in sorted(changed_sandbox_files)]
+
+                if ask:
+                    confirm = input(
+                        "Overwrite original files with fixed versions?\n"
+                        + "\n".join(f"- {c}" for c in rel_changes)
+                        + "\n(y/n): "
+                    ).strip().lower()
+                    if confirm != "y":
+                        log("User declined overwrite", "WARN")
+                        cleanup_sandbox()
+                        return False
+
+                if dry_run:
+                    log("DRY RUN: would apply fixes:\n" + "\n".join(rel_changes), "WARN")
+                else:
+                    # Compute diffs for report before copying.
+                    for p in sorted(changed_sandbox_files):
+                        rel = os.path.relpath(p, sandbox_root)
+                        dst = os.path.join(project_root, rel)
+                        if report is not None:
+                            try:
+                                old_text = ""
+                                if os.path.exists(dst):
+                                    old_text = open(dst, encoding="utf-8").read()
+                                new_text = open(p, encoding="utf-8").read()
+                                report.files_touched = sorted(set(report.files_touched + [rel]))
+                                report.diffs[rel] = unified_diff(
+                                    old=old_text,
+                                    new=new_text,
+                                    fromfile=f"a/{rel}",
+                                    tofile=f"b/{rel}",
+                                )
+                            except Exception:
+                                pass
+
+                        os.makedirs(os.path.dirname(dst), exist_ok=True)
+                        shutil.copy(p, dst)
+                        log(f"File updated: {dst}")
+
+                    if post_apply_check:
+                        rc2, out2, err2 = run_command(
+                            effective_cmd,
+                            timeout_s=timeout_s,
+                            python_exe=venv_python,
+                            cwd=project_root,
+                            extra_env={"PYTHONPATH": project_root},
+                        )
+                        if verbose:
+                            if out2:
+                                log(f"POST-APPLY STDOUT:\n{out2}", "DEBUG")
+                            if err2:
+                                log(f"POST-APPLY STDERR:\n{err2}", "DEBUG")
+                        if rc2 != 0:
+                            log("Post-apply command failed", "ERROR")
+                            cleanup_sandbox()
+                            return False
+
+            cleanup_sandbox()
+            return True
+
+        log("Fixpack command failed ❌", "ERROR")
+        print(combined)
+
+        if check_and_install_missing_lib(combined, python_exe=venv_python, project_root=sandbox_root):
+            log("Missing dependency installed (venv), retrying…")
+            time.sleep(1)
+            if attempt_report is not None and report is not None:
+                attempt_report.changed_files = sorted(
+                    {os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)}
+                )
+                report.attempts.append(attempt_report)
+            continue
+
+        if ruff_first:
+            before = snapshot_py_hashes(sandbox_root)
+            rc_r1, _o1, _e1 = run_command(
+                "python -m ruff check . --fix --select I",
+                timeout_s=max(timeout_s, 60),
+                python_exe=venv_python,
+                cwd=sandbox_root,
+                extra_env={"PYTHONPATH": sandbox_root},
+            )
+            run_command(
+                "python -m ruff format .",
+                timeout_s=max(timeout_s, 60),
+                python_exe=venv_python,
+                cwd=sandbox_root,
+                extra_env={"PYTHONPATH": sandbox_root},
+            )
+            after = snapshot_py_hashes(sandbox_root)
+            ch = changed_py_files(before, after)
+            if ch:
+                changed_sandbox_files.update(ch)
+                if attempt_report is not None:
+                    attempt_report.ruff_first_applied = True
+
+                # Re-run after ruff
+                rc3, out3, err3 = run_command(
+                    effective_cmd,
+                    timeout_s=timeout_s,
+                    python_exe=venv_python,
+                    cwd=sandbox_root,
+                    extra_env={"PYTHONPATH": sandbox_root},
+                )
+                if rc3 == 0:
+                    if attempt_report is not None:
+                        attempt_report.return_code = int(rc3)
+                        attempt_report.stdout = out3
+                        attempt_report.stderr = err3
+                    if attempt_report is not None and report is not None:
+                        attempt_report.changed_files = sorted(
+                            {os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)}
+                        )
+                        report.attempts.append(attempt_report)
+                    continue
+                combined = (out3 or "") + "\n" + (err3 or "")
+
+        from auto_code_fixer.traceback_utils import pick_relevant_file
+
+        target_file = pick_relevant_file(combined, sandbox_root=sandbox_root)
+        if not target_file:
+            log("Could not determine failing file from output; stopping.", "ERROR")
+            cleanup_sandbox()
+            return False
+
+        # Ensure inside sandbox
+        sr = os.path.realpath(os.path.abspath(sandbox_root))
+        tf = os.path.realpath(os.path.abspath(target_file))
+        if not (tf.startswith(sr + os.sep) or tf == sr):
+            log("Suspicious target file path outside sandbox; stopping.", "ERROR")
+            cleanup_sandbox()
+            return False
+
+        if attempt_report is not None:
+            attempt_report.selected_file = os.path.relpath(tf, sandbox_root)
+
+        applied_any = False
+
+        if patch_protocol:
+            try:
+                from auto_code_fixer.fixer import fix_code_with_gpt_patch_protocol
+                from auto_code_fixer.patch_protocol import (
+                    parse_patch_protocol_response,
+                    validate_and_resolve_patch_files,
+                )
+                from auto_code_fixer.patcher import safe_read, atomic_write_verified_sha256
+                from auto_code_fixer.utils import find_imports
+                from auto_code_fixer.approval import (
+                    PlannedChange,
+                    UserAbort,
+                    guard_planned_changes,
+                    prompt_approve_file_by_file,
+                )
+
+                hint_paths = [os.path.relpath(tf, sandbox_root)]
+
+                ctx_pairs: list[tuple[str, str]] = []
+                if context_files and context_files > 0:
+                    rels: list[str] = []
+                    for abs_p in find_imports(tf, sandbox_root):
+                        try:
+                            rels.append(os.path.relpath(abs_p, sandbox_root))
+                        except Exception:
+                            continue
+                    rels = [r for r in rels if r not in hint_paths]
+                    for rel in rels[:context_files]:
+                        abs_p = os.path.join(sandbox_root, rel)
+                        if os.path.exists(abs_p):
+                            try:
+                                ctx_pairs.append((rel, safe_read(abs_p)))
+                            except Exception:
+                                pass
+
+                raw = fix_code_with_gpt_patch_protocol(
+                    sandbox_root=sandbox_root,
+                    error_log=combined,
+                    api_key=api_key,
+                    model=model,
+                    hint_paths=hint_paths,
+                    context_files=ctx_pairs,
+                )
+
+                patch_files = parse_patch_protocol_response(raw)
+                if len(patch_files) > max_files_changed:
+                    raise ValueError(
+                        f"Patch wants to change {len(patch_files)} files, exceeding --max-files-changed={max_files_changed}"
+                    )
+
+                resolved = validate_and_resolve_patch_files(patch_files, sandbox_root=sandbox_root)
+                sha_by_rel = {pf.path: pf.sha256 for pf in patch_files}
+
+                planned: list[PlannedChange] = []
+                for abs_path, new_content in resolved:
+                    old = ""
+                    if os.path.exists(abs_path):
+                        old = safe_read(abs_path)
+                    if new_content.strip() == (old or "").strip():
+                        continue
+                    rel = os.path.relpath(abs_path, sandbox_root)
+                    planned.append(
+                        PlannedChange(
+                            abs_path=abs_path,
+                            rel_path=rel,
+                            old_content=old,
+                            new_content=new_content,
+                        )
+                    )
+
+                if planned:
+                    guard_planned_changes(
+                        planned,
+                        max_file_bytes=max_file_bytes,
+                        max_total_bytes=max_total_bytes,
+                        max_diff_lines=max_diff_lines,
+                    )
+
+                    if approve:
+                        try:
+                            planned = prompt_approve_file_by_file(planned)
+                        except UserAbort:
+                            planned = []
+
+                for chg in planned:
+                    expected_sha = sha_by_rel.get(chg.rel_path)
+                    if not expected_sha:
+                        raise ValueError(f"Missing sha256 for {chg.rel_path} in patch protocol payload")
+                    atomic_write_verified_sha256(chg.abs_path, chg.new_content, expected_sha)
+                    changed_sandbox_files.add(os.path.abspath(chg.abs_path))
+                    applied_any = True
+
+            except Exception as e:
+                log(f"Patch protocol failed ({e}); falling back to full-text mode", "WARN")
+
+        if not applied_any:
+            fixed_code = fix_code_with_gpt(
+                original_code=open(tf, encoding="utf-8").read(),
+                error_log=combined,
+                api_key=api_key,
+                model=model,
+            )
+
+            from auto_code_fixer.patcher import safe_write
+
+            if fixed_code.strip() == open(tf, encoding="utf-8").read().strip():
+                log("GPT returned no changes. Stopping.", "WARN")
+                cleanup_sandbox()
+                return False
+
+            safe_write(tf, fixed_code)
+            changed_sandbox_files.add(os.path.abspath(tf))
+            applied_any = True
+
+        if applied_any:
+            log("Code updated by GPT ✏️")
+            time.sleep(1)
+
+        if attempt_report is not None and report is not None:
+            attempt_report.changed_files = sorted(
+                {os.path.relpath(p, sandbox_root) for p in (set(changed_sandbox_files) - changed_before)}
+            )
+            report.attempts.append(attempt_report)
+
+    log("Failed to fixpack after max retries ❌", "ERROR")
+    cleanup_sandbox()
+    return False
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Auto-fix Python code using OpenAI (advanced sandbox + retry loop)"
@@ -411,7 +988,7 @@ def main():
     parser.add_argument(
         "entry_file",
         nargs="?",
-        help="Path to the main Python file",
+        help="Path to the main Python file (or folder/package path if --fixpack)",
     )
 
     parser.add_argument("--project-root", default=".")
@@ -428,6 +1005,35 @@ def main():
             "If set, it runs inside the sandbox venv."
         ),
     )
+
+    parser.add_argument(
+        "--fixpack",
+        action="store_true",
+        help=(
+            "Fixpack mode: treat entry_file as a folder/package path, create a full-project sandbox, "
+            "run a command (default: pytest -q), and iteratively fix failing files until green or budget."
+        ),
+    )
+
+    parser.add_argument(
+        "--ruff-first",
+        action="store_true",
+        help=(
+            "Before calling the LLM, try best-effort Ruff auto-fixes (including import sorting) and Ruff formatting."
+        ),
+    )
+
+    parser.add_argument(
+        "--explain",
+        action="store_true",
+        help="Write a JSON report (report.json by default) with attempts, diffs, and final status.",
+    )
+
+    parser.add_argument(
+        "--report",
+        default=None,
+        help="Path to write the JSON report (implies --explain). Default: ./report.json",
+    )
     parser.add_argument(
         "--ai-plan",
         action="store_true",
@@ -463,7 +1069,44 @@ def main():
     parser.add_argument(
         "--approve",
         action="store_true",
-        help="Show diffs for proposed changes and ask for approval before applying them in the sandbox",
+        help=(
+            "Show diffs for proposed changes and ask for approval before applying them in the sandbox. "
+            "In patch-protocol mode, approvals are file-by-file."
+        ),
+    )
+
+    parser.add_argument(
+        "--max-diff-lines",
+        type=int,
+        default=4000,
+        help="Safety guard: maximum unified-diff lines to display/apply per file (default: 4000)",
+    )
+    parser.add_argument(
+        "--max-file-bytes",
+        type=int,
+        default=200_000,
+        help="Safety guard: maximum size (bytes) of proposed new content per file (default: 200000)",
+    )
+    parser.add_argument(
+        "--max-total-bytes",
+        type=int,
+        default=1_000_000,
+        help="Safety guard: maximum total bytes of proposed new content across all files (default: 1000000)",
+    )
+
+    post_apply_group = parser.add_mutually_exclusive_group()
+    post_apply_group.add_argument(
+        "--post-apply-check",
+        action="store_true",
+        help=(
+            "If using --run, re-run the command against the real project files after applying fixes "
+            "(uses sandbox venv for deps)."
+        ),
+    )
+    post_apply_group.add_argument(
+        "--no-post-apply-check",
+        action="store_true",
+        help="Disable the post-apply re-run check (even if --run is set).",
     )
 
     parser.add_argument(
@@ -527,25 +1170,82 @@ def main():
     if args.ai_plan:
         os.environ["AUTO_CODE_FIXER_AI_PLAN"] = "1"
 
-    ok = fix_file(
-        args.entry_file,
-        args.project_root,
-        args.api_key,
-        ask,
-        verbose,
-        dry_run=args.dry_run,
-        model=args.model,
-        timeout_s=args.timeout,
-        max_retries=args.max_retries,
-        run_cmd=args.run,
-        patch_protocol=not args.legacy_mode,
-        max_files_changed=args.max_files_changed,
-        context_files=args.context_files,
-        approve=args.approve,
-        fmt=args.format,
-        lint=args.lint,
-        lint_fix=args.fix,
-    )
+    if args.no_post_apply_check:
+        post_apply_check = False
+    elif args.post_apply_check:
+        post_apply_check = True
+    else:
+        post_apply_check = bool(args.run)
+
+    report_path = args.report or ("report.json" if args.explain else None)
+    report: FixReport | None = None
+    if report_path is not None:
+        report = FixReport(
+            version=__version__,
+            mode="fixpack" if args.fixpack else "file",
+            project_root=os.path.abspath(args.project_root),
+            target=os.path.abspath(args.entry_file),
+            run_cmd=args.run or ("pytest -q" if args.fixpack else None),
+        )
+
+    try:
+        if args.fixpack:
+            ok = fixpack(
+                args.entry_file,
+                args.project_root,
+                args.api_key,
+                ask,
+                verbose,
+                dry_run=args.dry_run,
+                model=args.model,
+                timeout_s=args.timeout,
+                max_retries=args.max_retries,
+                run_cmd=args.run,
+                patch_protocol=not args.legacy_mode,
+                max_files_changed=args.max_files_changed,
+                context_files=args.context_files,
+                approve=args.approve,
+                max_diff_lines=args.max_diff_lines,
+                max_file_bytes=args.max_file_bytes,
+                max_total_bytes=args.max_total_bytes,
+                post_apply_check=post_apply_check,
+                ruff_first=args.ruff_first,
+                report=report,
+            )
+        else:
+            ok = fix_file(
+                args.entry_file,
+                args.project_root,
+                args.api_key,
+                ask,
+                verbose,
+                dry_run=args.dry_run,
+                model=args.model,
+                timeout_s=args.timeout,
+                max_retries=args.max_retries,
+                run_cmd=args.run,
+                patch_protocol=not args.legacy_mode,
+                max_files_changed=args.max_files_changed,
+                context_files=args.context_files,
+                approve=args.approve,
+                max_diff_lines=args.max_diff_lines,
+                max_file_bytes=args.max_file_bytes,
+                max_total_bytes=args.max_total_bytes,
+                post_apply_check=post_apply_check,
+                fmt=args.format,
+                lint=args.lint,
+                lint_fix=args.fix,
+                ruff_first=args.ruff_first,
+                report=report,
+            )
+    finally:
+        if report is not None and report_path is not None:
+            import datetime as _dt
+
+            report.finished_at = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+            report.ok = bool(locals().get("ok", False))
+            report.write_json(report_path)
+            log(f"Wrote report: {os.path.abspath(report_path)}", "DEBUG")
 
     raise SystemExit(0 if ok else 2)