patch-cc 0.1.0__py3-none-any.whl

patch_cc/bun/macho.py

@@ -0,0 +1,124 @@
+"""Mach-O ``__BUN,__bun`` handling for macOS, via LIEF.
+
+Unlike ELF, we use LIEF to write here. Mach-O segment growth means shifting
+``__LINKEDIT`` and fixing every load command that references it -- LIEF does
+that correctly, and it has no pathological relocation behaviour on Mach-O
+(growth is page-aligned and bounded, so there is no size blow-up).
+
+Any edit invalidates the code signature, and on Apple Silicon an unsigned or
+stale-signature binary is killed on launch rather than merely warned about. So
+the signature is removed before writing and an ad-hoc one is applied after.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from .errors import BunError
+
+SEGMENT = "__BUN"
+SECTION = "__bun"
+
+
+class MachOError(BunError):
+    """The Mach-O could not be read or rewritten."""
+
+
+def _lief():
+    try:
+        import lief  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - platform dependent
+        raise MachOError(
+            "LIEF is required to patch macOS binaries. Install it with "
+            "`uv tool install patch-cc` or `pip install lief`."
+        ) from exc
+    lief.logging.disable()
+    return lief
+
+
+def _binary(path: str):
+    lief = _lief()
+    fat = lief.MachO.parse(path)
+    if fat is None:
+        raise MachOError(f"not a Mach-O binary: {path}")
+    # `parse` returns a FatBinary; Claude ships thin per-arch binaries.
+    binary = fat.at(0) if hasattr(fat, "at") else fat
+    if binary is None:
+        raise MachOError(f"no Mach-O slice found in {path}")
+    return lief, binary
+
+
+def read_section(path: str) -> bytes:
+    _lief_mod, binary = _binary(path)
+    segment = binary.get_segment(SEGMENT)
+    if segment is None:
+        raise MachOError(f"no {SEGMENT} segment -- not a Bun standalone binary")
+    section = segment.get_section(SECTION)
+    if section is None:
+        raise MachOError(f"no {SEGMENT},{SECTION} section")
+    return bytes(section.content)
+
+
+def _page_size(lief, binary) -> int:
+    try:
+        return (
+            16384
+            if binary.header.cpu_type == lief.MachO.Header.CPU_TYPE.ARM64
+            else 4096
+        )
+    except AttributeError:  # pragma: no cover - LIEF API drift
+        return 16384
+
+
+def write_section(path: str, payload: bytes, out_path: str | None = None) -> None:
+    """Replace ``__BUN,__bun`` with ``payload`` and re-sign ad-hoc."""
+    out_path = out_path or path
+    lief, binary = _binary(path)
+
+    if binary.has_code_signature:
+        binary.remove_signature()
+
+    segment = binary.get_segment(SEGMENT)
+    if segment is None:
+        raise MachOError(f"no {SEGMENT} segment")
+    section = segment.get_section(SECTION)
+    if section is None:
+        raise MachOError(f"no {SEGMENT},{SECTION} section")
+
+    grow = len(payload) - int(section.size)
+    if grow > 0:
+        page = _page_size(lief, binary)
+        aligned = -(-grow // page) * page
+        if not binary.extend_segment(segment, aligned):
+            raise MachOError(f"failed to extend {SEGMENT} by {aligned} bytes")
+
+    section.content = list(payload)
+    section.size = len(payload)
+    binary.write(out_path)
+    codesign(out_path)
+
+
+def codesign(path: str) -> None:
+    """Apply an ad-hoc signature. Required for the binary to run on arm64."""
+    if not shutil.which("codesign"):  # pragma: no cover - macOS only
+        raise MachOError("`codesign` not found; cannot sign the patched binary")
+    result = subprocess.run(
+        ["codesign", "--sign", "-", "--force", path],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:  # pragma: no cover - macOS only
+        raise MachOError(f"codesign failed: {result.stderr.strip()}")
+
+
+def verify_signature(path: str) -> bool:  # pragma: no cover - macOS only
+    if not shutil.which("codesign"):
+        return False
+    return (
+        subprocess.run(
+            ["codesign", "--verify", "--verbose=2", path],
+            capture_output=True,
+        ).returncode
+        == 0
+    )

patch_cc/cache.py

@@ -0,0 +1,86 @@
+"""Remembered interactive selection.
+
+The menu's only memory: the patches and customisations picked last time, so the
+next interactive run comes up pre-filled even after a Claude auto-update wiped
+the patched binary (and its manifest) away. It is never read by the ``apply``
+args path and never applies anything on its own -- deleting the file simply
+resets the menu to defaults.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .patches import DEFAULT_BRAND, DEFAULT_SUFFIX, Options, default_ids, ids
+
+
+def cache_path() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "patch-cc" / "selection.json"
+
+
+@dataclass(slots=True)
+class Selection:
+    patches: list[str] = field(default_factory=default_ids)
+    options: Options = field(default_factory=Options)
+
+
+def load() -> Selection:
+    """The last selection, or a fresh default set when none is cached or the
+    file is unreadable -- the menu always gets a usable, pre-checkable set.
+
+    Only shapes are validated here (strings in the right places); whether an
+    agent or model still exists is the menu's question, answered against the
+    binary it is about to patch.
+    """
+    try:
+        data = json.loads(cache_path().read_text("utf8"))
+        known = set(ids())
+        brand = data.get("brand", DEFAULT_BRAND)
+        suffix = data.get("suffix", DEFAULT_SUFFIX)
+        models = data.get("subagent_models", {})
+        return Selection(
+            patches=[p for p in data.get("patches", default_ids()) if p in known],
+            options=Options(
+                brand=brand if isinstance(brand, str) and brand else DEFAULT_BRAND,
+                version_suffix=suffix
+                if isinstance(suffix, str) and suffix
+                else DEFAULT_SUFFIX,
+                subagent_models={
+                    a: m
+                    for a, m in models.items()
+                    if isinstance(a, str) and isinstance(m, str)
+                },
+            ),
+        )
+    except (OSError, json.JSONDecodeError, AttributeError, TypeError, ValueError):
+        return Selection()
+
+
+def save(selection: Selection) -> None:
+    """Best-effort: a cache that cannot be written just means no pre-fill next
+    run -- it must never break the patch it was only trying to remember."""
+    try:
+        path = cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(
+            json.dumps(
+                {
+                    "patches": selection.patches,
+                    "brand": selection.options.brand,
+                    "suffix": selection.options.version_suffix,
+                    "subagent_models": selection.options.subagent_models,
+                },
+                indent=2,
+            )
+            + "\n",
+            "utf8",
+        )
+        tmp.replace(path)
+    except OSError:
+        pass

