ps5dbg 0.1.0__tar.gz

ps5dbg-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ps5dbg is licensed under the GNU General Public License v3.0.
+This matches the license of ps5debug-NG (OpenSourcereR-dev), whose
+wire protocol this library implements and to which it is wire-compatible.
+
+The full text of the GPL-3.0 is available at:
+https://www.gnu.org/licenses/gpl-3.0.txt
+
+A verbatim copy should accompany this file in distributions. If you need
+the complete license text programmatically, fetch it from the URL above.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.

ps5dbg-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: ps5dbg
+Version: 0.1.0
+Summary: Cross-platform Python client and CLI for the ps5debug-NG wire protocol on jailbroken PS5 consoles.
+Author: Darkatek7
+License: GPL-3.0-only
+Project-URL: Homepage, https://github.com/Darkatek7/ps5dbg
+Project-URL: Repository, https://github.com/Darkatek7/ps5dbg
+Project-URL: Issues, https://github.com/Darkatek7/ps5dbg/issues
+Keywords: ps5,playstation5,ps5debug,ps5debug-ng,debugger,homebrew,jailbreak
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# ps5dbg
+
+> A cross-platform Python client and CLI for the **ps5debug-NG** wire protocol on jailbroken PS5 consoles. Speak to your console from any OS — build trainers, debuggers, and tooling on a clean library instead of reimplementing the protocol.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE)
+[![Tests](https://img.shields.io/badge/tests-31%20pass%20%2B%2015%20live-brightgreen.svg)](#testing)
+[![Protocol](https://img.shields.io/badge/protocol-v1.3.0-blue.svg)](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/PROTOCOL.md)
+
+`ps5dbg` lets a developer talk to a PS5 running the [ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG) command payload (the debugger that lives in `SceShellCore` and listens on **port 744**). It implements the full v1.3.0 wire protocol — process inspection, memory scanning, kernel R/W, software & hardware breakpoints, live disassembly/assembly, and console control — and exposes it as both an importable Python library and a `ps5dbg` command-line tool.
+
+It runs anywhere Python 3.10+ runs (Linux, macOS, Windows) with **zero runtime dependencies**.
+
+---
+
+## Why it exists
+
+Every reusable client for the ps5debug/ps5debug-NG protocol today is **C# / .NET, Windows-oriented, and predates the v1.3.0 protocol additions** — the canonical reference (Ctn's `PS4DBG.cs`) has been dormant since 2023. Mac and Linux users who want to scan memory or apply trainers over this protocol have **no working open tool**.
+
+`ps5dbg` fills that gap: a clean, tested, dependency-free Python implementation of the full v1.3.0 protocol — framing, bit-swapped status words, the xorshift-128 auth handshake, the turbo-scan family, kernel R/W, breakpoints, and the port-755 async interrupt channel. It's the foundation that makes a cross-platform scanner GUI or unified toolbox feasible later.
+
+---
+
+## Install
+
+```bash
+# when published
+pip install ps5dbg
+# or
+pipx install ps5dbg
+
+# from source (development)
+git clone https://github.com/Darkatek7/ps5dbg.git
+cd ps5dbg
+pip install -e ".[dev]"
+```
+
+Requires a PS5 running [ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG) and reachable on your LAN. Set the address via `--host`/`--port` or the `PS5_HOST`/`PS5_PORT` env vars (default unset).
+
+---
+
+## Quick start
+
+**CLI:**
+```bash
+$ ps5dbg ping
+ps5debug-NG v1.3 (ps5debug-NG by OSR v1.3.0)  FW=5.50  rtt=3ms
+
+$ ps5dbg procs
+PID    NAME
+  0    kernel
+  1    init
+...
+ 47    SceShellCore
+ 91    eboot.bin             # the foreground game
+
+$ ps5dbg read 91 0x0000004b3a8c0000 16 --hex
+4b3a8c0000  7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00
+
+$ ps5dbg notify "hello from ps5dbg"
+```
+
+**Library:**
+```python
+from ps5dbg import PS5Debug
+
+with PS5Debug("192.168.1.10") as ps5:
+    print(ps5.fw_version())              # 550
+    print(ps5.branding().brand)          # 'ps5debug-NG by OSR v1.3.0'
+    for p in ps5.procs():
+        print(f"{p.pid:4d}  {p.name}")
+    data = ps5.read(pid=91, addr=0x4b3a8c0000, length=16)
+```
+
+**Build a trainer in a few lines** (full scan API lands with v0.1):
+```python
+# pseudo — see examples/build_a_trainer.py once scan lands
+with PS5Debug("192.168.1.10") as ps5:
+    fg = ps5.foreground_app()
+    hits = ps5.scan_aob(fg.pid, addr, length, pattern=b"\x01\x00\x00\x00", mask=b"\xff\xff\xff\xff")
+    ps5.write(fg.pid, hits[0], (999).to_bytes(4, "little"))   # risky: needs --yes-equivalent in CLI
+```
+
+---
+
+## Features
+
+Full coverage of the ps5debug-NG v1.3.0 command surface:
+
+| Area | What you can do |
+|---|---|
+| **Info / ping** | protocol version, firmware version, branding, platform id, liveness NOP |
+| **Processes** | list, memory read/write (auto-chunked past 1 MiB), write-multi, VM maps, metadata (name/path/titleId/contentId), alloc/free, RPC function call (6 SysV args), ELF load (run or RPC), mprotect, foreground-app detect |
+| **Memory scanning** | one-shot value scan, AOB + multi-AOB, iterative trio (START/COUNT/GET, auth-gated), **turbo scan family** (SIMD compare, server-resident sets, snapshot, aliasing, parallel) with capability detection + automatic fallback to the iterative trio |
+| **Kernel** | kernel base, arbitrary kernel memory read/write |
+| **Disasm / asm** | server-side **Zydis** region disassembly, RIP-relative xref extraction, xrefs-to-target, server-side RBP-chain stack walk, server-side **Keystone** x86-64 assembly |
+| **Debugger** | attach/detach, up to 30 software breakpoints, up to 4 hardware watchpoints, full register access (GP/FPU+YMM/debug/FS-GS base), thread list/suspend/resume, continue/stop/step, async interrupt packets via the port-755 outbound channel |
+| **Console** | reboot, on-screen notification, kernel-console print |
+| **Discovery & logs** | UDP `0xFFFFAAAA` discovery to find consoles without hardcoding IPs, kernel-log tailer (port 9081) |
+
+---
+
+## CLI reference
+
+```
+ps5dbg [--host H] [--port P] [--json] SUBCOMMAND
+
+Connection / info:
+  ping                         NOP round-trip + fw version
+  version                      protocol version + branding + fw + platform id
+  discover                     UDP broadcast, list responding consoles
+  klog [-f]                    tail kernel log (port 9081)
+  notify "<text>"              on-screen toast
+  reboot                       (confirm required)
+
+Process & memory:
+  procs                        process list
+  fg                           foreground app
+  info <pid>                   name/path/titleid/contentid
+  maps <pid>                   VM maps
+  read  <pid> <addr> <len> [--hex|--bytes|--ascii]
+  write <pid> <addr> <hex|@file>          (--yes required)
+  write-multi <pid> <addr>:<hex> ...      (--yes required)
+  alloc <pid> <len>
+  free  <pid> <addr> <len>
+
+Kernel:
+  kbase                        kernel base address
+  kread  <addr> <len>
+  kwrite <addr> <hex|@file>                (--yes required)
+
+Reverse engineering:
+  disasm <pid> <addr> <len>    server-side Zydis
+  asm "<text>" [--base 0x..]   server-side Keystone
+  stack <pid> [<rbp> <rsp>]    server-side stack walk
+
+Scanning:
+  scan value <pid> <addr> <len> <type> <cmp> <value>
+  scan aob   <pid> <addr> <len> <pattern> [--mask ..]
+  scan start|count|get <pid> ...   (iterative, auth-gated)
+  scan turbo ...                    (caps-detected)
+
+Debugger:
+  dbg attach <pid>
+  dbg threads
+  dbg regs <lwpid>
+  dbg bp <index> <addr>
+  dbg wp <index> <addr> <len> <rw>
+  dbg continue|stop|step
+  dbg detach
+```
+
+Use `--json` on any subcommand for machine-readable output. Mutating/risky commands (`write`, `kwrite`, `reboot`, `protect`, `load_elf`, `attach`) require `--yes` or an interactive confirm.
+
+---
+
+## Protocol coverage
+
+`ps5dbg` implements every opcode in the ps5debug-NG v1.3.0 table (66 commands across the info / process / debug / kernel / console namespaces). Notes on the non-obvious bits:
+
+- **Status words are bit-swapped** on the wire (adjacent even/odd bits swapped). `CMD_SUCCESS` arrives as `0x80000000`. The library handles this internally; you compare against `ps5dbg.Status.SUCCESS`.
+- **1 MiB max body** — `read`, `write`, and `load_elf` auto-chunk transparently.
+- **Auth handshake** (`CMD_PROC_AUTH`) uses an xorshift-128 keystream seeded `[200,300,400,500]`; `ps5dbg` runs it for you and sets the scan-enabled bit.
+- **Turbo scan** is capability-detected via `CMD_PROC_TURBOSCAN_CAPS` with automatic fallback to the iterative trio when the server predates it.
+- **Debugger interrupts** arrive over a separate TCP channel (port 755, PS5 dials out) as 1184-byte packets; `ps5dbg` runs a background listener and surfaces them via callback/queue.
+
+Full protocol notes and gotchas: see [`docs/protocol_notes.md`](./docs/protocol_notes.md) and the upstream [`PROTOCOL.md`](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/PROTOCOL.md).
+
+---
+
+## Requirements & compatibility
+
+- **Python** 3.10 or newer. No runtime dependencies.
+- **OS** any (Linux / macOS / Windows).
+- **Console** any PS5 running ps5debug-NG v1.x (the library targets v1.3.0). Verified against FW 5.50.
+
+---
+
+## Roadmap
+
+- **v0.1** — full protocol coverage ✅ (this release: all 66 opcodes across info/process/scan+turbo/kernel/disasm/asm/debugger/console/discovery/klog)
+- **v0.2** — memory-scanner GUI on top of `ps5dbg` (cross-platform "Cheat Engine for PS5")
+- **v0.3** — unified PC toolbox (klog tail + elfldr deploy + ps5dbg control + PKG install + console discovery in one app)
+
+Contributions welcome — see [`AGENTS.md`](./AGENTS.md) for architecture and conventions.
+
+## Testing
+
+```
+pytest                       # unit tests (anywhere; no PS5 needed)
+pytest -m live               # + live tests against PS5_HOST (default unset; set PS5_HOST)
+pytest -m live --risky --yes # + risky live tests (notify, debug attach) — be prepared to reboot
+```
+
+Unit tests cover: bitswap involution, status-code mapping, framing layout,
+opcode top-byte, interrupt-packet parsing, GP-register indexing. Live tests
+exercise the real console on safe ops (ping, version, procs, maps, read,
+kern_base, AOB scan, turbo scan resident round-trip). No test ever reboots the
+console. The debug-attach test is gated behind `--risky` because attaching to
+SceShellCore can freeze the system UI.
+
+See [`examples/`](./examples) for `read_game_memory.py`, `build_a_trainer.py`,
+and `watch_foreground.py`.
+
+---
+
+## Acknowledgments
+
+- **[OpenSourcereR-dev/ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG)** — the debugger payload and the definitive `PROTOCOL.md` this library implements.
+- **Ctn** — the original `ps5debug`, whose wire protocol ps5debug-NG extends and which this library remains compatible with.
+- **[ps5-payload-dev](https://github.com/ps5-payload-dev)** — the SDK and payload ecosystem that made PS5 homebrew possible.
+- **[etaHEN](https://github.com/etaHEN/etaHEN)** — the HEN chain that loads the debugger.
+
+## License
+
+[GPL-3.0-only](./LICENSE) — matching ps5debug-NG, whose wire protocol this library implements.

ps5dbg-0.1.0/README.md

@@ -0,0 +1,216 @@
+# ps5dbg
+
+> A cross-platform Python client and CLI for the **ps5debug-NG** wire protocol on jailbroken PS5 consoles. Speak to your console from any OS — build trainers, debuggers, and tooling on a clean library instead of reimplementing the protocol.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE)
+[![Tests](https://img.shields.io/badge/tests-31%20pass%20%2B%2015%20live-brightgreen.svg)](#testing)
+[![Protocol](https://img.shields.io/badge/protocol-v1.3.0-blue.svg)](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/PROTOCOL.md)
+
+`ps5dbg` lets a developer talk to a PS5 running the [ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG) command payload (the debugger that lives in `SceShellCore` and listens on **port 744**). It implements the full v1.3.0 wire protocol — process inspection, memory scanning, kernel R/W, software & hardware breakpoints, live disassembly/assembly, and console control — and exposes it as both an importable Python library and a `ps5dbg` command-line tool.
+
+It runs anywhere Python 3.10+ runs (Linux, macOS, Windows) with **zero runtime dependencies**.
+
+---
+
+## Why it exists
+
+Every reusable client for the ps5debug/ps5debug-NG protocol today is **C# / .NET, Windows-oriented, and predates the v1.3.0 protocol additions** — the canonical reference (Ctn's `PS4DBG.cs`) has been dormant since 2023. Mac and Linux users who want to scan memory or apply trainers over this protocol have **no working open tool**.
+
+`ps5dbg` fills that gap: a clean, tested, dependency-free Python implementation of the full v1.3.0 protocol — framing, bit-swapped status words, the xorshift-128 auth handshake, the turbo-scan family, kernel R/W, breakpoints, and the port-755 async interrupt channel. It's the foundation that makes a cross-platform scanner GUI or unified toolbox feasible later.
+
+---
+
+## Install
+
+```bash
+# when published
+pip install ps5dbg
+# or
+pipx install ps5dbg
+
+# from source (development)
+git clone https://github.com/Darkatek7/ps5dbg.git
+cd ps5dbg
+pip install -e ".[dev]"
+```
+
+Requires a PS5 running [ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG) and reachable on your LAN. Set the address via `--host`/`--port` or the `PS5_HOST`/`PS5_PORT` env vars (default unset).
+
+---
+
+## Quick start
+
+**CLI:**
+```bash
+$ ps5dbg ping
+ps5debug-NG v1.3 (ps5debug-NG by OSR v1.3.0)  FW=5.50  rtt=3ms
+
+$ ps5dbg procs
+PID    NAME
+  0    kernel
+  1    init
+...
+ 47    SceShellCore
+ 91    eboot.bin             # the foreground game
+
+$ ps5dbg read 91 0x0000004b3a8c0000 16 --hex
+4b3a8c0000  7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00
+
+$ ps5dbg notify "hello from ps5dbg"
+```
+
+**Library:**
+```python
+from ps5dbg import PS5Debug
+
+with PS5Debug("192.168.1.10") as ps5:
+    print(ps5.fw_version())              # 550
+    print(ps5.branding().brand)          # 'ps5debug-NG by OSR v1.3.0'
+    for p in ps5.procs():
+        print(f"{p.pid:4d}  {p.name}")
+    data = ps5.read(pid=91, addr=0x4b3a8c0000, length=16)
+```
+
+**Build a trainer in a few lines** (full scan API lands with v0.1):
+```python
+# pseudo — see examples/build_a_trainer.py once scan lands
+with PS5Debug("192.168.1.10") as ps5:
+    fg = ps5.foreground_app()
+    hits = ps5.scan_aob(fg.pid, addr, length, pattern=b"\x01\x00\x00\x00", mask=b"\xff\xff\xff\xff")
+    ps5.write(fg.pid, hits[0], (999).to_bytes(4, "little"))   # risky: needs --yes-equivalent in CLI
+```
+
+---
+
+## Features
+
+Full coverage of the ps5debug-NG v1.3.0 command surface:
+
+| Area | What you can do |
+|---|---|
+| **Info / ping** | protocol version, firmware version, branding, platform id, liveness NOP |
+| **Processes** | list, memory read/write (auto-chunked past 1 MiB), write-multi, VM maps, metadata (name/path/titleId/contentId), alloc/free, RPC function call (6 SysV args), ELF load (run or RPC), mprotect, foreground-app detect |
+| **Memory scanning** | one-shot value scan, AOB + multi-AOB, iterative trio (START/COUNT/GET, auth-gated), **turbo scan family** (SIMD compare, server-resident sets, snapshot, aliasing, parallel) with capability detection + automatic fallback to the iterative trio |
+| **Kernel** | kernel base, arbitrary kernel memory read/write |
+| **Disasm / asm** | server-side **Zydis** region disassembly, RIP-relative xref extraction, xrefs-to-target, server-side RBP-chain stack walk, server-side **Keystone** x86-64 assembly |
+| **Debugger** | attach/detach, up to 30 software breakpoints, up to 4 hardware watchpoints, full register access (GP/FPU+YMM/debug/FS-GS base), thread list/suspend/resume, continue/stop/step, async interrupt packets via the port-755 outbound channel |
+| **Console** | reboot, on-screen notification, kernel-console print |
+| **Discovery & logs** | UDP `0xFFFFAAAA` discovery to find consoles without hardcoding IPs, kernel-log tailer (port 9081) |
+
+---
+
+## CLI reference
+
+```
+ps5dbg [--host H] [--port P] [--json] SUBCOMMAND
+
+Connection / info:
+  ping                         NOP round-trip + fw version
+  version                      protocol version + branding + fw + platform id
+  discover                     UDP broadcast, list responding consoles
+  klog [-f]                    tail kernel log (port 9081)
+  notify "<text>"              on-screen toast
+  reboot                       (confirm required)
+
+Process & memory:
+  procs                        process list
+  fg                           foreground app
+  info <pid>                   name/path/titleid/contentid
+  maps <pid>                   VM maps
+  read  <pid> <addr> <len> [--hex|--bytes|--ascii]
+  write <pid> <addr> <hex|@file>          (--yes required)
+  write-multi <pid> <addr>:<hex> ...      (--yes required)
+  alloc <pid> <len>
+  free  <pid> <addr> <len>
+
+Kernel:
+  kbase                        kernel base address
+  kread  <addr> <len>
+  kwrite <addr> <hex|@file>                (--yes required)
+
+Reverse engineering:
+  disasm <pid> <addr> <len>    server-side Zydis
+  asm "<text>" [--base 0x..]   server-side Keystone
+  stack <pid> [<rbp> <rsp>]    server-side stack walk
+
+Scanning:
+  scan value <pid> <addr> <len> <type> <cmp> <value>
+  scan aob   <pid> <addr> <len> <pattern> [--mask ..]
+  scan start|count|get <pid> ...   (iterative, auth-gated)
+  scan turbo ...                    (caps-detected)
+
+Debugger:
+  dbg attach <pid>
+  dbg threads
+  dbg regs <lwpid>
+  dbg bp <index> <addr>
+  dbg wp <index> <addr> <len> <rw>
+  dbg continue|stop|step
+  dbg detach
+```
+
+Use `--json` on any subcommand for machine-readable output. Mutating/risky commands (`write`, `kwrite`, `reboot`, `protect`, `load_elf`, `attach`) require `--yes` or an interactive confirm.
+
+---
+
+## Protocol coverage
+
+`ps5dbg` implements every opcode in the ps5debug-NG v1.3.0 table (66 commands across the info / process / debug / kernel / console namespaces). Notes on the non-obvious bits:
+
+- **Status words are bit-swapped** on the wire (adjacent even/odd bits swapped). `CMD_SUCCESS` arrives as `0x80000000`. The library handles this internally; you compare against `ps5dbg.Status.SUCCESS`.
+- **1 MiB max body** — `read`, `write`, and `load_elf` auto-chunk transparently.
+- **Auth handshake** (`CMD_PROC_AUTH`) uses an xorshift-128 keystream seeded `[200,300,400,500]`; `ps5dbg` runs it for you and sets the scan-enabled bit.
+- **Turbo scan** is capability-detected via `CMD_PROC_TURBOSCAN_CAPS` with automatic fallback to the iterative trio when the server predates it.
+- **Debugger interrupts** arrive over a separate TCP channel (port 755, PS5 dials out) as 1184-byte packets; `ps5dbg` runs a background listener and surfaces them via callback/queue.
+
+Full protocol notes and gotchas: see [`docs/protocol_notes.md`](./docs/protocol_notes.md) and the upstream [`PROTOCOL.md`](https://github.com/OpenSourcereR-dev/ps5debug-NG/blob/main/PROTOCOL.md).
+
+---
+
+## Requirements & compatibility
+
+- **Python** 3.10 or newer. No runtime dependencies.
+- **OS** any (Linux / macOS / Windows).
+- **Console** any PS5 running ps5debug-NG v1.x (the library targets v1.3.0). Verified against FW 5.50.
+
+---
+
+## Roadmap
+
+- **v0.1** — full protocol coverage ✅ (this release: all 66 opcodes across info/process/scan+turbo/kernel/disasm/asm/debugger/console/discovery/klog)
+- **v0.2** — memory-scanner GUI on top of `ps5dbg` (cross-platform "Cheat Engine for PS5")
+- **v0.3** — unified PC toolbox (klog tail + elfldr deploy + ps5dbg control + PKG install + console discovery in one app)
+
+Contributions welcome — see [`AGENTS.md`](./AGENTS.md) for architecture and conventions.
+
+## Testing
+
+```
+pytest                       # unit tests (anywhere; no PS5 needed)
+pytest -m live               # + live tests against PS5_HOST (default unset; set PS5_HOST)
+pytest -m live --risky --yes # + risky live tests (notify, debug attach) — be prepared to reboot
+```
+
+Unit tests cover: bitswap involution, status-code mapping, framing layout,
+opcode top-byte, interrupt-packet parsing, GP-register indexing. Live tests
+exercise the real console on safe ops (ping, version, procs, maps, read,
+kern_base, AOB scan, turbo scan resident round-trip). No test ever reboots the
+console. The debug-attach test is gated behind `--risky` because attaching to
+SceShellCore can freeze the system UI.
+
+See [`examples/`](./examples) for `read_game_memory.py`, `build_a_trainer.py`,
+and `watch_foreground.py`.
+
+---
+
+## Acknowledgments
+
+- **[OpenSourcereR-dev/ps5debug-NG](https://github.com/OpenSourcereR-dev/ps5debug-NG)** — the debugger payload and the definitive `PROTOCOL.md` this library implements.
+- **Ctn** — the original `ps5debug`, whose wire protocol ps5debug-NG extends and which this library remains compatible with.
+- **[ps5-payload-dev](https://github.com/ps5-payload-dev)** — the SDK and payload ecosystem that made PS5 homebrew possible.
+- **[etaHEN](https://github.com/etaHEN/etaHEN)** — the HEN chain that loads the debugger.
+
+## License
+
+[GPL-3.0-only](./LICENSE) — matching ps5debug-NG, whose wire protocol this library implements.

ps5dbg-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ps5dbg"
+version = "0.1.0"
+description = "Cross-platform Python client and CLI for the ps5debug-NG wire protocol on jailbroken PS5 consoles."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-only" }
+authors = [{ name = "Darkatek7" }]
+keywords = ["ps5", "playstation5", "ps5debug", "ps5debug-ng", "debugger", "homebrew", "jailbreak"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Hardware",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov",
+]
+build = [
+    "build",
+    "twine",
+]
+
+[project.scripts]
+ps5dbg = "ps5dbg.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Darkatek7/ps5dbg"
+Repository = "https://github.com/Darkatek7/ps5dbg"
+Issues = "https://github.com/Darkatek7/ps5dbg/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: tests that require a reachable PS5 at PS5_HOST:PS5_PORT (default unset; set PS5_HOST)",
+    "risky: live tests that mutate target/kernel state (need --risky to run)",
+]

ps5dbg-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ps5dbg-0.1.0/src/ps5dbg/__init__.py

@@ -0,0 +1,39 @@
+"""ps5dbg — cross-platform Python client + CLI for the ps5debug-NG wire protocol.
+
+Public API:
+
+    from ps5dbg import PS5Debug
+
+    with PS5Debug("192.168.1.10") as ps5:    # your PS5's LAN IP
+        print(ps5.fw_version())          # -> 550
+        for p in ps5.procs():
+            print(p.pid, p.name)
+
+Host resolution: pass host= explicitly, OR set the PS5_HOST env var (then
+PS5Debug() with no argument uses it).
+"""
+from __future__ import annotations
+
+from .client import PS5Debug
+from .errors import (
+    AlreadyAttached,
+    AuthFailed,
+    BadStatus,
+    ConnectionLost,
+    PS5DbgError,
+    ProtocolError,
+    ScanAuthRequired,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "PS5Debug",
+    "PS5DbgError",
+    "ConnectionLost",
+    "ProtocolError",
+    "BadStatus",
+    "AuthFailed",
+    "ScanAuthRequired",
+    "AlreadyAttached",
+    "__version__",
+]

ps5dbg-0.1.0/src/ps5dbg/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m ps5dbg``."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())