patch-cc 0.1.0__py3-none-any.whl

patch_cc/__init__.py

@@ -0,0 +1,3 @@
+"""patch-cc: an interactive patcher for the Claude Code native binary."""
+
+__version__ = "0.1.0"

patch_cc/bun/__init__.py

@@ -0,0 +1,6 @@
+"""Bun standalone-executable container handling."""
+
+from .container import Bundle, ContainerError, read, write
+from .errors import BunError
+
+__all__ = ["Bundle", "BunError", "ContainerError", "read", "write"]

patch_cc/bun/blob.py

@@ -0,0 +1,256 @@
+"""Read and rewrite the Bun standalone-executable blob.
+
+Layout of the blob (little-endian throughout)::
+
+    [ data arena: name / contents / sourcemap / bytecode / ... payloads ]
+    [ module table: N records of `struct_size` bytes                    ]
+    [ compileExecArgv payload                                           ]
+    [ 32-byte offsets struct                                            ]
+    [ 15-byte "\\n---- Bun! ----\\n" trailer                              ]
+
+Every pointer in the blob is a ``(u32 offset, u32 length)`` pair relative to the
+start of the blob, and they live in exactly two places: the module table and the
+offsets struct. That is what makes rewriting tractable -- move a payload, then
+fix up the pointers that describe it.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from .errors import BunError
+
+TRAILER = b"\n---- Bun! ----\n"
+OFFSETS_SIZE = 32
+
+#: Module record field order. Old Bun (<1.3.7) stops after ``bytecode``.
+FIELDS_NEW = (
+    "name",
+    "contents",
+    "sourcemap",
+    "bytecode",
+    "module_info",
+    "bytecode_origin_path",
+)
+FIELDS_OLD = FIELDS_NEW[:4]
+
+#: Names Bun gives the Claude entrypoint module across platforms/versions.
+ENTRY_NAMES = ("claude", "claude.exe", "src/entrypoints/cli.js")
+
+
+class BlobError(BunError):
+    """The .bun payload did not look like a Bun module graph."""
+
+
+def is_entry_module(name: str) -> bool:
+    return any(name == n or name.endswith("/" + n) for n in ENTRY_NAMES)
+
+
+@dataclass(slots=True)
+class Module:
+    index: int
+    ranges: dict[str, tuple[int, int]]
+    trailing: bytes  # encoding, loader, module_format, side
+
+    @property
+    def name_range(self) -> tuple[int, int]:
+        return self.ranges["name"]
+
+
+@dataclass(slots=True)
+class Blob:
+    data: bytes
+    struct_size: int
+    modules: list[Module]
+    modules_ptr: tuple[int, int]
+    argv_ptr: tuple[int, int]
+    entry_point_id: int
+    flags: int
+    offsets_at: int
+
+    @property
+    def fields(self) -> tuple[str, ...]:
+        return FIELDS_NEW if self.struct_size == 52 else FIELDS_OLD
+
+    def payload(self, rng: tuple[int, int]) -> bytes:
+        off, length = rng
+        return self.data[off : off + length]
+
+    def module_name(self, module: Module) -> str:
+        return self.payload(module.name_range).decode("utf8", "replace")
+
+    def entry_module(self) -> Module:
+        for module in self.modules:
+            if is_entry_module(self.module_name(module)):
+                return module
+        raise BlobError("no Claude entrypoint module in the Bun blob")
+
+    def entry_source(self) -> bytes:
+        return self.payload(self.entry_module().ranges["contents"])
+
+    def bytecode_size(self) -> int:
+        return (
+            self.entry_module().ranges["bytecode"][1] if self.struct_size == 52 else 0
+        )
+
+
+def _detect_struct_size(modules_len: int) -> int:
+    new_ok = modules_len % 52 == 0
+    old_ok = modules_len % 36 == 0
+    if new_ok and not old_ok:
+        return 52
+    if old_ok and not new_ok:
+        return 36
+    return 52
+
+
+def parse(data: bytes) -> Blob:
+    """Parse a raw Bun blob (already unwrapped from its container section)."""
+    if len(data) < OFFSETS_SIZE + len(TRAILER):
+        raise BlobError("blob is too small to hold offsets and trailer")
+    if data[-len(TRAILER) :] != TRAILER:
+        raise BlobError("missing Bun trailer -- not a Bun standalone payload")
+
+    offsets_at = len(data) - len(TRAILER) - OFFSETS_SIZE
+    (_byte_count,) = struct.unpack_from("<Q", data, offsets_at)
+    modules_ptr = struct.unpack_from("<II", data, offsets_at + 8)
+    (entry_point_id,) = struct.unpack_from("<I", data, offsets_at + 16)
+    argv_ptr = struct.unpack_from("<II", data, offsets_at + 20)
+    (flags,) = struct.unpack_from("<I", data, offsets_at + 28)
+
+    struct_size = _detect_struct_size(modules_ptr[1])
+    fields = FIELDS_NEW if struct_size == 52 else FIELDS_OLD
+    table_off, table_len = modules_ptr
+    if table_off + table_len > len(data):
+        raise BlobError("module table runs past the end of the blob")
+
+    modules: list[Module] = []
+    for index in range(table_len // struct_size):
+        base = table_off + index * struct_size
+        ranges = {
+            field: struct.unpack_from("<II", data, base + i * 8)
+            for i, field in enumerate(fields)
+        }
+        trailing = data[base + len(fields) * 8 : base + len(fields) * 8 + 4]
+        modules.append(Module(index=index, ranges=ranges, trailing=trailing))
+
+    if not modules:
+        raise BlobError("Bun blob contains no modules")
+
+    return Blob(
+        data=data,
+        struct_size=struct_size,
+        modules=modules,
+        modules_ptr=modules_ptr,
+        argv_ptr=argv_ptr,
+        entry_point_id=entry_point_id,
+        flags=flags,
+        offsets_at=offsets_at,
+    )
+
+
+def rebuild(blob: Blob, source: bytes, *, drop_bytecode: bool = True) -> bytes:
+    """Return a new blob with the entrypoint's source replaced.
+
+    Payloads are re-emitted in their original file order so the result stays as
+    close to the input layout as possible.
+
+    ``drop_bytecode`` removes the entrypoint's precompiled Bun bytecode. Editing
+    the source invalidates that bytecode anyway -- Bun recompiles from source --
+    so keeping it costs ~154 MB for no benefit. See docs/INTERNALS.md.
+    """
+    entry = blob.entry_module()
+    fields = blob.fields
+    has_bytecode = "bytecode" in fields
+
+    # Every payload, in the order it appears in the source arena.
+    placed: list[
+        tuple[int, int, int, str]
+    ] = []  # (offset, length, module_index, field)
+    for module in blob.modules:
+        for field in fields:
+            off, length = module.ranges[field]
+            if length:
+                placed.append((off, length, module.index, field))
+    placed.sort()
+
+    out = bytearray()
+    new_ranges: dict[tuple[int, str], tuple[int, int]] = {}
+    prev_end = 0
+    for off, length, mod_index, field in placed:
+        is_entry = mod_index == entry.index
+        if is_entry and field == "bytecode" and drop_bytecode:
+            new_ranges[(mod_index, field)] = (0, 0)
+            prev_end = off + length
+            continue
+
+        payload = (
+            source
+            if (is_entry and field == "contents")
+            else blob.data[off : off + length]
+        )
+        # Preserve the 1-byte separators Bun emits between payloads.
+        if prev_end and off > prev_end:
+            out += b"\0" * (off - prev_end)
+        new_ranges[(mod_index, field)] = (len(out), len(payload))
+        out += payload
+        prev_end = off + length
+
+    out += b"\0"
+    table_off = len(out)
+    table_len = len(blob.modules) * blob.struct_size
+    out += bytearray(table_len)
+
+    argv = blob.payload(blob.argv_ptr)
+    argv_off = len(out)
+    out += argv + b"\0"
+
+    offsets_at = len(out)
+    out += bytearray(OFFSETS_SIZE)
+    out += TRAILER
+
+    for module in blob.modules:
+        base = table_off + module.index * blob.struct_size
+        for i, field in enumerate(fields):
+            off, length = new_ranges.get((module.index, field), (0, 0))
+            struct.pack_into("<II", out, base + i * 8, off, length)
+        tail = base + len(fields) * 8
+        out[tail : tail + 4] = module.trailing
+
+    struct.pack_into("<Q", out, offsets_at, offsets_at)
+    struct.pack_into("<II", out, offsets_at + 8, table_off, table_len)
+    struct.pack_into("<I", out, offsets_at + 16, blob.entry_point_id)
+    struct.pack_into("<II", out, offsets_at + 20, argv_off, len(argv))
+    struct.pack_into("<I", out, offsets_at + 28, blob.flags)
+
+    if has_bytecode and drop_bytecode:
+        assert new_ranges[(entry.index, "bytecode")] == (0, 0)
+    return bytes(out)
+
+
+def unwrap_section(section: bytes) -> tuple[bytes, int]:
+    """Strip the length prefix a container section puts in front of the blob.
+
+    Bun >=1.3.4 uses a u64 prefix; older builds use u32. Both are followed by
+    padding up to the section's alignment, hence the 4 KiB slack window.
+    """
+    size = len(section)
+    if size >= 8:
+        (as64,) = struct.unpack_from("<Q", section, 0)
+        if 8 + as64 <= size and 8 + as64 >= size - 4096:
+            return section[8 : 8 + as64], 8
+    if size >= 4:
+        (as32,) = struct.unpack_from("<I", section, 0)
+        if 4 + as32 <= size and 4 + as32 >= size - 4096:
+            return section[4 : 4 + as32], 4
+    raise BlobError("unrecognised .bun section header")
+
+
+def wrap_section(blob: bytes, header_size: int) -> bytes:
+    prefix = (
+        struct.pack("<Q", len(blob))
+        if header_size == 8
+        else struct.pack("<I", len(blob))
+    )
+    return prefix + blob

patch_cc/bun/container.py

@@ -0,0 +1,129 @@
+"""One API over the two binary containers we support: ELF and Mach-O."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from . import blob as blobmod
+from . import elf, macho
+from .errors import BunError
+
+ELF_MAGIC = b"\x7fELF"
+MACHO_MAGICS = {
+    b"\xcf\xfa\xed\xfe",
+    b"\xce\xfa\xed\xfe",  # thin, LE
+    b"\xfe\xed\xfa\xcf",
+    b"\xfe\xed\xfa\xce",  # thin, BE
+    b"\xca\xfe\xba\xbe",
+    b"\xbe\xba\xfe\xca",  # fat
+}
+
+
+class ContainerError(BunError):
+    pass
+
+
+def detect(path: str) -> str:
+    with open(path, "rb") as handle:
+        magic = handle.read(4)
+    if magic == ELF_MAGIC:
+        return "elf"
+    if magic in MACHO_MAGICS:
+        return "macho"
+    raise ContainerError(
+        f"{path} is neither ELF nor Mach-O. Claude Code must be the native "
+        "build -- reinstall with `curl -fsSL https://claude.ai/install.sh | bash`."
+    )
+
+
+@dataclass(slots=True)
+class Bundle:
+    """The JS bundle plus everything needed to put it back.
+
+    ``source`` is the decoded JS text -- patches operate on ``str``. The binary
+    layers below work in ``bytes``; this class is the encode/decode boundary.
+    """
+
+    path: str
+    kind: str
+    source: str
+    blob: blobmod.Blob
+    header_size: int
+    binary_size: int
+    bytecode_size: int
+
+
+def read(path: str) -> Bundle:
+    kind = detect(path)
+    if kind == "elf":
+        with open(path, "rb") as handle:
+            raw = handle.read()
+        section = elf.read_section(raw)
+    else:
+        section = macho.read_section(path)
+
+    payload, header_size = blobmod.unwrap_section(section)
+    parsed = blobmod.parse(payload)
+    return Bundle(
+        path=path,
+        kind=kind,
+        source=parsed.entry_source().decode("utf8"),
+        blob=parsed,
+        header_size=header_size,
+        binary_size=os.path.getsize(path),
+        bytecode_size=parsed.bytecode_size(),
+    )
+
+
+def write(
+    bundle: Bundle, source: str, out_path: str, *, drop_bytecode: bool = True
+) -> None:
+    """Repack ``source`` into a copy of the binary at ``out_path``.
+
+    The patched image is staged to a temp file and verified -- re-extracted and
+    compared against ``source`` -- *before* it is moved into place. A rebuild
+    bug therefore fails without ever touching the live binary.
+    """
+    import shutil  # noqa: PLC0415
+
+    new_blob = blobmod.rebuild(
+        bundle.blob, source.encode("utf8"), drop_bytecode=drop_bytecode
+    )
+    section = blobmod.wrap_section(new_blob, bundle.header_size)
+    tmp = f"{out_path}.patch-cc.tmp"
+
+    try:
+        if bundle.kind == "elf":
+            with open(bundle.path, "rb") as handle:
+                raw = handle.read()
+            patched = elf.write_section(raw, section)
+            with open(tmp, "wb") as handle:
+                handle.write(patched)
+            os.chmod(tmp, os.stat(bundle.path).st_mode & 0o7777)
+        else:
+            shutil.copy2(bundle.path, tmp)
+            macho.write_section(tmp, section)
+
+        verify(tmp, source)  # raises before we commit if anything is off
+        os.replace(tmp, out_path)
+    except BaseException:
+        if os.path.exists(tmp):
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+        raise
+
+
+def verify(path: str, expected: str) -> None:
+    """Re-extract from a written binary and assert it round-trips exactly."""
+    try:
+        written = read(path)
+    except Exception as exc:  # noqa: BLE001
+        raise ContainerError(f"patched binary could not be re-read: {exc}") from exc
+    if written.source != expected:
+        raise ContainerError(
+            "patched binary did not round-trip: extracted source differs from "
+            f"what we wrote ({len(written.source):,} vs {len(expected):,} bytes)"
+        )

