Metadata-Version: 2.5
Name: flowscape
Version: 0.1.0
Summary: Modern 3D network visualization for macOS — Etherape-shaped, SwiftUI + Metal, no-payload wire format
Project-URL: Homepage, https://github.com/lesleslie/flowscape
Project-URL: Repository, https://github.com/lesleslie/flowscape
Author-email: Les Leslie <les@wedgwoodwebworks.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.14
Requires-Dist: betterproto2>=2.0.0
Requires-Dist: dpkt>=1.9.8
Requires-Dist: numpy>=2.0.0
Requires-Dist: oneiric>=0.16.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: protobuf>=5.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.9; extra == 'dev'
Requires-Dist: betterproto2[cli]>=2.0.0; extra == 'dev'
Requires-Dist: commitizen>=3.0.0; extra == 'dev'
Requires-Dist: complexipy>=3.0.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pip-licenses>=4.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.8; extra == 'dev'
Provides-Extra: macos
Requires-Dist: pcapy-ng>=0.0.4; extra == 'macos'
Requires-Dist: py2app>=0.28.0; extra == 'macos'
Provides-Extra: runtime
Requires-Dist: pcapy-ng>=0.0.4; extra == 'runtime'
Description-Content-Type: text/markdown

# flowscape

> **A 3D landscape of your network flows.**
>
> **Scaffold status: PyPI name reservation.** This package is a placeholder scaffold to claim
> the `flowscape` name on PyPI. Implementation has not yet started; see the design spec
> below for the full v1 plan.

Modern Etherape-shaped network visualization for macOS. SwiftUI + Metal
frontend, Python backend with `dpkt` for parsing and `pcapy-ng` for live
capture. Two `SOCK_SEQPACKET` Unix-domain sockets wire the Swift renderer
to the Python capture pipeline via Protocol Buffers (data plane) and
JSON-RPC 2.0 (control plane).

## Reserve the PyPI name

```bash
cd /Users/les/Projects/flowscape
uv build
uv publish  # uses UV_PUBLISH_TOKEN from env
```

The package name `flowscape` is currently free on PyPI (verified 2026-08-31).
Publishing a placeholder 0.1.0 release locks the name.

## Design spec

The full v1 design lives in
[`docs/superpowers/specs/2026-08-31-flowscape-design.md`](../mahavishnu/docs/superpowers/specs/2026-08-31-flowscape-design.md).
Key commitments:

- **macOS-only, signed `.app` bundle** as headline distribution
- **3D rendering as a headline feature** (orbit camera, click-a-host, hover-to-inspect)
- **Structural no-payload guarantee** — packet payload bytes never leave the capture
  process; wire format carries metadata + a 32-byte SHA-256 prefix per edge
- **Two-process split** — Swift owns GPU/UI; Python owns capture/decode/aggregation/heuristics
- **One source of truth for IPC** — `proto/flowscape.proto` generates both Python
  (`betterproto2`) and Swift (`SwiftProtobuf`) types

## Architecture (planned)

| Module | Purpose |
|---|---|
| `settings.py` | Oneiric settings model (`FlowscapeSettings extends MCPServerSettings`) |
| `capture.py` | libpcap source via `pcapy-ng`; `pcap_thread` posts packets to asyncio |
| `decode.py` | `dpkt` parsing; emits `FlowEvent` with `payload_sha256_prefix` (32-byte) |
| `aggregate.py` | Per-flow rolling counters + per-host byte totals (60s window) |
| `graph.py` | Derives `GraphState` from aggregator on tick |
| `heuristics.py` | Beaconing, port-scan, top-N churn detectors |
| `publisher.py` | Encodes graph snapshots + alerts as protobuf on data.sock |
| `ipc_server.py` | JSON-RPC on control.sock |
| `app.py` | Oneiric-driven entrypoint; signal/cleanup |
| `cli.py` | `flowscape live`, `replay`, `doctor`, `interfaces`, `version` |

Realistic v1 timeline: 14-20 weeks for one experienced developer.

## Status

| Phase | State |
|---|---|
| PyPI name reservation | **pending** (run `uv publish`) |
| Spec / design | complete (in mahavishnu/docs/superpowers/specs/) |
| Implementation | not started |
| Tests | not started |

## License

BSD-3-Clause. See LICENSE.

Etherape is GPLv2. We do **not** study its source code — see the design spec
for the clean-room protocol.