# Catalog Sync Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an independent catalog-sync CLI that harvests playlist pools, persists playlist/song/artist relationships, and automates deduplicated downloads.

**Architecture:** Implement a new `musicdl.catalogsync` package with a SQLite repository layer, per-source collectors, playlist-sync services, and a CLI wrapper that reuses existing `musicdl` source clients for parsing and downloading. Model downloaded media as logical file assets plus storage locations so local paths work now and cloud/object-storage locations fit later.

**Tech Stack:** Python stdlib (`sqlite3`, `json`, `pathlib`, `hashlib`, `shutil`), `click`, existing `musicdl` source clients, `requests`, `unittest`

---

### Task 1: Add failing tests for schema and normalization helpers

**Files:**
- Create: `tests/catalogsync/test_db.py`
- Create: `tests/catalogsync/test_models.py`
- Create: `tests/catalogsync/fixtures/`

- [ ] Write failing tests for schema creation and song dedupe helpers.
- [ ] Run the focused unittest commands and verify they fail for missing modules.
- [ ] Implement the minimal schema and helper modules to satisfy the tests.
- [ ] Re-run the focused tests and verify they pass.

### Task 2: Add failing tests for collector parsing helpers

**Files:**
- Create: `tests/catalogsync/test_collectors.py`
- Create: `musicdl/catalogsync/collectors/`

- [ ] Write fixture-driven failing tests for NetEase, QQ, and Kuwo collector parsing helpers.
- [ ] Run the focused unittest commands and verify they fail.
- [ ] Implement minimal collector modules and parsing helpers.
- [ ] Re-run the focused tests and verify they pass.

### Task 3: Implement repository, sync services, and download planner

**Files:**
- Create: `musicdl/catalogsync/db.py`
- Create: `musicdl/catalogsync/repository.py`
- Create: `musicdl/catalogsync/services.py`
- Create: `musicdl/catalogsync/downloader.py`

- [ ] Write failing service tests for playlist sync, derived artist sync, and download dedupe.
- [ ] Run the focused unittest commands and verify they fail.
- [ ] Implement the repository and service layer.
- [ ] Re-run the focused tests and verify they pass.

### Task 4: Implement CLI and package integration

**Files:**
- Create: `musicdl/catalogsync/cli.py`
- Modify: `setup.py`
- Modify: `musicdl/__init__.py`

- [ ] Write failing CLI smoke tests around argument parsing and DB initialization.
- [ ] Run the focused unittest commands and verify they fail.
- [ ] Implement the CLI entrypoint and wire a new console script.
- [ ] Re-run the focused tests and verify they pass.

### Task 5: Verify end-to-end behavior and document usage

**Files:**
- Create: `docs/catalogsync.md`
- Modify: `README.md`

- [ ] Run the full focused unittest suite for `tests/catalogsync`.
- [ ] Run a manual CLI smoke flow against a temporary SQLite DB.
- [ ] Update user-facing docs with command examples and caveats.
- [ ] Re-run final verification commands and capture results.