Metadata-Version: 2.3
Name: krill-collector
Version: 0.1.2
Summary: Record browser workflow sessions into krill recordings
Author: anonymous
Requires-Dist: krill-core>=0.1.0,<0.2.0
Requires-Dist: playwright>=1.49
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# krill-collector

> A krill feeds by filtering everything that drifts past it — this package filters a live browser session, straining out the HTTP exchanges and user events that make up a workflow.

Record a browser workflow session, including server-side request capture, into a krill `WorkflowRecording`.

## Install

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). Playwright needs a browser binary the first time:

```bash
uv add krill-collector
uv run playwright install chromium
```

## Usage

Record from the command line — drive the browser by hand, then close the tab to finish:

```bash
uv run krill-collect http://target-app.local -o logicflow.json
```

Or from Python:

```python
from krill_collector import WorkflowCollector, save_recording

collector = WorkflowCollector("http://target-app.local")
recording = collector.collect()  # opens a browser; records until the tab closes
save_recording(recording, "logicflow.json")
```

The recording is consumed by the companion [krill-fuzzer](../krill-fuzzer/README.md) package.

## API

```
browser session ──▶ intercept ──▶ record ──▶ WorkflowRecording ──▶ JSON
                     ├── network (RequestInterceptor)
                     ├── DOM events (EventRecorder)
                     └── server-side (ServerRequestRecorder)
```

### `krill_collector`

| Symbol | Type | Description |
|--------|------|-------------|
| `WorkflowCollector(target_url, server_project_roots)` | class | Orchestrates a recording session: `collect()` (sync), `async_collect()` |
| `ServerRequestRecorder(project_root, output_dir)` | class | Standalone server-side PHP request capture: `instrument()`, `deinstrument()`, `collect()` |
| `CollectorError` | Exception | Browser launch failure or zero exchanges captured; subclass of `KrillError` |
| `WorkflowRecording` | dataclass | The recording output: exchanges, events, target, timings (from `krill-core`) |
| `RecordedEvent` / `EventType` | recorded interaction + its kind (from `krill-core`) |
| `save_recording` | function | Write a recording to JSON (from `krill-core`) |

### `krill-collect`

Command-line recorder. `krill-collect TARGET_URL [-o OUTPUT] [-s SERVER_ROOT ...]` — records a browser session against `TARGET_URL`, writing JSON to `OUTPUT` (default `logicflow.json`). Repeat `-s DIR` to capture server-side requests from each project root.

## Documentation

- [Docs index](docs/index.md) — collect module design and implementation notes.

## Citation

If you use this project in academic work, please cite our paper. BibTeX (placeholder until the paper is released):

```bibtex
@misc{beluga_placeholder,
  title  = {{TODO: paper title — not yet released}},
  author = {{TODO: authors}},
  year   = {{TODO}},
  note   = {Paper not yet released. Citation entry will be updated on publication.}
}
```

## License

GPL-2.0 — see [LICENSE](../../LICENSE).
