# TVAnarchy

Native macOS app (SwiftUI) for the home media stack on **plum**, plus an iOS
companion. Unifies what was previously CLI/MCP-only: pick a **playback device**
(plum's VLC/QuickTime or the HDMI TV on **black**) and drive transport, browse a
cached library, search and manage downloads, enrich metadata, and manage the
device registry — all from one app.

**Hybrid architecture:** the control plane is native Swift (HTTP to VLC's Lua
interface; mpv JSON-IPC over SSH to black — zero new runtime deps); the
data-heavy plane reuses the vendored helper projects (`mcp/`, `recommender/`,
`search/`) as subprocesses. See [docs/](docs/README.md) for the full picture and
[docs/roadmap.md](docs/roadmap.md) for built-vs-designed status.

## Build & dev loop

The easiest way is the `./run` wrapper (see its `usage` and comments for all targets):

```sh
./run          # (or ./run dev) — stamp + xcodegen + Debug build + install + relaunch
./run test
./run clean
./run governor fleet status
./run mcp
./run bridge
./run typecheck
./run test:all
./run deploy
...
```

For manual / Xcode:

```sh
brew install xcodegen        # if not already present
xcodegen generate            # project.yml -> TVAnarchy.xcodeproj
xcodebuild -scheme TVAnarchy -destination 'platform=macOS' build
# or open TVAnarchy.xcodeproj in Xcode and Run
```

See [docs/operations.md](docs/operations.md) for full build/install/deploy flows, release cuts, and per-platform update.

`TVAnarchy.xcodeproj` is generated and git-ignored — `project.yml` is the source of truth.

## Pillars (v2)

**Watch · Download · Net** — product organization and full repo correlation:
[`v2/README.md`](v2/README.md).

## Layout

- `Sources/TVAnarchyCore/` — framework: models, `PlayerTarget` protocol + impls,
  library/metadata/torrents/VPN subsystems, device registry.
- `Sources/TVAnarchy/` — SwiftUI macOS app (App, RootView, feature views:
  Home/Player/Library/Search/Downloads/Metadata/Adult/Devices/Logs/Settings).
- `Sources/TVAnarchyiOS/` — iOS companion (VLCKit player, library, downloads,
  remote control over an HTTP bridge).
- `Tests/TVAnarchyCoreTests/`, `Tests/TVAnarchyiOSUITests/` — unit + UI tests.
- `governor/`, `mcp/`, `recommender/`, `search/` — helper subsystems (own READMEs).
- `fleet/` — designed-only mesh layer; `tools/` — release/update/stamping scripts;
  `docs/` — cross-cutting documentation.

## Playback devices

- **Plum VLC** — HTTP to `http://127.0.0.1:8080/requests/…` (password from
  `~/.config/portable-net-tv/config.json` or `$VLC_HTTP_PASSWORD`).
- **Black (mpv)** — mpv JSON-IPC over SSH, endpoints LAN `10.0.0.11` →
  WG overlay `10.9.0.4` fallback (the LAN address flaps). Launch/library/stats
  are delegated to per-device command templates wrapping `/usr/local/bin/black-tv`
  (the legacy `blacktv` kind auto-migrates to this).
- **QuickTime** — local, zero-install, AppleScript-driven.

Devices live in `~/.config/tv-anarchy/devices.json` and are editable in the
Devices tab.