patch_cc/bun/elf.py

@@ -0,0 +1,281 @@
+"""Raw ELF64 surgery for the ``.bun`` section.
+
+We deliberately do not use a generic ELF library to *write*. LIEF rebuilds the
+binary and relocates ``.bun`` so its file offset matches its virtual address
+(0x20000000), which inflates a 267 MB binary to 715 MB. Editing the bytes in
+place keeps ``.bun`` where it is and grows the file by only the delta.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+from dataclasses import dataclass
+
+from .errors import BunError
+
+SHT_NOBITS = 8
+SHF_ALLOC = 0x2
+PT_LOAD = 1
+
+
+class ElfError(BunError):
+    """The binary is not an ELF64 we know how to rewrite safely."""
+
+
+@dataclass(slots=True)
+class Section:
+    index: int
+    name: str
+    type: int
+    flags: int
+    addr: int
+    offset: int
+    size: int
+    align: int
+
+    @property
+    def has_file_payload(self) -> bool:
+        return self.type != SHT_NOBITS and self.size > 0
+
+    @property
+    def is_alloc(self) -> bool:
+        return bool(self.flags & SHF_ALLOC)
+
+
+@dataclass(slots=True)
+class Segment:
+    index: int
+    type: int
+    offset: int
+    vaddr: int
+    filesz: int
+    memsz: int
+    align: int
+
+
+@dataclass(slots=True)
+class Elf:
+    phoff: int
+    shoff: int
+    phentsize: int
+    phnum: int
+    shentsize: int
+    shnum: int
+    sections: list[Section]
+    segments: list[Segment]
+
+    def section(self, name: str) -> Section | None:
+        return next((s for s in self.sections if s.name == name), None)
+
+
+def parse(buf: bytes) -> Elf:
+    if len(buf) < 64 or buf[:4] != b"\x7fELF":
+        raise ElfError("not an ELF file")
+    if buf[4] != 2:
+        raise ElfError("only ELF64 is supported")
+    if buf[5] != 1:
+        raise ElfError("only little-endian ELF is supported")
+
+    phoff, shoff = struct.unpack_from("<QQ", buf, 32)
+    phentsize, phnum, shentsize, shnum, shstrndx = struct.unpack_from("<HHHHH", buf, 54)
+    if not shnum or shstrndx >= shnum:
+        raise ElfError("ELF has no usable section header table")
+
+    strbase = shoff + shstrndx * shentsize
+    stroff, strsize = struct.unpack_from("<QQ", buf, strbase + 24)
+    strtab = buf[stroff : stroff + strsize]
+
+    sections: list[Section] = []
+    for index in range(shnum):
+        base = shoff + index * shentsize
+        name_off, sh_type = struct.unpack_from("<II", buf, base)
+        flags, addr, offset, size = struct.unpack_from("<QQQQ", buf, base + 8)
+        (align,) = struct.unpack_from("<Q", buf, base + 48)
+        end = strtab.find(b"\0", name_off)
+        name = strtab[name_off : end if end != -1 else None].decode("utf8", "replace")
+        sections.append(Section(index, name, sh_type, flags, addr, offset, size, align))
+
+    segments: list[Segment] = []
+    for index in range(phnum):
+        base = phoff + index * phentsize
+        (p_type,) = struct.unpack_from("<I", buf, base)
+        offset, vaddr, _paddr, filesz, memsz = struct.unpack_from(
+            "<QQQQQ", buf, base + 8
+        )
+        (align,) = struct.unpack_from("<Q", buf, base + 48)
+        segments.append(Segment(index, p_type, offset, vaddr, filesz, memsz, align))
+
+    return Elf(phoff, shoff, phentsize, phnum, shentsize, shnum, sections, segments)
+
+
+def read_section(buf: bytes, name: str = ".bun") -> bytes:
+    elf = parse(buf)
+    section = elf.section(name)
+    if section is None:
+        raise ElfError(f"no {name} section in this ELF")
+    return buf[section.offset : section.offset + section.size]
+
+
+def _containing_load(elf: Elf, section: Section) -> Segment | None:
+    file_end = section.offset + section.size
+    virt_end = section.addr + section.size
+    for seg in elf.segments:
+        if seg.type != PT_LOAD:
+            continue
+        if (
+            seg.offset <= section.offset
+            and file_end <= seg.offset + seg.filesz
+            and seg.vaddr <= section.addr
+            and virt_end <= seg.vaddr + seg.memsz
+        ):
+            return seg
+    return None
+
+
+def _check_growth_is_safe(elf: Elf, bun: Section, shifted: list[Section]) -> None:
+    """Refuse anything that could change runtime mapping semantics."""
+    end = bun.offset + bun.size
+
+    overlapping = [
+        s
+        for s in elf.sections
+        if s.index != bun.index and s.has_file_payload and bun.offset < s.offset < end
+    ]
+    if overlapping:
+        names = ", ".join(s.name or f"<{s.index}>" for s in overlapping)
+        raise ElfError(f".bun overlaps later section payloads: {names}")
+
+    alloc = [s for s in shifted if s.is_alloc]
+    if alloc:
+        names = ", ".join(s.name or f"<{s.index}>" for s in alloc)
+        raise ElfError(f"cannot move allocated sections that follow .bun: {names}")
+
+    sh_end = elf.shoff + elf.shentsize * elf.shnum
+    if elf.shoff < end < sh_end:
+        raise ElfError("cannot resize .bun from inside the section header table")
+    ph_end = elf.phoff + elf.phentsize * elf.phnum
+    if elf.phoff < end < ph_end:
+        raise ElfError("cannot resize .bun from inside the program header table")
+
+    container = _containing_load(elf, bun)
+    spanning = [
+        seg
+        for seg in elf.segments
+        if seg.index != (container.index if container else -1)
+        and seg.filesz
+        and seg.offset < end < seg.offset + seg.filesz
+    ]
+    if spanning:
+        names = ", ".join(f"{s.index}:{s.type}" for s in spanning)
+        raise ElfError(f"cannot resize .bun inside unrelated segments: {names}")
+
+
+def _alignment_step(elf: Elf, end: int, shifted: list[Section]) -> int:
+    """Smallest shift that preserves the alignment of everything we move."""
+    step = 1
+    for section in shifted:
+        step = max(step, section.align or 1)
+    for seg in elf.segments:
+        if seg.filesz and seg.offset >= end:
+            step = max(step, seg.align or 1)
+    return step
+
+
+def write_section(buf: bytes, payload: bytes, name: str = ".bun") -> bytes:
+    """Return a new ELF image with ``name``'s contents replaced by ``payload``.
+
+    The section keeps its file offset. Everything after it shifts by a delta
+    rounded to a multiple of the strictest alignment among the moved pieces, and
+    the containing ``PT_LOAD`` grows or shrinks to match.
+    """
+    elf = parse(buf)
+    bun = elf.section(name)
+    if bun is None:
+        raise ElfError(f"no {name} section in this ELF")
+
+    start, end = bun.offset, bun.offset + bun.size
+    shifted = [
+        s
+        for s in elf.sections
+        if s.index != bun.index and s.has_file_payload and s.offset >= end
+    ]
+
+    delta = len(payload) - bun.size
+    if delta:
+        _check_growth_is_safe(elf, bun, shifted)
+        step = _alignment_step(elf, end, shifted)
+        if step > 1:
+            # Grow generously / shrink conservatively so offsets stay congruent.
+            delta = (
+                (delta + step - 1) // step * step
+                if delta > 0
+                else -((-delta) // step * step)
+            )
+
+    container = _containing_load(elf, bun)
+    if delta and container is None:
+        raise ElfError(".bun has no containing PT_LOAD segment")
+
+    for seg in elf.segments:
+        if (
+            delta
+            and seg.type == PT_LOAD
+            and seg.filesz
+            and seg.offset >= end
+            and seg.align
+        ):
+            if (seg.offset + delta) % seg.align != seg.vaddr % seg.align:
+                raise ElfError(
+                    f"shifting LOAD segment {seg.index} would break its alignment"
+                )
+
+    new_size = bun.size + delta
+    body = bytearray(payload)
+    if len(body) < new_size:
+        body += b"\0" * (new_size - len(body))
+    elif len(body) > new_size:
+        raise ElfError("internal error: payload larger than the resized section")
+
+    out = bytearray(buf[:start]) + body + bytearray(buf[end:])
+
+    new_phoff = elf.phoff + delta if elf.phoff >= end else elf.phoff
+    new_shoff = elf.shoff + delta if elf.shoff >= end else elf.shoff
+    struct.pack_into("<QQ", out, 32, new_phoff, new_shoff)
+
+    for section in elf.sections:
+        base = new_shoff + section.index * elf.shentsize
+        if section.index == bun.index:
+            struct.pack_into("<Q", out, base + 32, new_size)
+        elif delta and section.has_file_payload and section.offset >= end:
+            struct.pack_into("<Q", out, base + 24, section.offset + delta)
+
+    for seg in elf.segments:
+        base = new_phoff + seg.index * elf.phentsize
+        if delta and container is not None and seg.index == container.index:
+            struct.pack_into(
+                "<QQ", out, base + 32, seg.filesz + delta, seg.memsz + delta
+            )
+        elif delta and seg.filesz and seg.offset >= end:
+            struct.pack_into("<Q", out, base + 8, seg.offset + delta)
+
+    return bytes(out)
+
+
+def atomic_write(path: str, data: bytes, mode_from: str | None = None) -> None:
+    """Write ``data`` to ``path`` via a temp file, preserving the mode bits."""
+    tmp = f"{path}.patch-cc.tmp"
+    try:
+        with open(tmp, "wb") as handle:
+            handle.write(data)
+        source = mode_from or (path if os.path.exists(path) else None)
+        if source:
+            os.chmod(tmp, os.stat(source).st_mode & 0o7777)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+        raise

patch_cc/bun/errors.py

@@ -0,0 +1,12 @@
+"""Shared base for binary-container errors.
+
+Kept in its own module so blob/elf/macho/container can all subclass one type
+without an import cycle. The CLI catches :class:`BunError` to turn any
+container-layer failure into a clean message instead of a traceback.
+"""
+
+from __future__ import annotations
+
+
+class BunError(RuntimeError):
+    """Any failure reading or rewriting the Bun-embedded binary."""