feat: PhotoPrism M0 bring-up — compose stack, web client, sidecar, migrate

Replace the legacy mule-image backend with PhotoPrism plus a thin
SvelteKit client and a Node sidecar for endpoints PhotoPrism doesn't
expose (file rename), and add a two-phase migrator (metadata via PUT,
heaps → albums) for the existing Postgres library.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

sidecar/README.md

@@ -0,0 +1,43 @@
+# mule-sidecar
+
+Auxiliary service that handles operations PhotoPrism's REST API does not expose.
+
+## Why this exists
+
+Per the merge plan at `/home/dtoro/.claude/plans/i-want-you-to-twinkly-galaxy.md`,
+a Go + Gin + GORM service (matching PhotoPrism's stack) will eventually own:
+
+- Per-user heap sharing with pending invitations
+- Folder mutations under `originals/` (create / rename / delete / move)
+- **File rename** on disk (PhotoPrism's `OriginalName` is a display-only rename)
+
+The plan picks Go for stack consistency and the option to upstream features.
+
+## What ships today
+
+A **Node.js prototype** (`server.mjs`) covering only the **file rename** endpoint.
+
+The decision to ship Node first is pragmatic — Go isn't installed on this dev
+box and `sudo dnf install golang` needs a password. Node is already on PATH for
+the SvelteKit dev server, so a single-file Node service unblocks the feature
+without changing the host setup.
+
+The endpoint contract is stable: when M4 lands the proper Go service, the
+SvelteKit client keeps calling the same paths.
+
+## Endpoints
+
+- `POST /api/sidecar/files/:photoUid/rename` `{ "newName": "newfile.png" }`
+  Renames the primary file of the photo on disk under `${ORIGINALS_ROOT}`,
+  then triggers a PhotoPrism reindex of the parent path.
+
+## Run
+
+```
+ORIGINALS_ROOT=/home/dtoro/projects/mule-image/photos-sample \
+PHOTOPRISM_BASE_URL=http://localhost:2342 \
+SIDECAR_PORT=8000 \
+node server.mjs
+```
+
+The SvelteKit dev server proxies `/api/sidecar/*` to `http://localhost:8000`.

sidecar/server.mjs

@@ -0,0 +1,845 @@
+// mule-sidecar — Node.js prototype.
+//
+// Endpoints PhotoPrism does not expose. Today: file rename on disk.
+// Future Go rewrite (per plan) will keep the same wire contract.
+//
+// Auth: forwards the caller's `X-Auth-Token` to PhotoPrism's session check
+// before doing anything destructive. The token belongs to the end user; the
+// sidecar does not hold its own credentials in this prototype.
+
+import http from 'node:http';
+import { URL, fileURLToPath } from 'node:url';
+import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+
+const ORIGINALS_ROOT = path.resolve(
+	process.env.ORIGINALS_ROOT ?? '/photoprism/originals'
+);
+const PHOTOPRISM_BASE_URL =
+	process.env.PHOTOPRISM_BASE_URL ?? 'http://localhost:2342';
+const PORT = Number(process.env.SIDECAR_PORT ?? 8000);
+
+// JSON-backed marks store. Holds the mule-image extras PhotoPrism doesn't:
+// per-photo rating (0..5) and color label (red/orange/yellow/green/'').
+// Lives next to server.mjs so the Go rewrite can migrate it into MariaDB
+// without touching ORIGINALS_ROOT.
+const SIDECAR_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MARKS_FILE = path.join(SIDECAR_DIR, 'data', 'marks.json');
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function json(res, status, body) {
+	res.writeHead(status, { 'Content-Type': 'application/json' });
+	res.end(JSON.stringify(body));
+}
+
+async function readJson(req) {
+	const chunks = [];
+	for await (const c of req) chunks.push(c);
+	const raw = Buffer.concat(chunks).toString('utf8');
+	return raw ? JSON.parse(raw) : {};
+}
+
+async function pp(method, urlPath, token, body) {
+	const url = new URL(urlPath, PHOTOPRISM_BASE_URL);
+	const init = {
+		method,
+		headers: {
+			'X-Auth-Token': token,
+			'Content-Type': 'application/json'
+		}
+	};
+	if (body !== undefined) init.body = JSON.stringify(body);
+	const r = await fetch(url, init);
+	const text = await r.text();
+	let data = null;
+	try {
+		data = text ? JSON.parse(text) : null;
+	} catch {
+		data = text;
+	}
+	return { ok: r.ok, status: r.status, data };
+}
+
+async function validateSession(token) {
+	if (!token) return false;
+	// Cheapest auth probe: list 1 photo. 401 if the token is bad.
+	const r = await pp('GET', '/api/v1/photos?count=1', token);
+	return r.ok;
+}
+
+/**
+ * Enforce: NewName is a bare filename (no path separators, no leading dot,
+ * no surprising chars). PhotoPrism's index works fine with most filename
+ * shapes, but we lock down the obvious dangerous ones.
+ */
+function sanitizeFilename(name) {
+	if (typeof name !== 'string') return null;
+	const trimmed = name.trim();
+	if (!trimmed) return null;
+	if (trimmed.length > 240) return null;
+	if (trimmed.startsWith('.')) return null;
+	if (/[\\/\x00]/.test(trimmed)) return null;
+	if (trimmed === '..' || trimmed === '.') return null;
+	return trimmed;
+}
+
+// ── Marks store (rating + color label) ───────────────────────────────────────
+// In-memory cache backed by an atomic JSON file write. Single-threaded Node
+// means we don't need an external lock — sequential awaits serialize writes.
+
+/** @type {Record<string, { rating?: number; color?: string; updatedAt: string }>} */
+let MARKS_CACHE = null;
+let marksLoadPromise = null;
+
+async function loadMarks() {
+	if (MARKS_CACHE !== null) return MARKS_CACHE;
+	if (marksLoadPromise) return marksLoadPromise;
+	marksLoadPromise = (async () => {
+		await fs.mkdir(path.dirname(MARKS_FILE), { recursive: true });
+		try {
+			const raw = await fs.readFile(MARKS_FILE, 'utf8');
+			MARKS_CACHE = JSON.parse(raw);
+		} catch (err) {
+			if (err.code === 'ENOENT') MARKS_CACHE = {};
+			else throw err;
+		}
+		return MARKS_CACHE;
+	})();
+	return marksLoadPromise;
+}
+
+async function persistMarks() {
+	const tmp = MARKS_FILE + '.tmp';
+	await fs.writeFile(tmp, JSON.stringify(MARKS_CACHE ?? {}, null, 2));
+	await fs.rename(tmp, MARKS_FILE);
+}
+
+/** Normalize partial input. Strips unknown fields, clamps rating to 0..5,
+ *  whitelists colors to mule-image's four-color palette. */
+function sanitizeMarkPatch(patch) {
+	if (!patch || typeof patch !== 'object') return null;
+	const out = {};
+	if ('rating' in patch) {
+		const r = Math.round(Number(patch.rating));
+		if (!Number.isFinite(r) || r < 0 || r > 5) return null;
+		out.rating = r;
+	}
+	if ('color' in patch) {
+		const c = typeof patch.color === 'string' ? patch.color.toLowerCase() : '';
+		if (c !== '' && !['red', 'orange', 'yellow', 'green'].includes(c)) return null;
+		out.color = c;
+	}
+	return out;
+}
+
+/** Merge a patch onto an existing mark, dropping zero/empty so the JSON
+ *  stays sparse — never write `rating: 0` or `color: ''` to disk, just
+ *  delete the field. */
+function mergeMark(prev, patch) {
+	const merged = { ...(prev ?? {}) };
+	if ('rating' in patch) {
+		if (patch.rating > 0) merged.rating = patch.rating;
+		else delete merged.rating;
+	}
+	if ('color' in patch) {
+		if (patch.color) merged.color = patch.color;
+		else delete merged.color;
+	}
+	const hasAny = 'rating' in merged || 'color' in merged;
+	if (!hasAny) return null;
+	merged.updatedAt = new Date().toISOString();
+	return merged;
+}
+
+async function ensureWithinOriginals(absPath) {
+	const real = await fs.realpath(path.dirname(absPath)).catch(() => null);
+	if (!real) return false;
+	return real === ORIGINALS_ROOT || real.startsWith(ORIGINALS_ROOT + path.sep);
+}
+
+/**
+ * Resolve a user-supplied relative path under ORIGINALS_ROOT.
+ * Returns the absolute resolved path on success, or null if it escapes
+ * the root, contains traversal sequences, or its parent is missing.
+ *
+ * `mustExist=false` is used for the *target* of a rename/create where
+ * the path itself doesn't yet exist; we still ensure the parent does.
+ */
+async function resolveUnderRoot(rel, { mustExist = true } = {}) {
+	if (typeof rel !== 'string') return null;
+	const clean = rel.replace(/^\/+/, '');
+	if (!clean || clean === '.' || clean.split('/').some((seg) => seg === '..' || seg === '')) {
+		return null;
+	}
+	const abs = path.resolve(ORIGINALS_ROOT, clean);
+	const parent = path.dirname(abs);
+	// Confirm both the abs and its parent resolve back under ORIGINALS_ROOT
+	// (defends against symlinks pointing out of the library).
+	const parentReal = await fs.realpath(parent).catch(() => null);
+	if (!parentReal) return null;
+	if (
+		parentReal !== ORIGINALS_ROOT &&
+		!parentReal.startsWith(ORIGINALS_ROOT + path.sep)
+	) {
+		return null;
+	}
+	if (mustExist) {
+		const stat = await fs.stat(abs).catch(() => null);
+		if (!stat) return null;
+	}
+	return abs;
+}
+
+// ── handlers ─────────────────────────────────────────────────────────────────
+
+async function handleRename(req, res, photoUid) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+
+	const body = await readJson(req).catch(() => null);
+	if (!body) return json(res, 400, { error: 'invalid json' });
+
+	const newName = sanitizeFilename(body.newName);
+	if (!newName) return json(res, 400, { error: 'newName must be a plain filename' });
+
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	// Fetch the photo to discover the file's path on disk. The single-photo
+	// endpoint nests Files[0] with Root + Name; the file lookup by UID
+	// (/api/v1/files/:uid) doesn't exist in this build.
+	const photoResp = await pp('GET', `/api/v1/photos/${photoUid}`, token);
+	if (!photoResp.ok) return json(res, photoResp.status, { error: 'photo not found' });
+
+	const photo = photoResp.data;
+	const file =
+		(photo.Files || []).find((f) => f.Primary) || (photo.Files || [])[0];
+	if (!file) return json(res, 404, { error: 'no files on this photo' });
+
+	// Build the absolute current path.
+	const root = (file.Root && file.Root !== '/') ? file.Root : '';
+	const relPath = path.posix.join(root, file.Name);
+	const oldAbs = path.resolve(path.join(ORIGINALS_ROOT, relPath));
+
+	if (!(await ensureWithinOriginals(oldAbs))) {
+		return json(res, 400, { error: 'path escapes originals root' });
+	}
+	const stat = await fs.stat(oldAbs).catch(() => null);
+	if (!stat || !stat.isFile()) return json(res, 404, { error: 'file missing on disk' });
+
+	const newAbs = path.resolve(path.join(path.dirname(oldAbs), newName));
+	if (!(await ensureWithinOriginals(newAbs))) {
+		return json(res, 400, { error: 'new path escapes originals root' });
+	}
+
+	// Refuse to clobber an existing file.
+	if (await fs.stat(newAbs).then(() => true, () => false)) {
+		return json(res, 409, { error: 'target filename already exists' });
+	}
+
+	const oldName = file.Name;
+	console.log(`[rename] ${relPath} -> ${path.posix.join(root, newName)}`);
+	await fs.rename(oldAbs, newAbs);
+
+	// Tell PhotoPrism to re-index the parent so the DB picks up the new path.
+	// `cleanup: true` removes orphan rows for the old filename.
+	const indexResp = await pp(
+		'POST',
+		'/api/v1/index',
+		token,
+		{ path: root || '/', rescan: false, cleanup: true }
+	);
+	if (!indexResp.ok) {
+		// Best-effort: file is renamed, index will catch up eventually.
+		console.warn('[rename] reindex returned', indexResp.status);
+	}
+
+	json(res, 200, {
+		ok: true,
+		oldName,
+		newName,
+		oldRelPath: relPath,
+		newRelPath: path.posix.join(root, newName)
+	});
+}
+
+function handleHealth(_req, res) {
+	json(res, 200, { ok: true, originalsRoot: ORIGINALS_ROOT });
+}
+
+// ── Marks handlers (rating + color) ──────────────────────────────────────────
+
+async function handleMarksListAll(req, res) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+	const all = await loadMarks();
+	json(res, 200, all);
+}
+
+async function handleMarkGet(req, res, uid) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+	const all = await loadMarks();
+	json(res, 200, all[uid] ?? {});
+}
+
+async function handleMarkPut(req, res, uid) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	const patch = sanitizeMarkPatch(body);
+	if (patch === null) return json(res, 400, { error: 'invalid patch' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const all = await loadMarks();
+	const next = mergeMark(all[uid], patch);
+	if (next === null) delete all[uid];
+	else all[uid] = next;
+	await persistMarks();
+	json(res, 200, all[uid] ?? {});
+}
+
+async function handleMarkBulk(req, res) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	if (!body || !Array.isArray(body.ids)) {
+		return json(res, 400, { error: 'ids[] required' });
+	}
+	const patch = sanitizeMarkPatch(body.patch);
+	if (patch === null) return json(res, 400, { error: 'invalid patch' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const all = await loadMarks();
+	const applied = {};
+	for (const uid of body.ids) {
+		if (typeof uid !== 'string' || !uid) continue;
+		const next = mergeMark(all[uid], patch);
+		if (next === null) delete all[uid];
+		else all[uid] = next;
+		applied[uid] = all[uid] ?? {};
+	}
+	await persistMarks();
+	json(res, 200, { count: Object.keys(applied).length, marks: applied });
+}
+
+// ── Folder mutations ────────────────────────────────────────────────────────
+//
+// Each endpoint operates on a relative path under ORIGINALS_ROOT, then
+// triggers PhotoPrism's re-index of the parent so the DB picks up the
+// change. PhotoPrism's "folder" concept is just a directory on disk —
+// there's no DB-side folder entity to mutate.
+
+async function reindex(parentRel, token) {
+	const r = await pp(
+		'POST',
+		'/api/v1/index',
+		token,
+		{ path: parentRel || '/', rescan: false, cleanup: true }
+	);
+	if (!r.ok) console.warn('[folder] reindex returned', r.status);
+}
+
+async function handleFolderCreate(req, res) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	if (!body) return json(res, 400, { error: 'invalid json' });
+	if (typeof body.path !== 'string') return json(res, 400, { error: 'path required' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const abs = await resolveUnderRoot(body.path, { mustExist: false });
+	if (!abs) return json(res, 400, { error: 'invalid path' });
+	if (await fs.stat(abs).then(() => true, () => false)) {
+		return json(res, 409, { error: 'already exists' });
+	}
+	await fs.mkdir(abs, { recursive: false });
+	const rel = path.relative(ORIGINALS_ROOT, abs);
+	console.log('[folder.create]', rel);
+	void reindex(path.posix.dirname('/' + rel), token);
+	json(res, 200, { ok: true, path: rel });
+}
+
+async function handleFolderRename(req, res, rel) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	if (!body) return json(res, 400, { error: 'invalid json' });
+	const newName = sanitizeFilename(body.newName);
+	if (!newName) return json(res, 400, { error: 'newName must be a plain dirname' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const oldAbs = await resolveUnderRoot(rel);
+	if (!oldAbs) return json(res, 400, { error: 'invalid path' });
+	const stat = await fs.stat(oldAbs);
+	if (!stat.isDirectory()) return json(res, 400, { error: 'not a directory' });
+
+	const newAbs = path.join(path.dirname(oldAbs), newName);
+	if (await fs.stat(newAbs).then(() => true, () => false)) {
+		return json(res, 409, { error: 'target already exists' });
+	}
+	if (
+		!newAbs.startsWith(ORIGINALS_ROOT + path.sep) &&
+		newAbs !== ORIGINALS_ROOT
+	) {
+		return json(res, 400, { error: 'target escapes root' });
+	}
+
+	await fs.rename(oldAbs, newAbs);
+	const oldRel = path.relative(ORIGINALS_ROOT, oldAbs);
+	const newRel = path.relative(ORIGINALS_ROOT, newAbs);
+	console.log('[folder.rename]', oldRel, '→', newRel);
+	void reindex(path.posix.dirname('/' + oldRel), token);
+	json(res, 200, { ok: true, oldPath: oldRel, newPath: newRel });
+}
+
+// ── Heap convert (move/copy heap photos into a folder) ─────────────────────
+// PhotoPrism has no native "move all album photos into folder X" operation
+// — it can't because the file-on-disk layout is its source of truth. The
+// flow: list members via q=album:<UID>, fs.rename / fs.copyFile each primary
+// file into the destination, optionally delete the album, then reindex
+// both source and destination so PhotoPrism's DB catches up.
+
+/** Find a non-clobbering destination for `basename` inside `destDir`. If
+ *  `foo.jpg` exists, try `foo-1.jpg`, `foo-2.jpg`, … up to a sane cap. */
+async function uniqueName(destDir, basename) {
+	const ext = path.extname(basename);
+	const stem = basename.slice(0, basename.length - ext.length);
+	for (let i = 0; i < 1000; i++) {
+		const candidate = i === 0 ? basename : `${stem}-${i}${ext}`;
+		const abs = path.join(destDir, candidate);
+		const exists = await fs.stat(abs).then(() => true, () => false);
+		if (!exists) return { abs, name: candidate };
+	}
+	return null;
+}
+
+async function handleHeapConvert(req, res, albumUid) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	if (!body) return json(res, 400, { error: 'invalid json' });
+
+	const mode = body.mode === 'copy' ? 'copy' : 'move';
+	const deleteHeap = mode === 'move' && body.deleteHeap === true;
+	const subfolderRaw = typeof body.subfolder === 'string' ? body.subfolder.trim() : '';
+	const subfolder = subfolderRaw ? sanitizeFilename(subfolderRaw) : null;
+	if (subfolderRaw && !subfolder) {
+		return json(res, 400, { error: 'invalid subfolder name' });
+	}
+
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	// Resolve target folder. Picker passes a relative path under ORIGINALS_ROOT.
+	const targetAbs = await resolveUnderRoot(body.targetFolder);
+	if (!targetAbs) return json(res, 400, { error: 'invalid targetFolder' });
+
+	// Create the optional subfolder (idempotent).
+	let destAbs = targetAbs;
+	if (subfolder) {
+		destAbs = path.join(targetAbs, subfolder);
+		await fs.mkdir(destAbs, { recursive: true });
+	}
+
+	// Fetch the album's photos. PhotoPrism's q-DSL lets us filter by album
+	// UID; merged=true expands to one row per file (we need every variant
+	// in a stack to follow the primary). 1000 covers any realistic heap.
+	const listResp = await pp(
+		'GET',
+		`/api/v1/photos?q=${encodeURIComponent(`album:${albumUid}`)}&count=1000&merged=true`,
+		token
+	);
+	if (!listResp.ok) return json(res, listResp.status, { error: 'list photos failed' });
+	const photos = Array.isArray(listResp.data) ? listResp.data : [];
+
+	// Track source parents so we know which paths to reindex once we're done.
+	const sourceParents = new Set();
+	const errors = [];
+	let moved = 0;
+	let copied = 0;
+
+	for (const photo of photos) {
+		const file =
+			(photo.Files || []).find((f) => f.Primary) || (photo.Files || [])[0];
+		if (!file || typeof file.Name !== 'string') {
+			errors.push({ uid: photo.UID, reason: 'no primary file' });
+			continue;
+		}
+		// PhotoPrism Files[].Name is already originals-relative.
+		const srcRel = file.Name;
+		const srcAbs = path.resolve(path.join(ORIGINALS_ROOT, srcRel));
+		if (!srcAbs.startsWith(ORIGINALS_ROOT + path.sep) && srcAbs !== ORIGINALS_ROOT) {
+			errors.push({ uid: photo.UID, reason: 'path escapes originals' });
+			continue;
+		}
+		const stat = await fs.stat(srcAbs).catch(() => null);
+		if (!stat || !stat.isFile()) {
+			errors.push({ uid: photo.UID, reason: 'file missing on disk' });
+			continue;
+		}
+		// Avoid no-op moves (file already lives in dest).
+		if (path.dirname(srcAbs) === destAbs) {
+			errors.push({ uid: photo.UID, reason: 'already in target' });
+			continue;
+		}
+
+		const basename = path.basename(srcAbs);
+		const target = await uniqueName(destAbs, basename);
+		if (!target) {
+			errors.push({ uid: photo.UID, reason: 'too many collisions' });
+			continue;
+		}
+
+		try {
+			if (mode === 'move') {
+				await fs.rename(srcAbs, target.abs);
+				moved += 1;
+			} else {
+				await fs.copyFile(srcAbs, target.abs);
+				copied += 1;
+			}
+			sourceParents.add(path.dirname(srcRel));
+		} catch (err) {
+			errors.push({
+				uid: photo.UID,
+				reason: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+
+	// Reindex destination + every distinct source parent so PhotoPrism's
+	// DB catches up to the new on-disk layout.
+	const destRel = path.relative(ORIGINALS_ROOT, destAbs);
+	const reindexPaths = new Set(sourceParents);
+	reindexPaths.add(destRel);
+	if (subfolder) reindexPaths.add(path.relative(ORIGINALS_ROOT, targetAbs));
+	for (const p of reindexPaths) {
+		void reindex(p ? '/' + p : '/', token);
+	}
+
+	// Optionally delete the album after a successful move. We don't gate on
+	// `errors.length === 0` — partial successes still warrant heap cleanup
+	// if the user explicitly opted in.
+	let heap_deleted = false;
+	if (deleteHeap) {
+		const delResp = await pp('DELETE', `/api/v1/albums/${albumUid}`, token);
+		heap_deleted = delResp.ok;
+		if (!delResp.ok) {
+			errors.push({ uid: albumUid, reason: `album delete: HTTP ${delResp.status}` });
+		}
+	}
+
+	console.log(
+		`[heap.convert] album=${albumUid} mode=${mode} moved=${moved} copied=${copied} errors=${errors.length} heap_deleted=${heap_deleted}`
+	);
+	json(res, 200, { moved, copied, errors, heap_deleted });
+}
+
+async function handleFolderDelete(req, res, rel) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const abs = await resolveUnderRoot(rel);
+	if (!abs) return json(res, 400, { error: 'invalid path' });
+	if (abs === ORIGINALS_ROOT) return json(res, 400, { error: 'refuse to delete root' });
+	const stat = await fs.stat(abs);
+	if (!stat.isDirectory()) return json(res, 400, { error: 'not a directory' });
+
+	// Safety: only remove if empty. Recursive rm is left to the user via shell
+	// until M5 lands proper file moves.
+	const entries = await fs.readdir(abs);
+	if (entries.length > 0) {
+		return json(res, 409, { error: 'directory not empty' });
+	}
+	await fs.rmdir(abs);
+	console.log('[folder.delete]', rel);
+	void reindex(path.posix.dirname('/' + rel), token);
+	json(res, 200, { ok: true, path: rel });
+}
+
+// ── Cross-folder duplicate scan ─────────────────────────────────────────────
+//
+// PhotoPrism silently drops byte-identical files at index time, so duplicates
+// across folders never enter its DB. This sidecar scans ORIGINALS_ROOT
+// directly: walk every file, pre-filter by size (files with unique sizes
+// can't be hash-duplicates so we skip hashing them), sha1 the rest, and
+// return groups of ≥2 files that share a hash.
+//
+// Resolution archives the unwanted copies into a `.duplicates/` quarantine
+// folder under ORIGINALS_ROOT — PhotoPrism's indexer ignores dotfile dirs,
+// so the moved files stop appearing in the index. Recoverable by moving
+// them back to a regular subfolder + reindex.
+
+const QUARANTINE_DIR = '.duplicates';
+const SUPPORTED_EXTS = new Set([
+	'.jpg', '.jpeg', '.png', '.heic', '.heif', '.tiff', '.tif',
+	'.gif', '.bmp', '.webp', '.avif',
+	'.mov', '.mp4', '.m4v', '.avi', '.mkv', '.webm',
+	'.dng', '.cr2', '.cr3', '.nef', '.arw', '.orf', '.rw2', '.raw'
+]);
+
+async function walkFiles(rootAbs) {
+	/** @type {{ relPath: string, absPath: string, size: number }[]} */
+	const out = [];
+	async function recurse(dir) {
+		let entries;
+		try {
+			entries = await fs.readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const ent of entries) {
+			// Skip dotfile/dotdir (matches PhotoPrism's indexer behaviour
+			// + our own quarantine dir).
+			if (ent.name.startsWith('.')) continue;
+			const abs = path.join(dir, ent.name);
+			if (ent.isDirectory()) {
+				await recurse(abs);
+				continue;
+			}
+			if (!ent.isFile()) continue;
+			const ext = path.extname(ent.name).toLowerCase();
+			if (!SUPPORTED_EXTS.has(ext)) continue;
+			let st;
+			try {
+				st = await fs.stat(abs);
+			} catch {
+				continue;
+			}
+			out.push({
+				relPath: path.relative(rootAbs, abs),
+				absPath: abs,
+				size: st.size
+			});
+		}
+	}
+	await recurse(rootAbs);
+	return out;
+}
+
+async function sha1File(absPath) {
+	return new Promise((resolve, reject) => {
+		const hash = createHash('sha1');
+		createReadStream(absPath)
+			.on('data', (chunk) => hash.update(chunk))
+			.on('end', () => resolve(hash.digest('hex')))
+			.on('error', reject);
+	});
+}
+
+async function scanDuplicates(token) {
+	const all = await walkFiles(ORIGINALS_ROOT);
+
+	// Group by size first; hashes only fire for size collisions. For a
+	// typical library this skips ~95% of the IO+CPU.
+	/** @type {Map<number, typeof all>} */
+	const bySize = new Map();
+	for (const f of all) {
+		const arr = bySize.get(f.size);
+		if (arr) arr.push(f);
+		else bySize.set(f.size, [f]);
+	}
+
+	/** @type {Map<string, { hash: string, size: number, files: typeof all }>} */
+	const groups = new Map();
+	for (const [size, group] of bySize) {
+		if (group.length < 2) continue;
+		// Concurrently hash each file in this size bucket.
+		const hashes = await Promise.all(group.map((f) => sha1File(f.absPath)));
+		for (let i = 0; i < group.length; i++) {
+			const h = hashes[i];
+			const g = groups.get(h);
+			if (g) g.files.push(group[i]);
+			else groups.set(h, { hash: h, size, files: [group[i]] });
+		}
+	}
+
+	// Filter to groups with ≥2 files (size collisions where hashes differed
+	// produce singleton entries we drop here). For each surviving group,
+	// ask PhotoPrism which path it has indexed — that becomes the default
+	// "keep" candidate so the user doesn't accidentally archive the only
+	// indexed copy.
+	const out = [];
+	for (const g of groups.values()) {
+		if (g.files.length < 2) continue;
+		let indexedPath = null;
+		try {
+			const r = await pp(
+				'GET',
+				`/api/v1/photos?q=hash:${g.hash}&count=1&merged=true`,
+				token
+			);
+			if (r.ok && Array.isArray(r.data) && r.data[0]) {
+				const photo = r.data[0];
+				const primary =
+					(photo.Files || []).find((f) => f.Primary) ||
+					(photo.Files || [])[0];
+				if (primary?.Name) indexedPath = primary.Name;
+			}
+		} catch {
+			/* swallow — best-effort hint */
+		}
+		out.push({
+			hash: g.hash,
+			size: g.size,
+			indexedPath,
+			files: g.files.map((f) => ({ path: f.relPath, size: f.size }))
+		});
+	}
+	// Sort groups by size descending so the biggest disk wins float to top.
+	out.sort((a, b) => b.size * (b.files.length - 1) - a.size * (a.files.length - 1));
+	return out;
+}
+
+async function handleDupScan(req, res) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+	const started = Date.now();
+	console.log('[dup.scan] starting walk under', ORIGINALS_ROOT);
+	const groups = await scanDuplicates(token);
+	const ms = Date.now() - started;
+	console.log(`[dup.scan] ${groups.length} groups in ${ms} ms`);
+	json(res, 200, { groups, scannedMs: ms });
+}
+
+async function handleDupArchive(req, res) {
+	const token = req.headers['x-auth-token'];
+	if (!token || Array.isArray(token)) return json(res, 401, { error: 'no token' });
+	const body = await readJson(req).catch(() => null);
+	if (!body || !Array.isArray(body.paths)) {
+		return json(res, 400, { error: 'paths[] required' });
+	}
+	if (!(await validateSession(token))) return json(res, 401, { error: 'invalid session' });
+
+	const moved = [];
+	const errors = [];
+	const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+	const targetDir = path.join(ORIGINALS_ROOT, QUARANTINE_DIR, stamp);
+	await fs.mkdir(targetDir, { recursive: true });
+
+	for (const rel of body.paths) {
+		try {
+			const abs = await resolveUnderRoot(rel);
+			if (!abs) {
+				errors.push({ path: rel, error: 'invalid path' });
+				continue;
+			}
+			// Use the file's basename as the quarantine name; prepend a
+			// short slice of its parent dir if a collision would happen so
+			// two `IMG_0001.jpg` from different folders don't overwrite
+			// each other in the same quarantine batch.
+			let dest = path.join(targetDir, path.basename(abs));
+			let i = 1;
+			while (await fs.stat(dest).then(() => true, () => false)) {
+				const parsed = path.parse(path.basename(abs));
+				dest = path.join(targetDir, `${parsed.name}__${i}${parsed.ext}`);
+				i++;
+			}
+			await fs.rename(abs, dest);
+			moved.push({
+				from: rel,
+				to: path.relative(ORIGINALS_ROOT, dest)
+			});
+			console.log('[dup.archive]', rel, '→', path.relative(ORIGINALS_ROOT, dest));
+		} catch (err) {
+			errors.push({
+				path: rel,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+
+	// Trigger a cleanup reindex so PhotoPrism drops any photo entries whose
+	// underlying file is now in the quarantine dir (out of its scan path).
+	if (moved.length > 0) {
+		void pp('POST', '/api/v1/index', token, {
+			path: '/',
+			rescan: false,
+			cleanup: true
+		});
+	}
+
+	json(res, 200, { moved, errors });
+}
+
+// ── router ───────────────────────────────────────────────────────────────────
+
+const RENAME_RE = /^\/api\/sidecar\/files\/([^/]+)\/rename$/;
+const FOLDER_CREATE_RE = /^\/api\/sidecar\/folders$/;
+const FOLDER_RENAME_RE = /^\/api\/sidecar\/folders\/(.+)\/rename$/;
+const FOLDER_DELETE_RE = /^\/api\/sidecar\/folders\/(.+)$/;
+const MARKS_BULK_RE = /^\/api\/sidecar\/photos\/marks\/bulk$/;
+const MARKS_ALL_RE = /^\/api\/sidecar\/photos\/marks$/;
+const MARKS_ONE_RE = /^\/api\/sidecar\/photos\/([^/]+)\/marks$/;
+const HEAP_CONVERT_RE = /^\/api\/sidecar\/albums\/([^/]+)\/convert$/;
+const DUP_SCAN_RE = /^\/api\/sidecar\/duplicates\/scan$/;
+const DUP_ARCHIVE_RE = /^\/api\/sidecar\/duplicates\/archive$/;
+
+const server = http.createServer(async (req, res) => {
+	try {
+		const url = new URL(req.url ?? '/', 'http://localhost');
+		const p = url.pathname;
+
+		if (p === '/api/sidecar/healthz' && req.method === 'GET') {
+			return handleHealth(req, res);
+		}
+		// Cross-folder duplicate detection.
+		if (DUP_SCAN_RE.test(p) && req.method === 'GET') {
+			return handleDupScan(req, res);
+		}
+		if (DUP_ARCHIVE_RE.test(p) && req.method === 'POST') {
+			return handleDupArchive(req, res);
+		}
+		// Marks routes — bulk match first so "marks/bulk" doesn't get
+		// captured by the "{uid}/marks" pattern.
+		if (MARKS_BULK_RE.test(p) && req.method === 'POST') {
+			return handleMarkBulk(req, res);
+		}
+		if (MARKS_ALL_RE.test(p) && req.method === 'GET') {
+			return handleMarksListAll(req, res);
+		}
+		const markM = MARKS_ONE_RE.exec(p);
+		if (markM) {
+			if (req.method === 'GET') return handleMarkGet(req, res, markM[1]);
+			if (req.method === 'PUT') return handleMarkPut(req, res, markM[1]);
+		}
+		const fileM = RENAME_RE.exec(p);
+		if (fileM && req.method === 'POST') {
+			return handleRename(req, res, fileM[1]);
+		}
+		if (FOLDER_CREATE_RE.test(p) && req.method === 'POST') {
+			return handleFolderCreate(req, res);
+		}
+		const renameFolderM = FOLDER_RENAME_RE.exec(p);
+		if (renameFolderM && req.method === 'POST') {
+			return handleFolderRename(req, res, decodeURIComponent(renameFolderM[1]));
+		}
+		const deleteFolderM = FOLDER_DELETE_RE.exec(p);
+		if (deleteFolderM && req.method === 'DELETE') {
+			// Avoid matching the rename URL which has a trailing /rename.
+			if (!p.endsWith('/rename')) {
+				return handleFolderDelete(req, res, decodeURIComponent(deleteFolderM[1]));
+			}
+		}
+		const heapConvertM = HEAP_CONVERT_RE.exec(p);
+		if (heapConvertM && req.method === 'POST') {
+			return handleHeapConvert(req, res, heapConvertM[1]);
+		}
+		json(res, 404, { error: 'no route' });
+	} catch (err) {
+		console.error(err);
+		json(res, 500, { error: err instanceof Error ? err.message : String(err) });
+	}
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+	console.log(
+		`mule-sidecar listening on http://127.0.0.1:${PORT} (originals=${ORIGINALS_ROOT})`
+	);
+});