3.1 KiB
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.