# pm3py Refactor Progress

**Design:** [2026-03-18-refactor-design.md](2026-03-18-refactor-design.md)
**Branch:** `refactor/core-package`
**Started:** 2026-03-18

## Phase 1 — Create `core/`, normalize names, fix imports

**Status: Complete**

### What was done

- Created `pm3py/core/` sub-package
- Moved all source modules into `core/`:
  - `protocol.py`, `transport.py`, `client.py`, `hw.py`, `hf.py`, `lf.py` — moved as-is
  - `hf_14a.py` → `hf_iso14a.py` (renamed)
  - `hf_15.py` → `hf_iso15.py` (renamed)
  - `hf_mf.py` → `hf_mfc.py` (renamed)
- Normalized client attributes:
  - `hf.a14` → `hf.iso14a`
  - `hf.mf` → `hf.mfc`
  - `hf.iso15` — unchanged
- Created `core/__init__.py` re-exporting: `Proxmark3`, `FirmwareInfo`, `PM3Transport`, `PM3Error`, `PM3Response`, `PM3Status`, `Cmd`
- Updated `pm3py/__init__.py` to import from `.core.*`
- Updated all 10 test files (imports + attribute references)
- **30/30 tests passing**

### Backward compatibility

- `from pm3py import Proxmark3` still works (re-exported)
- **Breaking:** `hf.a14` → `hf.iso14a`, `hf.mf` → `hf.mfc`
- **Breaking:** Direct imports like `from pm3py.hf_14a import ...` → `from pm3py.core.hf_iso14a import ...`

## Phase 2 — Extract `sniff/`

**Status: Scaffolded — extraction deferred**

`hf_iso15.py` is 94 lines of clean reader commands + thin `sniff()` firmware call. The trace parsing, 15693 decoders, NDEF annotation, and ANSI formatting described in the design doc haven't been written yet. Nothing to extract.

Created `pm3py/sniff/__init__.py` placeholder. Will extract into sub-modules when sniff infrastructure is implemented.

## Phase 3 — Scaffold `transponders/`

**Status: Complete (scaffolded)**

Created full directory tree per design:
- `transponders/hf/iso14443a3/nxp/` — MIFARE Classic, Ultralight, NTAG
- `transponders/hf/iso14443a4/nxp/` — DESFire, NTAG 5
- `transponders/hf/iso15693/nxp/` — ICODE SLIX2
- `transponders/hf/iso15693/st/` — ST25TV
- `transponders/lf/atmel/` — T55xx
- `transponders/lf/em/` — EM4100, EM4x05

All directories have `__init__.py`. Model migration from sim worktree is a separate effort — the sim framework has ~7.8k LOC with deep inheritance chains (`Transponder` → `Tag15693` → `NxpIcodeTag` → `IcodeSlix2Tag`, etc.) and auth mixins (`NxpPasswordAuth`, `NxpAesAuth`). Base class extraction needs to happen alongside model migration.

## Phase 4 — Scaffold `reader/` and `sim/`

**Status: Complete (scaffolded)**

Created directory trees per design:
- `reader/hf/nxp/` — NXP reader ICs (CLRC663, PN5xx)
- `reader/hf/st/` — ST reader ICs
- `reader/lf/`
- `reader/modes/` — inventory, programming, access control workflows
- `sim/` — sim session, table compiler, relay (migrate from worktree)

All directories have `__init__.py`. Sim migration (~41 files, 7.8k LOC) is a separate effort.

## Next Steps

- Sniff infrastructure: implement trace parsing, 15693 decoders, NDEF annotation, ANSI formatting in `sniff/`
- Transponder migration: extract base classes from sim worktree, populate `transponders/` modules
- Sim migration: move sim session, table compiler, relay into `sim/`
- Reader modes: implement inventory, programming, access workflows in `reader/modes/`