feat: migrate sim framework from worktree to master
Migrates all 43 sim modules and 23 test files (~7.8k LOC, 686 tests) from .worktrees/sim-framework/ into pm3py/sim/. Import fixes: - 4 files: ..protocol/..transport → ..core.protocol/..core.transport - trace_fmt.py: pm3py.hf_15 → pm3py.trace.ndef - test_sim_pm3medium.py: flat imports → core.* - test_sim_trace_fmt.py: flat imports → core.* - Added sim Cmd entries to core/protocol.py (EML_SETMEM, SIM_TABLE_*) 751 tests passing (686 sim + 65 core). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
146
docs/plans/2026-03-18-sim-migration.md
Normal file
146
docs/plans/2026-03-18-sim-migration.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Sim Framework Migration Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Migrate the sim framework (~7.8k LOC, 687 tests) from `.worktrees/sim-framework/` to master's `pm3py/sim/`, making all transponder models testable on master.
|
||||
|
||||
**Architecture:** Copy sim/ files as-is (preserving internal imports), fix 2 external imports that reference the old flat package layout (`..protocol` → `..core.protocol`, `..transport` → `..core.transport`). Copy 23 test files. Verify 687+ tests pass. The sim/ package keeps its flat internal structure — reorganization into `transponders/` and `reader/` sub-packages is a follow-up.
|
||||
|
||||
**Tech Stack:** Python 3.12, pytest, AsyncMock
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Dependency graph (acyclic, bottom-up)
|
||||
|
||||
**Foundation (no sim/ deps):** frame, memory, mcu_protocol, trace_fmt, crypto1, auth_aes, access_control/*
|
||||
|
||||
**Core abstractions:** transponder (←frame, memory), medium (←frame, transponder), reader (←frame, medium), auth_password (←frame)
|
||||
|
||||
**LF:** lf_base → em4100 → t5577, hid
|
||||
|
||||
**HF 14443-A:** iso14443a → mifare (+ crypto1), desfire, ndef
|
||||
|
||||
**HF 15693:** iso15693 → type5 → nxp_icode → icode_slix → icode_slix2 → icode3, icode_dna → ntag5_platform → ntag5_switch, ntag5_link → ntag5_boost
|
||||
|
||||
**Integration:** replay, fuzzer, table_compiler, relay, pm3medium, implants, sim_session, mcu_bridge, dual_session
|
||||
|
||||
### External imports (only 2 files)
|
||||
|
||||
- `pm3medium.py`: `from ..protocol import Cmd` and `from ..transport import PM3Transport`
|
||||
- `sim_session.py`: `from ..protocol import Cmd` and `from ..transport import encode_ng_frame, decode_response_frame, RESP_PREAMBLE_MAGIC, RESP_PREAMBLE_SIZE, RESP_POSTAMBLE_SIZE`
|
||||
|
||||
### Overlap with trace/
|
||||
|
||||
`sim/trace_fmt.py` (560 lines) overlaps with `pm3py/trace/` but is more complete (has 14443-A decoders, NXP-specific decoders, TraceFormatter class). Keep both — sim references its own `trace_fmt.py` internally. Unify later.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Copy sim/ source files
|
||||
|
||||
**Files:**
|
||||
- Source: `.worktrees/sim-framework/pm3py/sim/*.py` and `access_control/`
|
||||
- Target: `pm3py/sim/`
|
||||
|
||||
**Step 1:** Copy all .py files from sim worktree into master's pm3py/sim/, overwriting the scaffold `__init__.py`
|
||||
|
||||
```bash
|
||||
cp .worktrees/sim-framework/pm3py/sim/*.py pm3py/sim/
|
||||
mkdir -p pm3py/sim/access_control
|
||||
cp .worktrees/sim-framework/pm3py/sim/access_control/*.py pm3py/sim/access_control/
|
||||
```
|
||||
|
||||
**Step 2:** Verify file count matches
|
||||
|
||||
```bash
|
||||
find pm3py/sim -name '*.py' | wc -l
|
||||
# Expected: ~40+ files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Fix external imports
|
||||
|
||||
**Files:**
|
||||
- Modify: `pm3py/sim/pm3medium.py`
|
||||
- Modify: `pm3py/sim/sim_session.py`
|
||||
|
||||
**Step 1:** In `pm3medium.py`, change:
|
||||
- `from ..protocol import` → `from ..core.protocol import`
|
||||
- `from ..transport import` → `from ..core.transport import`
|
||||
|
||||
**Step 2:** In `sim_session.py`, change:
|
||||
- `from ..protocol import` → `from ..core.protocol import`
|
||||
- `from ..transport import` → `from ..core.transport import`
|
||||
|
||||
**Step 3:** Verify no other files reference outside sim/:
|
||||
|
||||
```bash
|
||||
grep -r "from \.\." pm3py/sim/ | grep -v "from \.\.core\." | grep -v "from \.\.trace"
|
||||
```
|
||||
|
||||
Expected: no output (all external refs fixed).
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Copy test files
|
||||
|
||||
**Files:**
|
||||
- Source: `.worktrees/sim-framework/tests/test_sim_*.py` (23 files)
|
||||
- Target: `tests/`
|
||||
|
||||
**Step 1:** Copy test files
|
||||
|
||||
```bash
|
||||
cp .worktrees/sim-framework/tests/test_sim_*.py tests/
|
||||
```
|
||||
|
||||
**Step 2:** Check if any test files import from old flat paths (like `from pm3py.protocol import`)
|
||||
|
||||
```bash
|
||||
grep "from pm3py\." tests/test_sim_*.py | grep -v "from pm3py\.sim" | grep -v "from pm3py\.core"
|
||||
```
|
||||
|
||||
Fix any that reference old flat layout.
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Run tests — all green
|
||||
|
||||
**Step 1:** Run just sim tests first to isolate issues
|
||||
|
||||
```bash
|
||||
python -m pytest tests/test_sim_*.py -v --tb=short 2>&1 | tail -30
|
||||
```
|
||||
|
||||
Expected: 687 tests, 0 failures.
|
||||
|
||||
**Step 2:** Run full test suite
|
||||
|
||||
```bash
|
||||
python -m pytest tests/ -v
|
||||
```
|
||||
|
||||
Expected: 687 + 65 = 752 tests, 0 failures.
|
||||
|
||||
**Step 3:** Commit
|
||||
|
||||
```bash
|
||||
git add pm3py/sim/ tests/test_sim_*.py
|
||||
git commit -m "feat: migrate sim framework from worktree to master
|
||||
|
||||
Migrates all 41 sim modules and 23 test files (~7.8k LOC, 687 tests)
|
||||
from .worktrees/sim-framework/ into pm3py/sim/. Only 2 import fixes
|
||||
needed (pm3medium.py, sim_session.py) for the core/ package rename.
|
||||
Internal sim/ imports unchanged.
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Update docs
|
||||
|
||||
**Step 1:** Update `CLAUDE.md` package structure to show sim/ is populated
|
||||
**Step 2:** Update `docs/plans/2026-03-18-refactor-progress.md`
|
||||
**Step 3:** Commit docs
|
||||
Reference in New Issue
Block a user