277 lines
8.3 KiB
Markdown
277 lines
8.3 KiB
Markdown
# Task Tree Dashboard 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:** Replace the dashboard Task Center detail tables with a stable task -> playlist -> song tree that updates node state in place.
|
|
|
|
**Architecture:** Keep the existing FastAPI endpoints and lazy playlist-song endpoint, but change the repository task query to keep finished tasks visible and change the dashboard frontend from table redraws to keyed tree-node patching. The top dashboard cards remain unchanged in this iteration.
|
|
|
|
**Tech Stack:** Python, FastAPI, Jinja2 templates, vanilla JavaScript, unittest
|
|
|
|
---
|
|
|
|
### Task 1: Keep finished tasks in the Task Center query
|
|
|
|
**Files:**
|
|
- Modify: `musicdl/catalogsync/ops/repository.py`
|
|
- Modify: `tests/catalogsync/test_ops_repository.py`
|
|
|
|
- [ ] **Step 1: Write the failing repository test**
|
|
|
|
```python
|
|
def test_list_task_center_rows_includes_completed_jobs(self):
|
|
from musicdl.catalogsync.db import initialize_database
|
|
from musicdl.catalogsync.ops.models import JobStatus
|
|
from musicdl.catalogsync.ops.repository import OpsRepository
|
|
|
|
with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmpdir:
|
|
db_path = Path(tmpdir) / "catalogsync.db"
|
|
initialize_database(db_path).close()
|
|
repo = OpsRepository(db_path)
|
|
|
|
completed_job_id = repo.create_job(
|
|
job_type="download_only",
|
|
config_snapshot={},
|
|
status=JobStatus.COMPLETED,
|
|
playlist_scope={"playlist_ids": [42]},
|
|
)
|
|
|
|
rows = repo.list_task_center_rows(limit=20)
|
|
|
|
rows_by_id = {int(row["id"]): row for row in rows}
|
|
self.assertIn(completed_job_id, rows_by_id)
|
|
self.assertEqual("completed", rows_by_id[completed_job_id]["status"])
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_repository.OpsRepositoryTaskCenterTests.test_list_task_center_rows_includes_completed_jobs -v`
|
|
|
|
Expected: FAIL because completed jobs are filtered out of `list_task_center_rows()`.
|
|
|
|
- [ ] **Step 3: Write the minimal implementation**
|
|
|
|
```python
|
|
rows = self._fetchall(
|
|
"""
|
|
SELECT *
|
|
FROM job_runs
|
|
WHERE status IN (?, ?, ?, ?, ?, ?, ?, ?)
|
|
...
|
|
""",
|
|
(
|
|
JobStatus.RUNNING.value,
|
|
JobStatus.PAUSE_REQUESTED.value,
|
|
JobStatus.QUEUED.value,
|
|
JobStatus.PAUSED.value,
|
|
JobStatus.COMPLETED.value,
|
|
JobStatus.COMPLETED_WITH_ERRORS.value,
|
|
JobStatus.FAILED.value,
|
|
JobStatus.CANCELED.value,
|
|
...
|
|
),
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_repository.OpsRepositoryTaskCenterTests.test_list_task_center_rows_includes_completed_jobs -v`
|
|
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add musicdl/catalogsync/ops/repository.py tests/catalogsync/test_ops_repository.py
|
|
git commit -m "test: keep completed tasks in task center"
|
|
```
|
|
|
|
### Task 2: Lock dashboard HTML to the tree shell
|
|
|
|
**Files:**
|
|
- Modify: `musicdl/catalogsync/templates/ops/dashboard.html`
|
|
- Modify: `tests/catalogsync/test_ops_api.py`
|
|
|
|
- [ ] **Step 1: Write the failing dashboard HTML test**
|
|
|
|
```python
|
|
def test_dashboard_page_renders_task_tree_shell_without_detail_tables(self):
|
|
from musicdl.catalogsync.ops.models import JobStatus
|
|
from musicdl.catalogsync.ops.repository import OpsRepository
|
|
|
|
client, db_path, _ = self._build_client()
|
|
repo = OpsRepository(db_path)
|
|
job_id = repo.create_job(
|
|
job_type="download_only",
|
|
config_snapshot={},
|
|
status=JobStatus.RUNNING,
|
|
)
|
|
|
|
response = client.get("/dashboard")
|
|
html = response.text
|
|
|
|
self.assertIn('data-task-tree-root', html)
|
|
self.assertIn(f'data-task-node="{job_id}"', html)
|
|
self.assertNotIn("<h3>Summary</h3>", html)
|
|
self.assertNotIn("<h3>Stages</h3>", html)
|
|
self.assertNotIn("<h3>Workers</h3>", html)
|
|
self.assertNotIn("<h3>Running Items</h3>", html)
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_api.OperationsApiTests.test_dashboard_page_renders_task_tree_shell_without_detail_tables -v`
|
|
|
|
Expected: FAIL because the template still renders the table/detail shell.
|
|
|
|
- [ ] **Step 3: Write the minimal template implementation**
|
|
|
|
```html
|
|
<div class="card">
|
|
<h2>Task Center</h2>
|
|
<div class="task-tree" data-task-tree-root>
|
|
{% for row in task_rows %}
|
|
<section class="task-node" data-task-node="{{ row.id }}">
|
|
<div class="task-node__header">
|
|
<button type="button" data-task-toggle="{{ row.id }}">+</button>
|
|
<div class="task-node__meta">
|
|
<strong>{{ row.display_name }}</strong>
|
|
<div class="muted">{{ row.job_type }}</div>
|
|
</div>
|
|
</div>
|
|
<div class="task-node__children" data-task-children="{{ row.id }}" hidden></div>
|
|
</section>
|
|
{% endfor %}
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_api.OperationsApiTests.test_dashboard_page_renders_task_tree_shell_without_detail_tables -v`
|
|
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add musicdl/catalogsync/templates/ops/dashboard.html tests/catalogsync/test_ops_api.py
|
|
git commit -m "feat: replace task center table with tree shell"
|
|
```
|
|
|
|
### Task 3: Replace Task Center redraw with keyed tree patching
|
|
|
|
**Files:**
|
|
- Modify: `musicdl/catalogsync/static/ops/app.js`
|
|
- Modify: `musicdl/catalogsync/templates/ops/base.html`
|
|
|
|
- [ ] **Step 1: Add the tree patch helpers**
|
|
|
|
```javascript
|
|
function upsertTaskTree(rows) {
|
|
var root = document.querySelector("[data-task-tree-root]");
|
|
if (!root) {
|
|
return;
|
|
}
|
|
var seen = {};
|
|
rows.forEach(function (row) {
|
|
var id = String(row.id);
|
|
seen[id] = true;
|
|
var node = ensureTaskNode(root, row);
|
|
patchTaskNode(node, row);
|
|
});
|
|
pruneMissingTaskNodes(root, seen);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Switch `updateDashboard()` away from `setTaskRows()`**
|
|
|
|
```javascript
|
|
if (Object.prototype.hasOwnProperty.call(payload, "task_rows")) {
|
|
dashboardState.taskRows = payload.task_rows || [];
|
|
pruneTaskState(dashboardState.taskRows);
|
|
upsertTaskTree(dashboardState.taskRows);
|
|
restoreExpandedTaskRows();
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Rebuild expanded task rendering as playlist nodes only**
|
|
|
|
```javascript
|
|
function applyTaskDetail(jobId, payload) {
|
|
dashboardState.detailCache[String(jobId)] = payload;
|
|
patchPlaylistTree(String(jobId), payload.playlist_progress || []);
|
|
restoreExpandedPlaylistRows(String(jobId));
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Rebuild playlist song rendering as song child nodes**
|
|
|
|
```javascript
|
|
function applyPlaylistSongs(jobId, playlistId, songs) {
|
|
var key = playlistKey(jobId, playlistId);
|
|
var body = document.querySelector('[data-playlist-song-list="' + key + '"]');
|
|
patchSongTree(body, songs || []);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Version the static asset to force the browser to pick up the new script**
|
|
|
|
```html
|
|
<script src="/static/ops/app.js?v=20260417_task_tree_v3" defer></script>
|
|
```
|
|
|
|
- [ ] **Step 6: Run targeted API tests**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_api tests.catalogsync.test_ops_repository -v`
|
|
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add musicdl/catalogsync/static/ops/app.js musicdl/catalogsync/templates/ops/base.html
|
|
git commit -m "feat: patch dashboard task tree in place"
|
|
```
|
|
|
|
### Task 4: Final verification and docs sync
|
|
|
|
**Files:**
|
|
- Modify: `docs/catalogsync.md`
|
|
|
|
- [ ] **Step 1: Document the new dashboard behavior**
|
|
|
|
```markdown
|
|
## Task Center
|
|
|
|
The dashboard Task Center now renders a tree:
|
|
|
|
- task
|
|
- playlist
|
|
- song
|
|
|
|
Task state updates patch the existing node in place. Expanding a task no longer renders Summary, Stages, Workers, or Running Items tables.
|
|
```
|
|
|
|
- [ ] **Step 2: Run regression verification**
|
|
|
|
Run: `python -m unittest tests.catalogsync.test_ops_api tests.catalogsync.test_ops_repository -v`
|
|
|
|
Expected: PASS
|
|
|
|
- [ ] **Step 3: Manual browser verification**
|
|
|
|
Run the dashboard, expand one task and one playlist, wait through multiple refresh cycles, and verify:
|
|
|
|
- no large detail tables appear
|
|
- paused/completed tasks stay visible
|
|
- expanded nodes remain expanded
|
|
- the task tree does not visibly flash as a full block
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add docs/catalogsync.md
|
|
git commit -m "docs: describe task tree dashboard"
|
|
```
|