iLEAPP

# iLEAPP

iOS, iPadOS and watchOS logs, events and protobuf parser. The largest of the five LEAPP
extractors and the one where shared infrastructure usually lands first.

## Read these before changing an artifact

`admin/docs/` is the authority and is more current than anything summarised here:

| doc | covers |
| --- | --- |
| `admin/docs/artifact_info_block.md` | the `__artifacts_v2__` block, every field, and the `paths` glob semantics |
| `admin/docs/module_updates.md` | writing and updating a module |
| `admin/docs/module_updates_advanced.md` | multi-artifact modules, chaining, advanced cases |
| `admin/docs/features/file_search_architecture.md` | how the seekers find and extract files |
| `admin/docs/testing/create_module_test_cases.md` | test cases for a module |
| `admin/docs/testing/local_corpus_tests.md` | running against local corpora, and the hygiene rules for doing so |

If something here ever contradicts `admin/docs/`, the doc wins and this file is stale.

## Repo-specific things worth knowing

- **Input types.** Filesystem directory, zip, tar/tar.gz, and iOS backup. The backup seeker
  matches differently from the others. See `.claude/rules/ileapp-seekers.md`.
- **Duplicate artifact `name` values are rejected at load time.** Only a full run catches
  this, so run `ileapp.py` once before opening a PR.
- **blackboxprotobuf is vendored** at `scripts/blackboxprotobuf/`. Import it as
  `from scripts import blackboxprotobuf`. Do not add the PyPI package; a test enforces this.
- **Builds are made by `packaging/build.py`**, one PyInstaller spec for every platform and
  one executable, `ileapp`, that opens the window without arguments. Every artifact module
  is a hidden import, so what the artifacts import is followed without a list. What it
  cannot follow is a name built at run time (`importlib.import_module(some_variable)`) or a
  data file kept outside `scripts/`, `leapp_functions/` or `assets/`: expect a working dev
  run and a broken build, and run `python packaging/build.py smoke` or `test_builds.yml`.
  See `.claude/rules/ileapp-build-and-release.md`.

## Local corpora

Artifacts record verified row counts in `sample_data`. The images behind those keys are not
in this repo and most are not public. Print counts and value shapes from them, never actual
values, and delete anything you extract when you are done. `admin/docs/testing/local_corpus_tests.md`
has the full policy.

## Rules

`.claude/rules/` holds the detail. Files prefixed `leapp-` are shared across all five
extractors and `lava-` across all six repos. **Edit those at their canonical source, not
here**, or the next sync overwrites you. `ileapp-` files are local to this repo.

More agent context in abrignoni/iLEAPP

5 other files this repository gives its agents.