patch_cc/cli.py

@@ -0,0 +1,399 @@
+"""Command-line entry point.
+
+Bare ``patch-cc`` opens the interactive menu. Every action is also a
+subcommand so nothing needs the TUI:
+
+    patch-cc apply [PATCH ...] [--brand [NAME]] [--model AGENT=MODEL]
+                   [--suffix TEXT]
+    patch-cc status
+    patch-cc doctor
+    patch-cc list
+    patch-cc restore
+    patch-cc extract PATH        # dump the JS bundle (debugging)
+
+Patch ids are positional; nothing selected means the default set. The two
+configurable patches ride on their option: ``--brand`` selects branding,
+``--model`` selects subagent-models. Agents and models are validated against
+what the installed binary itself offers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import locate, patcher
+from .bun import BunError
+from .patches import Options, by_group, default_ids, derived_brand, ids
+from .patches.agents import INHERIT, discover_agents, discover_models
+from .ui import console, err, heading, ok, warn
+
+#: ``--brand`` with no value: derive the name from the system username.
+_DERIVE = ""
+
+
+def _parse_models(specs: list[str], source: str) -> dict[str, str]:
+    """Validate ``AGENT=MODEL`` pairs against what this bundle offers."""
+    agents = {a.name: a for a in discover_agents(source)}
+    models = [INHERIT, *discover_models(source)]
+    overrides: dict[str, str] = {}
+    for spec in specs:
+        agent, sep, model = spec.partition("=")
+        if not sep or agent not in agents or model not in models:
+            err(f"--model expects AGENT=MODEL, got {spec!r}")
+            console.print(
+                f"  [dim]agents in this binary: {', '.join(sorted(agents))}[/dim]"
+            )
+            console.print(f"  [dim]models in this binary: {', '.join(models)}[/dim]")
+            raise SystemExit(2)
+        overrides[agent] = model
+    return overrides
+
+
+def _requested(args, source: str) -> tuple[list[str], Options]:
+    """Build the patch set and options purely from CLI args -- no saved state.
+
+    Non-interactive patching is deliberately stateless: what you pass is
+    exactly what you get, the default set when you pass nothing.
+    """
+    selected = list(args.patches) if args.patches else default_ids()
+    unknown = [p for p in selected if p not in ids()]
+    if unknown:
+        err(f"unknown patch id(s): {', '.join(unknown)}")
+        console.print(f"  [dim]valid ids: {', '.join(ids())}[/dim]")
+        raise SystemExit(2)
+
+    options = Options()
+    if args.brand is not None:
+        options.brand = args.brand.strip() or derived_brand()
+        if "branding" not in selected:
+            selected.append("branding")
+    elif "branding" in selected:
+        options.brand = derived_brand()
+
+    if args.suffix:
+        options.version_suffix = args.suffix
+        if "version-marker" not in selected:
+            selected.append("version-marker")
+
+    if args.model:
+        options.subagent_models = _parse_models(args.model, source)
+        if "subagent-models" not in selected:
+            selected.append("subagent-models")
+    elif "subagent-models" in selected:
+        err("subagent-models needs at least one --model AGENT=MODEL")
+        agents = discover_agents(source)
+        if agents:
+            console.print(
+                f"  [dim]agents in this binary: "
+                f"{', '.join(sorted(a.name for a in agents))}[/dim]"
+            )
+        raise SystemExit(2)
+
+    return selected, options
+
+
+def _print_report(report: patcher.PatchReport) -> None:
+    heading("Patch results")
+    for patch, outcome in report.results:
+        missed = outcome.missed_steps()
+        if outcome.landed and not missed:
+            mark = "[green]✓[/green]"
+        elif outcome.landed:
+            mark = "[yellow]~[/yellow]"
+        else:
+            mark = "[red]✗[/red]"
+        detail = f"  applied {outcome.applied}" if outcome.applied else ""
+        console.print(f"  {mark} {patch.title:28s}{detail}")
+        for name in missed:
+            console.print(
+                f"      [yellow]· sub-step matched but not applied:[/yellow] {name}"
+            )
+        for note in outcome.notes:
+            console.print(f"      [dim]· {note}[/dim]")
+
+    if report.output is None:
+        console.print()
+        err("No patch changed anything; the binary was left untouched.")
+        console.print("  [dim]Run `patch-cc doctor` for anchor details.[/dim]")
+        return
+
+    saved = report.original_size - report.patched_size
+    size_note = (
+        f"{abs(saved) / 1e6:.0f} MB smaller than original"
+        if saved > 0
+        else f"{abs(saved) / 1e6:.0f} MB larger than original"
+        if saved < 0
+        else "same size as original"
+    )
+    console.print()
+    ok(f"Wrote {report.output}  ({report.patched_size / 1e6:.0f} MB, {size_note})")
+    if report.backup:
+        console.print(f"  [dim]backup: {report.backup}[/dim]")
+    if report.regressions:
+        warn(
+            f"{len(report.regressions)} patch(es) matched nothing: "
+            + ", ".join(p.id for p in report.regressions)
+        )
+        console.print("  [dim]Run `patch-cc doctor` for anchor details.[/dim]")
+
+
+def cmd_apply(args) -> int:
+    install = locate.find_or_raise()
+    bundle = patcher.read_pristine(install)
+    selected, options = _requested(args, bundle.source)
+
+    heading(f"Patching Claude {install.version or '?'} ({install.binary.name})")
+    try:
+        report = patcher.patch_installation(install, selected, options, bundle=bundle)
+    except patcher.AlreadyPatchedError as exc:
+        warn(str(exc))
+        return 1
+    except BunError as exc:
+        err(str(exc))
+        return 1
+
+    _print_report(report)
+    if report.output is not None:
+        console.print("\n[dim]Restart Claude Code for changes to take effect.[/dim]")
+    return 0 if report.output is not None else 1
+
+
+def cmd_status(args) -> int:
+    from . import doctor
+    from .bun import container
+
+    install = locate.find_or_raise()
+    bundle = container.read(str(install.binary))
+    st = doctor.status(bundle)
+
+    heading(f"Claude {install.version or '?'}  ({install.binary})")
+    state = "[green]patched[/green]" if st.patched else "[yellow]not patched[/yellow]"
+    console.print(f"  state:     {state}")
+    if st.manifest:
+        tool = st.manifest.get("tool", "?")
+        console.print(f"  by:        patch-cc {tool}")
+        console.print(f"  patches:   {', '.join(st.patch_ids) or '-'}")
+        if "brand" in st.manifest:
+            console.print(f"  brand:     {st.manifest['brand']}")
+        if "suffix" in st.manifest:
+            console.print(f"  suffix:    {st.manifest['suffix']}")
+        for agent, model in (st.manifest.get("models") or {}).items():
+            console.print(f"  model:     {agent} = {model}")
+    elif st.patched:
+        console.print(
+            "  [dim]patched by an older patch-cc (no manifest); "
+            "re-apply to record one[/dim]"
+        )
+    console.print(
+        f"  bytecode:  "
+        f"{'stripped' if st.bytecode_stripped else f'{st.bytecode_size / 1e6:.0f} MB present'}"
+    )
+    backup = patcher.backup_path_for(install)
+    if backup.exists():
+        console.print(f"  backup:    {backup}")
+    if install.is_symlinked:
+        console.print(f"  [dim]launcher {install.launcher} -> {install.binary}[/dim]")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    from . import doctor
+    from .bun import container
+
+    install = locate.find_or_raise()
+    installed = container.read(str(install.binary))
+
+    # Matcher health must be tested on a clean bundle. If the installed binary
+    # is already patched, our edits have removed the anchors, so fall back to
+    # the pristine backup.
+    test_bundle = installed
+    source_note = ""
+    if patcher.is_patched(installed.source):
+        clean = patcher.clean_source_path(install)
+        if clean is None:
+            warn("Installed binary is already patched and no clean backup exists.")
+            console.print(
+                "  [dim]Matcher health can't be checked against a patched binary. "
+                "Run `patch-cc restore`, or test a freshly downloaded binary.[/dim]"
+            )
+            return 1
+        test_bundle = container.read(str(clean))
+        source_note = (
+            "  [dim](installed binary is patched; testing against backup)[/dim]"
+        )
+
+    result = doctor.dryrun(test_bundle)
+
+    heading(f"Patch health against Claude {install.version or '?'}{source_note}")
+    for check in result.checks:
+        outcome = check.outcome
+        missed = outcome.missed_steps()
+        if outcome.landed and not missed:
+            mark, colour = "✓", "green"
+        elif outcome.landed:
+            mark, colour = "~", "yellow"
+        else:
+            mark, colour = "✗", "red"
+        console.print(
+            f"  [{colour}]{mark}[/{colour}] {check.patch.id:20s} "
+            f"cand={outcome.candidates} applied={outcome.applied}"
+        )
+        for name in missed:
+            sub = outcome.steps[name]
+            console.print(
+                f"      [yellow]sub-step {name} missed[/yellow] "
+                f"{'· ' + '; '.join(sub.notes) if sub.notes else ''}"
+            )
+
+    agents = (
+        ", ".join(f"{a.name}={a.effective_model}" for a in result.agents)
+        or "none found"
+    )
+    console.print(f"\n  [dim]agents:  {agents}[/dim]")
+    console.print(f"  [dim]models:  {', '.join(result.models)}[/dim]")
+
+    if result.broken:
+        console.print()
+        warn(f"{len(result.broken)} patch(es) no longer match. Anchor counts:")
+        for check in result.broken:
+            anchors = result.anchors.get(check.patch.id, {})
+            for anchor, count in anchors.items():
+                colour = "red" if count == 0 else "dim"
+                console.print(f"    [{colour}]{count:3d}[/{colour}]  {anchor}")
+        console.print(
+            "\n  [dim]A 0 next to an anchor is where upstream moved. "
+            "See docs/PLAYBOOK.md to repair.[/dim]"
+        )
+        return 1
+    ok("All patches still match this build.")
+    return 0
+
+
+def cmd_list(args) -> int:
+    heading("Available patches")
+    for group, patches in by_group().items():
+        if not patches:
+            continue
+        console.print(f"\n[bold]{group}[/bold]")
+        for patch in patches:
+            tag = "[dim](via --model)[/dim]" if not patch.default else ""
+            console.print(f"  [cyan]{patch.id:18s}[/cyan] {patch.summary} {tag}")
+
+    install = locate.find()
+    if install is None:
+        return 0
+    try:
+        source = patcher.read_pristine(install).source
+    except (BunError, OSError):
+        return 0
+    agents = discover_agents(source)
+    if agents:
+        console.print(f"\n[bold]Subagents in Claude {install.version or '?'}[/bold]")
+        for agent in agents:
+            console.print(
+                f"  [cyan]{agent.name:18s}[/cyan] default model: {agent.effective_model}"
+            )
+        console.print(
+            f"  [dim]models: {', '.join([INHERIT, *discover_models(source)])}[/dim]"
+        )
+    return 0
+
+
+def cmd_restore(args) -> int:
+    install = locate.find_or_raise()
+    try:
+        restored = patcher.restore(install)
+    except FileNotFoundError as exc:
+        err(str(exc))
+        return 1
+    ok(f"Restored {restored} from backup.")
+    console.print("[dim]Restart Claude Code for changes to take effect.[/dim]")
+    return 0
+
+
+def cmd_extract(args) -> int:
+    from .bun import container
+
+    bundle = container.read(args.path)
+    sys.stdout.buffer.write(bundle.source.encode("utf8"))
+    sys.stdout.buffer.flush()
+    return 0
+
+
+def cmd_menu(args) -> int:
+    from .menu import run_menu
+
+    return run_menu()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="patch-cc",
+        description="Interactive patcher for the Claude Code native binary.",
+    )
+    parser.set_defaults(func=cmd_menu)
+    sub = parser.add_subparsers(dest="command")
+
+    p_apply = sub.add_parser("apply", help="apply patches to the installed binary")
+    p_apply.add_argument(
+        "patches",
+        nargs="*",
+        metavar="PATCH",
+        help="patch ids to apply (default: the default set)",
+    )
+    p_apply.add_argument(
+        "--brand",
+        nargs="?",
+        const=_DERIVE,
+        metavar="NAME",
+        help="custom startup name (no value: <username>'s Code)",
+    )
+    p_apply.add_argument(
+        "--model",
+        action="append",
+        metavar="AGENT=MODEL",
+        help="override a subagent's default model (repeatable)",
+    )
+    p_apply.add_argument(
+        "--suffix", metavar="TEXT", help="--version marker text (default: (patched))"
+    )
+    p_apply.set_defaults(func=cmd_apply)
+
+    sub.add_parser(
+        "status", help="show what is applied to the installed binary"
+    ).set_defaults(func=cmd_status)
+    sub.add_parser(
+        "doctor", help="check every patch still matches this build"
+    ).set_defaults(func=cmd_doctor)
+    sub.add_parser(
+        "list", help="list patches, and the agents/models in your binary"
+    ).set_defaults(func=cmd_list)
+    sub.add_parser(
+        "restore", help="restore the original binary from backup"
+    ).set_defaults(func=cmd_restore)
+
+    p_extract = sub.add_parser(
+        "extract", help="dump the JS bundle from a binary (debug)"
+    )
+    p_extract.add_argument("path", help="path to a Claude native binary")
+    p_extract.set_defaults(func=cmd_extract)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (FileNotFoundError, BunError) as exc:
+        err(str(exc))
+        return 1
+    except KeyboardInterrupt:
+        console.print("\n[dim]cancelled[/dim]")
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())