pguzman/serato-doctor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add batch duplicate review workflow

Browse Source
This commit is contained in:
Philip Guzman
2026-07-01 16:18:30 -07:00
parent 4315d8d4d4
commit f3cfed316d
8 changed files with 391 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
serato_doctor/repair.py
+40 -10
View File
@@ -83,8 +83,28 @@ def apply_duplicate_repair(
backup_limit: Optional[int] = 10,
) -> RepairReceipt:
"""Create a complete rollback snapshot, then replace extras with symlinks."""
return apply_duplicate_repair_batch((plan,), serato_root, backup_limit)
def apply_duplicate_repair_batch(
plans: Iterable[DuplicateRepairPlan],
serato_root: Path,
backup_limit: Optional[int] = 10,
) -> RepairReceipt:
"""Apply several approved duplicate choices as one atomic backup."""
plans = tuple(plans)
if not plans:
raise ValueError("Choose at least one duplicate group")
if backup_limit is not None and backup_limit < 1:
raise ValueError("Backup limit must be at least 1, or unlimited")
replaced_paths = tuple(
path for plan in plans for path in plan.replaced
)
if len(set(replaced_paths)) != len(replaced_paths):
raise ValueError("The same file appears in more than one repair choice")
keepers = {plan.keeper for plan in plans}
if keepers.intersection(replaced_paths):
raise ValueError("A selected keeper cannot be removed by another choice")
backup_root = serato_root.expanduser().resolve() / BACKUP_FOLDER
backup = backup_root / _backup_name()
files_root = backup / "files"
@@ -93,35 +113,45 @@ def apply_duplicate_repair(
entries = []
try:
for path in plan.replaced:
destination = files_root / _safe_backup_path(path)
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(path, destination)
entries.append({"original": str(path), "backup": str(destination)})
for path in plan.metadata_files:
for plan in plans:
for path in plan.replaced:
destination = files_root / _safe_backup_path(path)
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(path, destination)
entries.append(
{
"original": str(path),
"backup": str(destination),
"keeper": str(plan.keeper),
}
)
for path in plans[0].metadata_files:
relative = path.relative_to(serato_root.expanduser().resolve())
destination = metadata_root / relative
destination.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(path, destination)
manifest = {
"created_at": datetime.now(timezone.utc).isoformat(),
"keeper": str(plan.keeper),
"keeper": str(plans[0].keeper),
"keepers": [str(plan.keeper) for plan in plans],
"choice_count": len(plans),
"replaced": entries,
"strategy": "symlink",
}
(backup / "manifest.json").write_text(
json.dumps(manifest, indent=2), encoding="utf-8"
)
for path in plan.replaced:
for entry in entries:
path = Path(entry["original"])
path.unlink()
path.symlink_to(plan.keeper)
path.symlink_to(Path(entry["keeper"]))
except Exception:
_rollback_entries(entries)
shutil.rmtree(backup, ignore_errors=True)
raise
rotate_backups(backup_root, backup_limit)
return RepairReceipt(backup, plan.keeper, plan.replaced)
return RepairReceipt(backup, plans[0].keeper, replaced_paths)
def restore_backup(backup: Path) -> Tuple[Path, ...]:
serato_doctor/web.py
+62
View File
@@ -26,6 +26,7 @@ from serato_doctor.scanner import scan_filesystem
from serato_doctor.repair import (
BACKUP_FOLDER,
apply_duplicate_repair,
apply_duplicate_repair_batch,
list_backups,
plan_duplicate_repair,
restore_backup,
@@ -324,6 +325,53 @@ def duplicate_repair(
return result
def duplicate_repair_batch(
serato: Path,
music: Path,
choices: Iterable[dict],
backup_limit: Optional[int],
apply: bool = False,
) -> dict:
"""Validate and preview or apply several keeper choices together."""
serato = serato.expanduser().resolve()
music = music.expanduser().resolve()
if not serato.is_dir() or not music.is_dir():
raise ValueError("Analyze the library again before repairing duplicates")
groups = find_duplicate_groups(scan_filesystem(music).tracks)
valid_groups = [
{track.path.resolve() for track in group.tracks} for group in groups
]
plans = []
selected_groups = set()
for choice in choices:
requested = tuple(Path(value).expanduser().resolve() for value in choice["group_files"])
group_key = frozenset(requested)
if set(requested) not in valid_groups:
raise ValueError("A duplicate group changed; analyze the library again")
if group_key in selected_groups:
raise ValueError("A duplicate group was selected more than once")
selected_groups.add(group_key)
plans.append(
plan_duplicate_repair(Path(choice["keeper"]), requested, serato)
)
if not plans:
raise ValueError("Choose at least one duplicate group")
replaced = [str(path) for plan in plans for path in plan.replaced]
result = {
"choice_count": len(plans),
"replaced": replaced,
"metadata_backups": len(plans[0].metadata_files),
"strategy": "shortcut",
"database_v2_modified": False,
}
if apply:
receipt = apply_duplicate_repair_batch(plans, serato, backup_limit)
result.update({"applied": True, "backup": str(receipt.backup)})
else:
result["applied"] = False
return result
def backup_history(serato: Path) -> dict:
serato = serato.expanduser().resolve()
if not serato.is_dir():
@@ -354,6 +402,8 @@ class SeratoDoctorHandler(BaseHTTPRequestHandler):
try:
token = parse_qs(request.query)["token"][0]
self._audio_response(_verified_audio(token))
except (BrokenPipeError, ConnectionResetError):
return
except (KeyError, IndexError, OSError, ValueError) as error:
self._json_response(404, {"error": str(error)})
return
@@ -379,6 +429,8 @@ class SeratoDoctorHandler(BaseHTTPRequestHandler):
"/api/analyze",
"/api/duplicates/preview",
"/api/duplicates/apply",
"/api/duplicates/batch/preview",
"/api/duplicates/batch/apply",
"/api/backups/restore",
"/api/backups",
"/api/reveal",
@@ -412,6 +464,16 @@ class SeratoDoctorHandler(BaseHTTPRequestHandler):
raise ValueError("That backup does not belong to this library")
restored = restore_backup(backup)
result = {"restored": [str(path) for path in restored]}
elif self.path.startswith("/api/duplicates/batch/"):
raw_limit = payload.get("backup_limit", 10)
backup_limit = None if raw_limit is None else int(raw_limit)
result = duplicate_repair_batch(
Path(payload["serato"]),
Path(payload["music"]),
payload["choices"],
backup_limit,
apply=self.path.endswith("/apply"),
)
else:
raw_limit = payload.get("backup_limit", 10)
backup_limit = None if raw_limit is None else int(raw_limit)
serato_doctor/webui/app.js
+66 -21
View File
@@ -26,6 +26,7 @@ let latestAnalysis = null;
let selectedDuplicateGroup = null;
let previewedRepair = null;
let latestBackup = null;
let reviewState = null;
function expandHome(path) {
return path.trim();
@@ -124,34 +125,59 @@ function renderDetail(key) {
return;
}
if (detail.items[0].file_previews) {
reviewState = {key, index: 0, choices: new Map()};
repairPanel.hidden = false;
renderReviewGroup();
return;
}
drilldownList.innerHTML = detail.items.map((item, index) => `
<article class="detail-item${item.files ? ' selectable-duplicate' : ''}" ${item.files ? `data-duplicate-index="${index}" role="button" tabindex="0"` : ''}>
<article class="detail-item">
<strong>${escapeHtml(item.filename || item.path || 'Untitled item')}</strong>
<ul>${detailLines(item)}</ul>
${item.files ? '<small>Choose this group to review a safe cleanup →</small>' : ''}
</article>
`).join('');
}
function chooseDuplicate(detailKey, index) {
const group = latestAnalysis?.details?.[detailKey]?.items?.[index];
if (!group?.files) return;
selectedDuplicateGroup = group;
function renderReviewGroup() {
const groups = latestAnalysis.details[reviewState.key].items;
const group = groups[reviewState.index];
const chosen = reviewState.choices.get(reviewState.index);
drilldownCount.textContent = `${reviewState.index + 1} of ${groups.length} · ${reviewState.choices.size} approved`;
drilldownSummary.textContent = 'Listen to each candidate, choose the keeper, and we’ll move to the next group. Skip anything uncertain.';
drilldownList.innerHTML = `
<article class="review-workspace">
<div class="review-heading"><div><span>Comparing now</span><strong>${escapeHtml(group.filename)}</strong></div><span>${reviewState.choices.size} selected</span></div>
<div class="review-candidates">${group.file_previews.map((file, index) => `
<section class="review-candidate ${chosen === file.path ? 'winner' : ''}">
<span class="candidate-number">Option ${index + 1}</span>
<strong>${escapeHtml(file.path.split('/').pop())}</strong>
<small>${escapeHtml(file.path)}</small>
<div class="file-actions"><button type="button" data-audio-url="${escapeHtml(file.audio_url)}" data-audio-name="${escapeHtml(file.path)}">▶ Play preview</button><button type="button" data-reveal-token="${escapeHtml(file.reveal_token)}">Show in Finder</button></div>
<button class="choose-winner" type="button" data-choose-winner="${index}">${chosen === file.path ? '✓ Selected keeper' : 'Keep this one →'}</button>
</section>
`).join('')}</div>
<div class="review-navigation"><button type="button" data-review-previous ${reviewState.index === 0 ? 'disabled' : ''}>← Previous</button><button type="button" data-review-skip>Skip for now</button></div>
</article>`;
updateBatchSummary();
}
function updateBatchSummary() {
if (!reviewState) return;
const groups = latestAnalysis.details[reviewState.key].items;
repairChoice.innerHTML = `<div class="batch-summary"><strong>${reviewState.choices.size} group${reviewState.choices.size === 1 ? '' : 's'} approved</strong><span>${groups.length - reviewState.choices.size} skipped or still awaiting a decision</span></div>`;
previewRepairButton.disabled = reviewState.choices.size === 0;
previewedRepair = null;
applyRepairButton.disabled = true;
repairPreview.hidden = true;
repairMessage.textContent = '';
repairChoice.innerHTML = group.files.map((file, fileIndex) => `
<div class="keeper-option"><label><input type="radio" name="keeper" value="${escapeHtml(file)}" ${fileIndex === 0 ? 'checked' : ''}><span><strong>${fileIndex === 0 ? 'Keep this file' : 'Keep instead'}</strong><small>${escapeHtml(file)}</small></span></label><div class="file-actions"><button type="button" data-audio-url="${escapeHtml(group.file_previews[fileIndex].audio_url)}" data-audio-name="${escapeHtml(file)}">▶ Play preview</button><button type="button" data-reveal-token="${escapeHtml(group.file_previews[fileIndex].reveal_token)}">Show in Finder</button></div></div>
`).join('');
repairPanel.hidden = false;
repairPanel.scrollIntoView({behavior: 'smooth', block: 'start'});
}
function repairPayload() {
const keeper = document.querySelector('input[name="keeper"]:checked')?.value;
if (!selectedDuplicateGroup || !keeper) throw new Error('Choose a file to keep');
return {serato: expandHome(document.querySelector('#serato-path').value), music: expandHome(document.querySelector('#music-path').value), keeper, group_files: selectedDuplicateGroup.files, backup_limit: document.querySelector('#keep-all-backups').checked ? null : Number(document.querySelector('#backup-limit').value)};
if (!reviewState?.choices.size) throw new Error('Choose at least one keeper');
const groups = latestAnalysis.details[reviewState.key].items;
const choices = Array.from(reviewState.choices, ([index, keeper]) => ({keeper, group_files: groups[index].files}));
return {serato: expandHome(document.querySelector('#serato-path').value), music: expandHome(document.querySelector('#music-path').value), choices, backup_limit: document.querySelector('#keep-all-backups').checked ? null : Number(document.querySelector('#backup-limit').value)};
}
async function requestRepair(endpoint) {
@@ -164,8 +190,8 @@ async function requestRepair(endpoint) {
previewRepairButton.addEventListener('click', async () => {
repairMessage.textContent = 'Checking the plan…'; applyRepairButton.disabled = true;
try {
previewedRepair = await requestRepair('/api/duplicates/preview');
repairPreview.innerHTML = `<strong>Ready to protect and consolidate</strong><p>${previewedRepair.replaced.length} duplicate file(s) will be backed up, then replaced with shortcuts to the keeper. ${previewedRepair.metadata_backups} Serato metadata file(s) will also be copied into the rollback snapshot. Database V2 will not be changed.</p>`;
previewedRepair = await requestRepair('/api/duplicates/batch/preview');
repairPreview.innerHTML = `<strong>One safe plan for ${previewedRepair.choice_count} approved group(s)</strong><p>${previewedRepair.replaced.length} duplicate file(s) will be backed up, then replaced with shortcuts to their selected keepers. ${previewedRepair.metadata_backups} Serato metadata file(s) will also be copied into the rollback snapshot. Database V2 will not be changed.</p>`;
repairPreview.hidden = false; applyRepairButton.disabled = false;
repairMessage.textContent = 'Preview complete. Nothing has changed yet.';
} catch (error) { repairMessage.textContent = error.message; }
@@ -175,7 +201,7 @@ applyRepairButton.addEventListener('click', async () => {
if (!previewedRepair) return;
applyRepairButton.disabled = true; repairMessage.textContent = 'Creating the backup before making changes…';
try {
const result = await requestRepair('/api/duplicates/apply');
const result = await requestRepair('/api/duplicates/batch/apply');
latestBackup = result.backup;
repairMessage.textContent = `Cleanup complete. Restore backup: ${result.backup}`;
previewRepairButton.disabled = true;
@@ -197,7 +223,6 @@ restoreRepairButton.addEventListener('click', async () => {
} catch (error) { repairMessage.textContent = error.message; restoreRepairButton.disabled = false; }
});
repairChoice.addEventListener('change', () => { previewedRepair = null; applyRepairButton.disabled = true; repairPreview.hidden = true; repairMessage.textContent = 'Keeper changed. Preview the plan again.'; });
async function handleFileAction(event) {
const previewButton = event.target.closest('[data-audio-url]');
const revealButton = event.target.closest('[data-reveal-token]');
@@ -224,8 +249,28 @@ async function handleFileAction(event) {
closeAudioPreview.addEventListener('click', () => { audioPlayer.pause(); audioPlayer.removeAttribute('src'); audioPlayer.load(); audioPreview.hidden = true; });
repairChoice.addEventListener('click', handleFileAction);
drilldownList.addEventListener('click', async (event) => { if (await handleFileAction(event)) return; const item = event.target.closest('[data-duplicate-index]'); if (item) chooseDuplicate(document.querySelector('.drill-trigger.selected')?.dataset.detail, Number(item.dataset.duplicateIndex)); });
drilldownList.addEventListener('keydown', (event) => { if (event.key !== 'Enter' && event.key !== ' ') return; const item = event.target.closest('[data-duplicate-index]'); if (item) { event.preventDefault(); chooseDuplicate(document.querySelector('.drill-trigger.selected')?.dataset.detail, Number(item.dataset.duplicateIndex)); } });
drilldownList.addEventListener('click', async (event) => {
if (await handleFileAction(event) || !reviewState) return;
const groups = latestAnalysis.details[reviewState.key].items;
const winner = event.target.closest('[data-choose-winner]');
if (winner) {
const fileIndex = Number(winner.dataset.chooseWinner);
reviewState.choices.set(reviewState.index, groups[reviewState.index].files[fileIndex]);
if (reviewState.index < groups.length - 1) reviewState.index += 1;
renderReviewGroup();
return;
}
if (event.target.closest('[data-review-skip]')) {
reviewState.choices.delete(reviewState.index);
if (reviewState.index < groups.length - 1) reviewState.index += 1;
renderReviewGroup();
return;
}
if (event.target.closest('[data-review-previous]') && reviewState.index > 0) {
reviewState.index -= 1;
renderReviewGroup();
}
});
function render(data) {
latestAnalysis = data;
serato_doctor/webui/index.html
+5 -5
View File
@@ -93,8 +93,8 @@
</div>
<div id="duplicate-repair" class="repair-panel panel" hidden>
<div class="section-heading"><div><p class="eyebrow">Backup-first cleanup</p><h2>Safely consolidate duplicates</h2></div><span class="repair-tag">Preview required</span></div>
<p>Choose the real file to keep. Every other path will be backed up and replaced with a shortcut to it, so existing Serato crates remain mapped. Serato’s database V2 is never edited.</p>
<div class="section-heading"><div><p class="eyebrow">Batch cleanup</p><h2>Review all selected changes</h2></div><span class="repair-tag">One backup · one apply</span></div>
<p>Approved choices are combined into one plan. Skipped groups remain untouched, and Serato’s database V2 is never edited.</p>
<div id="repair-choice" class="repair-choice"></div>
<div class="backup-options">
<label>Backups to keep <input id="backup-limit" type="number" min="1" value="10"></label>
@@ -102,8 +102,8 @@
</div>
<div id="repair-preview" class="repair-preview" hidden></div>
<div class="repair-actions">
<button id="preview-repair" type="button">Preview changes</button>
<button id="apply-repair" class="danger-action" type="button" disabled>Apply backed-up cleanup</button>
<button id="preview-repair" type="button">Preview all selected changes</button>
<button id="apply-repair" class="danger-action" type="button" disabled>Apply all selected changes</button>
<button id="restore-repair" type="button" hidden>Restore this backup</button>
</div>
<div id="repair-message" class="repair-message" role="status"></div>
@@ -123,6 +123,6 @@
</div>
</main>
</div>
<script src="/app.js?v=4" defer></script>
<script src="/app.js?v=5" defer></script>
</body>
</html>
serato_doctor/webui/layout-fixes.css
+131
View File
@@ -8,6 +8,137 @@
}
}
.review-workspace {
padding: clamp(16px, 3vw, 24px);
border: 1px solid rgba(155, 135, 245, .18);
border-radius: 16px;
background: rgba(255, 255, 255, .02);
}
.review-heading,
.review-navigation {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
}
.review-heading span,
.batch-summary span {
color: var(--muted);
font-size: 10px;
}
.review-heading strong {
display: block;
margin-top: 5px;
font-size: 14px;
}
.review-candidates {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 12px;
margin: 18px 0;
}
.review-candidate {
display: flex;
flex-direction: column;
gap: 9px;
min-width: 0;
padding: 16px;
border: 1px solid var(--line);
border-radius: 14px;
background: rgba(6, 8, 12, .28);
}
.review-candidate.winner {
border-color: rgba(84, 212, 154, .52);
background: rgba(84, 212, 154, .06);
}
.candidate-number {
color: var(--violet);
font-size: 9px;
font-weight: 750;
text-transform: uppercase;
letter-spacing: .1em;
}
.review-candidate > strong,
.review-candidate > small {
overflow-wrap: anywhere;
}
.review-candidate > strong {
font-size: 12px;
}
.review-candidate > small {
flex: 1;
color: var(--muted);
font-size: 9px;
line-height: 1.5;
}
.choose-winner {
margin-top: 4px;
border: 0;
border-radius: 10px;
padding: 10px 12px;
background: linear-gradient(135deg, #907be9, #6e59cf);
color: white;
font: 750 11px/1 inherit;
cursor: pointer;
}
.winner .choose-winner {
background: rgba(84, 212, 154, .18);
color: #8ce4b8;
}
.review-navigation button {
border: 1px solid var(--line);
border-radius: 9px;
padding: 8px 11px;
background: rgba(255, 255, 255, .04);
color: var(--muted);
font: 700 10px/1 inherit;
cursor: pointer;
}
.review-navigation button:disabled {
opacity: .35;
}
.batch-summary {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
padding: 14px;
border: 1px solid rgba(102, 217, 232, .2);
border-radius: 12px;
background: rgba(102, 217, 232, .05);
}
.batch-summary strong {
font-size: 12px;
}
@media (max-width: 760px) {
.review-candidates {
grid-template-columns: 1fr;
}
.review-heading,
.batch-summary {
align-items: flex-start;
flex-direction: column;
}
}
.file-compare-row {
display: grid;
gap: 8px;