@viralspin/mcp 0.4.0 → 0.5.2

package/dist/organizer/edit.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.labelsAfter = labelsAfter;
+exports.regroup = regroup;
+exports.backfillEmbeddings = backfillEmbeddings;
+exports.applyOps = applyOps;
+/**
+ * Changes after the sort, without reading the pictures again: add or drop a label ("tennis"), combine folders, rename one, hide one. The scan kept
+ * every picture's embedding next to the plan (<plan>.emb, float32 rows), so a new label is a dot product per picture: seconds for 29k pictures.
+ * Every change is kept on the plan (`ops`) and replayed in order, so a later label does not undo an earlier merge.
+ */
+const fs_1 = __importDefault(require("fs"));
+const plan_1 = require("./plan");
+const path_1 = __importDefault(require("path"));
+const images_1 = require("./images");
+const topics_1 = require("./topics");
+const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+/** The creator's labels after the ops: the ones the sort started with, plus added ones, minus removed ones. */
+function labelsAfter(start, ops) {
+    let out = [...start];
+    for (const o of ops) {
+        if (o.op === "add_label" && !out.some((l) => same(l, o.label)))
+            out.push(o.label.trim());
+        if (o.op === "remove_label")
+            out = out.filter((l) => !same(l, o.label));
+    }
+    return out;
+}
+/** Merges, renames and hides, in order, on the items' bucket names (labels are not touched). Pure. */
+function regroup(plan, ops) {
+    for (const o of ops) {
+        const out = o.op === "exclude" ? new Set(o.items) : null;
+        plan.items.forEach((it, i) => {
+            if (!it.topic)
+                return;
+            // "not tennis": these pictures leave that folder for their next label (or Other), and stay out on every later change
+            if (o.op === "exclude" && out.has(i) && same(o.bucket, it.topic)) {
+                it.topic = it.tags?.find((t) => !same(t, o.bucket)) ?? "Other";
+                return;
+            }
+            if (o.op === "merge" && o.from.some((f) => same(f, it.topic)))
+                it.topic = o.into.trim();
+            if (o.op === "rename" && same(o.from, it.topic))
+                it.topic = o.to.trim();
+            if (o.op === "hide" && same(o.bucket, it.topic))
+                it.topic = "Hidden";
+        });
+    }
+}
+/** Apply new ops to a saved plan (and its embeddings, for label changes). Returns a line saying what changed. */
+/**
+ * A sort made before fingerprints were kept: make them once, from the small previews it already saved on this computer (480px, so this never
+ * goes back to the original drive), or the original file when a preview is missing. About 0.15 s a picture; every change afterwards is instant.
+ */
+async function backfillEmbeddings(plan, embPath, onProgress) {
+    const clf = await (0, topics_1.labeller)((0, topics_1.labelSet)(plan.labels ?? []));
+    if (!clf)
+        throw new Error("The picture model is not available on this computer.");
+    const todo = plan.items.map((_, i) => i).filter((i) => plan.items[i].dupOf === undefined);
+    let buf = null;
+    let d = 512, n = 0;
+    const t0 = Date.now();
+    for (const i of todo) {
+        const it = plan.items[i];
+        const src = it.thumb && fs_1.default.existsSync(it.thumb) ? { file: it.thumb, kind: "image" } : { file: path_1.default.join(plan.root, it.rel), kind: it.kind };
+        try {
+            const rgb = await (0, images_1.rgb224)(src.file, src.kind);
+            const l = rgb ? await clf(rgb, 224, 224) : null;
+            if (l?.emb) {
+                if (!buf) {
+                    d = l.emb.length;
+                    buf = new Float32Array(plan.items.length * d);
+                }
+                buf.set(l.emb, i * d);
+            }
+        }
+        catch { /* leave this row empty: it stays where it was */ }
+        if (++n % 20 === 0 || n === todo.length)
+            onProgress?.(n, todo.length, Math.round(((Date.now() - t0) / n) * (todo.length - n)));
+    }
+    fs_1.default.writeFileSync(embPath, Buffer.from((buf ?? new Float32Array(0)).buffer));
+}
+async function applyOps(planPath, embPath, add, onProgress) {
+    const plan = JSON.parse(fs_1.default.readFileSync(planPath, "utf8"));
+    if (plan.by !== "topic")
+        throw new Error("Changing folders needs a sort By topic.");
+    const ops = [...(plan.ops ?? []), ...add];
+    const before = new Map();
+    for (const it of plan.items)
+        if (it.topic && it.dupOf === undefined)
+            before.set(it.topic, (before.get(it.topic) ?? 0) + 1);
+    if (add.some((o) => o.op === "add_label" || o.op === "remove_label")) {
+        if (!fs_1.default.existsSync(embPath))
+            await backfillEmbeddings(plan, embPath, onProgress);
+        const set = (0, topics_1.labelSet)(labelsAfter(plan.labels ?? [], ops));
+        const T = await (0, topics_1.textEmbeddings)(set);
+        if (!T)
+            throw new Error("The picture model is not available on this computer.");
+        const d = T[0].length;
+        const raw = fs_1.default.readFileSync(embPath);
+        const E = new Float32Array(raw.buffer, raw.byteOffset, Math.floor(raw.byteLength / 4));
+        const found = plan.items.map((it, i) => {
+            if (it.dupOf !== undefined || (i + 1) * d > E.length)
+                return undefined;
+            const row = E.subarray(i * d, (i + 1) * d);
+            return row.some((x) => x !== 0) ? (0, topics_1.labelsFromEmbedding)(row, T, set) : { tags: [], best: null };
+        });
+        const bucket = (0, topics_1.bucketFor)(found, set);
+        plan.items.forEach((it, i) => { if (found[i]) {
+            it.topic = bucket[i] ?? "Other";
+            it.tags = found[i].tags;
+        } });
+        regroup(plan, ops); // every merge / rename / hide so far, on top of the fresh labels
+    }
+    else
+        regroup(plan, add); // only the new ones: the earlier ones are already in the items
+    plan.ops = ops;
+    // labels already fold small subjects into their group (bucketFor), so nothing is folded again here: a label the creator asked for keeps its card even with one picture
+    plan.buckets = (0, plan_1.planBuckets)(plan.items, { by: "topic", minBucket: 1 }).filter((b) => b.name !== "Hidden");
+    plan.moves = (0, plan_1.planMoves)(plan.root, plan.items, plan.buckets);
+    plan.totals = (0, plan_1.summarize)(plan.items, plan.buckets);
+    fs_1.default.writeFileSync(planPath, JSON.stringify(plan));
+    const after = new Map();
+    for (const it of plan.items)
+        if (it.topic && it.dupOf === undefined)
+            after.set(it.topic, (after.get(it.topic) ?? 0) + 1);
+    const lines = [];
+    for (const o of add) {
+        if (o.op === "add_label") {
+            const n = [...after.entries()].find(([k]) => same(k, o.label))?.[1] ?? 0;
+            lines.push(n ? `${o.label}: ${n.toLocaleString()} pictures` : `${o.label}: no pictures matched`);
+        }
+        if (o.op === "remove_label")
+            lines.push(`Dropped the ${o.label} label`);
+        if (o.op === "merge")
+            lines.push(`Combined ${o.from.join(", ")} into ${o.into} (${(after.get(o.into.trim()) ?? 0).toLocaleString()})`);
+        if (o.op === "rename")
+            lines.push(`Renamed ${o.from} to ${o.to}`);
+        if (o.op === "exclude")
+            lines.push(`Took ${o.items.length} out of ${o.bucket}`);
+        if (o.op === "hide")
+            lines.push(`Hid ${o.bucket} (${(before.get(o.bucket) ?? 0).toLocaleString()} pictures stay on your computer)`);
+    }
+    return { plan, note: lines.join(" · ") || "No change" };
+}

package/dist/organizer/images.js

@@ -0,0 +1,231 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_W = void 0;
+exports.ffmpegPath = ffmpegPath;
+exports.hasFfmpeg = hasFfmpeg;
+exports.canReadPictures = canReadPictures;
+exports.dhash = dhash;
+exports.makeThumb = makeThumb;
+exports.makePreview = makePreview;
+exports.rgb224 = rgb224;
+exports.fileMeta = fileMeta;
+exports.takenMonth = takenMonth;
+/**
+ * Pixels for the organizer: a 64-bit picture hash and a small thumbnail. `sharp` (libvips, prebuilt, shrink-on-load, far faster than a process per picture)
+ * when it is installed; otherwise ffmpeg (VIRALSPIN_FFMPEG, the connector's own kit, or PATH). Video thumbnails always need ffmpeg and are skipped without it.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+let sharpMod;
+async function sharp() {
+    if (sharpMod === undefined) {
+        try {
+            const m = await Promise.resolve().then(() => __importStar(require("sharp")));
+            sharpMod = m.default ?? m;
+            sharpMod.cache(false);
+        }
+        catch {
+            sharpMod = null;
+        }
+    }
+    return sharpMod;
+}
+/** Where ffmpeg is: VIRALSPIN_FFMPEG, the connector's own kit, or PATH. */
+function ffmpegPath() {
+    if (process.env.VIRALSPIN_FFMPEG)
+        return process.env.VIRALSPIN_FFMPEG;
+    const exe = process.platform === "win32" ? "ffmpeg.exe" : "ffmpeg";
+    for (const d of [path_1.default.join(os_1.default.homedir(), ".viralspin", "kit", "bin"), path_1.default.join(os_1.default.homedir(), ".viralspin", "ffmpeg")]) {
+        const p = path_1.default.join(d, exe);
+        if (fs_1.default.existsSync(p))
+            return p;
+    }
+    return "ffmpeg";
+}
+let ffOk;
+function hasFfmpeg() {
+    if (ffOk !== undefined)
+        return Promise.resolve(ffOk);
+    return new Promise((res) => (0, child_process_1.execFile)(ffmpegPath(), ["-version"], (e) => { ffOk = !e; res(ffOk); }));
+}
+/** Can this computer make picture hashes at all (sharp or ffmpeg)? Used to say so plainly instead of failing quietly. */
+async function canReadPictures() { return !!(await sharp()) || (await hasFfmpeg()); }
+const dhashOf = (b) => {
+    if (b.length < 72)
+        return null;
+    let bits = "";
+    for (let y = 0; y < 8; y++)
+        for (let x = 0; x < 8; x++)
+            bits += b[y * 9 + x] > b[y * 9 + x + 1] ? "1" : "0";
+    let h = "";
+    for (let i = 0; i < 64; i += 4)
+        h += parseInt(bits.slice(i, i + 4), 2).toString(16);
+    return h;
+};
+/** 64-bit difference hash: a 9x8 greyscale shrink, each pixel compared with its right neighbour. Null when the picture can not be read. */
+async function dhash(file) {
+    const s = await sharp();
+    if (s) {
+        try {
+            return dhashOf(await s(file, { failOn: "none" }).rotate().resize(9, 8, { fit: "fill" }).greyscale().raw().toBuffer());
+        }
+        catch { /* fall through to ffmpeg */ }
+    }
+    return new Promise((res) => {
+        const ff = (0, child_process_1.spawn)(ffmpegPath(), ["-v", "error", "-i", file, "-vframes", "1", "-vf", "scale=9:8:flags=area,format=gray", "-f", "rawvideo", "-"]);
+        const bufs = [];
+        ff.stdout.on("data", (d) => bufs.push(d));
+        ff.on("error", () => res(null));
+        ff.on("close", () => res(dhashOf(Buffer.concat(bufs))));
+    });
+}
+/** A 480px-wide jpeg thumbnail of a picture, or the first second of a clip. False when it could not be made. */
+async function makeThumb(file, kind, dst) {
+    const s = kind === "image" ? await sharp() : null;
+    if (s) {
+        try {
+            await s(file, { failOn: "none" }).rotate().resize({ width: 480, withoutEnlargement: true }).jpeg({ quality: 70 }).toFile(dst);
+            return fs_1.default.existsSync(dst);
+        }
+        catch { /* fall through */ }
+    }
+    return new Promise((res) => {
+        const ff = (0, child_process_1.spawn)(ffmpegPath(), ["-v", "error", "-y", ...(kind === "video" ? ["-ss", "1"] : []), "-i", file, "-vframes", "1", "-vf", "scale=480:-2", "-q:v", "5", dst]);
+        ff.on("error", () => res(false));
+        ff.on("close", (c) => res(c === 0 && fs_1.default.existsSync(dst)));
+    });
+}
+/** A large (up to PREVIEW_W px wide) jpeg of a picture, for full-screen viewing and zooming in: the 480 px thumbnail is soft on a big screen. False when it could not be made. */
+exports.PREVIEW_W = 2400;
+async function makePreview(file, dst, kind = "image") {
+    // a clip's still: a frame about a second in (the first is often black or mid-fade); a clip shorter than that falls back to its first frame
+    if (kind === "video")
+        return (await ffFrame(file, dst, ["-ss", "1"])) || ffFrame(file, dst, []);
+    const s = await sharp();
+    if (s) {
+        try {
+            await s(file, { failOn: "none" }).rotate().resize({ width: exports.PREVIEW_W, withoutEnlargement: true }).jpeg({ quality: 86 }).toFile(dst);
+            return fs_1.default.existsSync(dst);
+        }
+        catch { /* fall through */ }
+    }
+    return ffFrame(file, dst, []);
+}
+function ffFrame(file, dst, seek) {
+    return new Promise((res) => {
+        const ff = (0, child_process_1.spawn)(ffmpegPath(), ["-v", "error", "-y", ...seek, "-i", file, "-vframes", "1", "-vf", `scale='min(${exports.PREVIEW_W},iw)':-2`, "-q:v", "2", dst]);
+        ff.on("error", () => res(false));
+        ff.on("close", (c) => res(c === 0 && fs_1.default.existsSync(dst) && fs_1.default.statSync(dst).size > 0));
+    });
+}
+/** A 224x224 RGB picture (cover-cropped) for the topic model: sharp for a picture, a frame at about 1 s for a clip. Null when it can not be read. */
+async function rgb224(file, kind) {
+    const s = kind === "image" ? await sharp() : null;
+    if (s) {
+        try {
+            return await s(file, { failOn: "none" }).rotate().resize(224, 224, { fit: "cover" }).removeAlpha().toColourspace("srgb").raw().toBuffer();
+        }
+        catch { /* fall through */ }
+    }
+    return new Promise((res) => {
+        const ff = (0, child_process_1.spawn)(ffmpegPath(), ["-v", "error", ...(kind === "video" ? ["-ss", "1"] : []), "-i", file, "-vframes", "1", "-vf", "scale=224:224:force_original_aspect_ratio=increase,crop=224:224", "-pix_fmt", "rgb24", "-f", "rawvideo", "-"]);
+        const bufs = [];
+        ff.stdout.on("data", (d) => bufs.push(d));
+        ff.on("error", () => res(null));
+        ff.on("close", () => { const b = Buffer.concat(bufs); res(b.length >= 224 * 224 * 3 ? b.subarray(0, 224 * 224 * 3) : null); });
+    });
+}
+/**
+ * What the viewer shows about one file: its pixel size (as displayed, so a rotated phone photo reads portrait), when it was taken (EXIF
+ * DateTimeOriginal, to the second) and, for a clip, how long it runs. Every field is best effort: sharp for pictures, ffmpeg's banner for clips
+ * and for anything sharp can't open (HEIC without libheif); null when neither knows.
+ */
+async function fileMeta(file, kind) {
+    const out = { width: null, height: null, taken: null, duration: null };
+    const s = kind === "image" ? await sharp() : null;
+    if (s) {
+        try {
+            const m = await s(file, { failOn: "none" }).metadata();
+            const turned = (m.orientation ?? 1) >= 5;
+            out.width = (turned ? m.height : m.width) ?? null;
+            out.height = (turned ? m.width : m.height) ?? null;
+            const d = m.exif ? /(\d{4}):(\d{2}):(\d{2}) (\d{2}):(\d{2}):(\d{2})/.exec(m.exif.toString("latin1")) : null;
+            if (d && +d[1] > 1990)
+                out.taken = `${d[1]}-${d[2]}-${d[3]}T${d[4]}:${d[5]}:${d[6]}`;
+        }
+        catch { /* ffmpeg below */ }
+    }
+    if (out.width && (kind === "image"))
+        return out;
+    await new Promise((res) => {
+        (0, child_process_1.execFile)(ffmpegPath(), ["-hide_banner", "-i", file], { timeout: 15000 }, (_e, _o, err) => {
+            const t = String(err || "");
+            const v = /Stream #[^\n]*Video:[^\n]*?(\d{2,5})x(\d{2,5})/.exec(t), rot = /rotate\s*:\s*-?(90|270)|rotation of -?(90|270)/.exec(t);
+            if (v && !out.width) {
+                const w = +v[1], h = +v[2];
+                out.width = rot ? h : w;
+                out.height = rot ? w : h;
+            }
+            const du = /Duration: (\d+):(\d+):(\d+(?:\.\d+)?)/.exec(t);
+            if (du)
+                out.duration = +du[1] * 3600 + +du[2] * 60 + +du[3];
+            const c = /creation_time\s*:\s*(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})/.exec(t);
+            if (c && !out.taken)
+                out.taken = `${c[1]}T${c[2]}`;
+            res();
+        });
+    });
+    return out;
+}
+/** "YYYY-MM" a picture was taken, from its EXIF DateTimeOriginal (sharp reads only the header), or null. */
+async function takenMonth(file) {
+    const s = await sharp();
+    if (!s)
+        return null;
+    try {
+        const meta = await s(file, { failOn: "none" }).metadata();
+        const m = meta.exif ? /(\d{4}):(\d{2}):\d{2} \d{2}:\d{2}:\d{2}/.exec(meta.exif.toString("latin1")) : null;
+        return m && +m[1] > 1990 && +m[2] >= 1 && +m[2] <= 12 ? `${m[1]}-${m[2]}` : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/organizer/plan.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeName = exports.kindOf = exports.ORGANIZED_DIR = exports.VID = exports.IMG = void 0;
+exports.hamming = hamming;
+exports.markDuplicates = markDuplicates;
+exports.planBuckets = planBuckets;
+exports.planMoves = planMoves;
+exports.summarize = summarize;
+exports.applyMoves = applyMoves;
+exports.undoMoves = undoMoves;
+// Pure planning + safe-move helpers for the folder organizer (no network, no vision, no ffmpeg), so they are testable.
+// The scan (scan.ts) fills `items`; this turns them into buckets and a PROPOSED list of moves. Nothing here touches the
+// disk except applyMoves / undoMoves, and those only ever rename: never delete, never overwrite.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.IMG = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic", ".bmp", ".tif", ".tiff"]);
+exports.VID = new Set([".mp4", ".mov", ".webm", ".m4v", ".avi", ".mkv"]);
+exports.ORGANIZED_DIR = "_Organized";
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const kindOf = (file) => { const e = path_1.default.extname(file).toLowerCase(); return exports.VID.has(e) ? "video" : exports.IMG.has(e) ? "image" : null; };
+exports.kindOf = kindOf;
+/** A folder-safe bucket name. */
+const safeName = (s) => (String(s || "").replace(/[<>:"/\\|?*\x00-\x1f]/g, " ").replace(/\s+/g, " ").trim().replace(/[. ]+$/, "").slice(0, 60)) || "Misc";
+exports.safeName = safeName;
+const titleCase = (s) => s.replace(/\b[a-z]/g, (c) => c.toUpperCase());
+/** Hamming distance of two 64-bit hashes given as 16-char hex strings. */
+function hamming(a, b) {
+    let d = 0;
+    for (let i = 0; i < 16; i++) {
+        let x = parseInt(a[i], 16) ^ parseInt(b[i], 16);
+        while (x) {
+            d += x & 1;
+            x >>= 1;
+        }
+    }
+    return d;
+}
+/** Mark every copy after the first as a duplicate of it: identical content hash, or (images) a near-identical picture hash. The oldest file is the original. */
+function markDuplicates(items, { near = 4 } = {}) {
+    const order = items.map((_, i) => i).sort((a, b) => items[a].mtime - items[b].mtime || items[a].rel.localeCompare(items[b].rel));
+    const byHash = new Map();
+    const seenD = [];
+    for (const i of order) {
+        const it = items[i];
+        if (it.hash) {
+            const hit = byHash.get(it.hash);
+            if (hit !== undefined) {
+                it.dupOf = hit;
+                it.dupKind = "exact";
+                continue;
+            }
+            byHash.set(it.hash, i);
+        }
+        if (it.dhash && it.kind === "image") {
+            const hit = seenD.find((j) => hamming(items[j].dhash, it.dhash) <= near);
+            if (hit !== undefined) {
+                it.dupOf = hit;
+                it.dupKind = "near";
+                continue;
+            }
+            seenD.push(i);
+        }
+    }
+    return items.filter((x) => x.dupOf !== undefined).length;
+}
+/** The label a picture goes under, per way of sorting. */
+function bucketOf(it, by) {
+    if (by === "type")
+        return { kind: "type", name: it.kind === "video" ? "Videos" : "Pictures" };
+    if (by === "date") {
+        const d = new Date(it.mtime);
+        return { kind: "date", name: `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")} ${MONTHS[d.getUTCMonth()]}` };
+    }
+    if (by === "topic") {
+        if (it.topic)
+            return { kind: "topic", name: (0, exports.safeName)(it.topic) }; // the on-device topic model's label, kept as written
+        const s = (it.subject || it.tags?.[0] || "").trim().toLowerCase();
+        return s ? { kind: "topic", name: titleCase((0, exports.safeName)(s)) } : { kind: "topic", name: "Unsorted" };
+    }
+    // folder: the first folder under the root (a file at the root goes under "Loose")
+    const parts = it.rel.split(/[\\/]/);
+    return { kind: "folder", name: parts.length > 1 ? (0, exports.safeName)(parts[0]) : "Loose" };
+}
+/**
+ * Buckets for the scan. Extra copies always go to one "Duplicates" bucket (moved, never deleted); the rest by `by`: folder | date | topic | type.
+ * Tiny topic buckets (< minBucket) fold into "Other" so 300 one-picture folders do not appear.
+ */
+function planBuckets(items, { by = "folder", minBucket = 3 } = {}) {
+    const map = new Map();
+    const add = (kind, name, i, media) => { const k = `${kind}:${media ?? "any"}:${name}`; if (!map.has(k))
+        map.set(k, { id: k, name, kind, media, items: [] }); map.get(k).items.push(i); };
+    items.forEach((it, i) => {
+        if (it.dupOf !== undefined)
+            return add("duplicates", "Duplicates", i);
+        const b = bucketOf(it, by);
+        add(b.kind, b.name, i, it.live ? "live" : it.kind); // a Live Photo (still + its clip) sits in its own section: motion for 7-second reels
+    });
+    let buckets = [...map.values()];
+    if (by === "topic") {
+        const small = buckets.filter((b) => b.kind === "topic" && b.name !== "Unsorted" && b.items.length < minBucket);
+        if (small.length) {
+            // per side: tiny picture buckets join the pictures' Other, tiny clip buckets the clips'
+            for (const media of ["image", "video", "live"]) {
+                const mine = small.filter((b) => b.media === media);
+                if (!mine.length)
+                    continue;
+                const into = buckets.find((b) => b.kind === "topic" && b.media === media && b.name === "Other" && !mine.includes(b));
+                if (into)
+                    into.items.push(...mine.flatMap((b) => b.items));
+                else
+                    buckets.push({ id: `topic:${media}:Other`, name: "Other", kind: "topic", media, items: mine.flatMap((b) => b.items) });
+            }
+            buckets = buckets.filter((b) => !small.includes(b));
+        }
+    }
+    return buckets.sort((a, b) => Number(a.kind === "duplicates") - Number(b.kind === "duplicates") || b.items.length - a.items.length || a.name.localeCompare(b.name));
+}
+/** Where each file would go. `root` is the scanned folder; everything lands in <root>/_Organized/<bucket>/ and keeps its file name. */
+function planMoves(root, items, buckets) {
+    const moves = [];
+    const taken = new Set();
+    for (const b of buckets) {
+        for (const i of b.items) {
+            const it = items[i];
+            const from = path_1.default.join(root, it.rel);
+            const dir = path_1.default.join(root, exports.ORGANIZED_DIR, (0, exports.safeName)(b.name));
+            const ext = path_1.default.extname(it.rel), stem = path_1.default.basename(it.rel, ext);
+            let to = path_1.default.join(dir, stem + ext), n = 1;
+            while (taken.has(to.toLowerCase()))
+                to = path_1.default.join(dir, `${stem} (${++n})${ext}`);
+            taken.add(to.toLowerCase());
+            moves.push({ from, to });
+        }
+    }
+    return moves;
+}
+function summarize(items, buckets) {
+    return {
+        files: items.length,
+        images: items.filter((x) => x.kind === "image").length,
+        videos: items.filter((x) => x.kind === "video").length,
+        bytes: items.reduce((s, x) => s + (x.size || 0), 0),
+        dupes: items.filter((x) => x.dupOf !== undefined).length,
+        buckets: buckets.length,
+    };
+}
+/**
+ * Do the moves. Only renames; a destination that already exists gets a " (n)" suffix, never overwritten; a source that is gone is skipped.
+ * The undo manifest is rewritten as it goes, so a crash halfway is still reversible.
+ */
+function applyMoves(root, moves, id) {
+    const dir = path_1.default.join(root, exports.ORGANIZED_DIR);
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const manifest = path_1.default.join(dir, `.viralspin-undo-${id}.json`);
+    const done = [];
+    let skipped = 0;
+    for (const m of moves) {
+        try {
+            if (!fs_1.default.existsSync(m.from)) {
+                skipped++;
+                continue;
+            }
+            fs_1.default.mkdirSync(path_1.default.dirname(m.to), { recursive: true });
+            let to = m.to, n = 1;
+            const ext = path_1.default.extname(to), stem = to.slice(0, to.length - ext.length);
+            while (fs_1.default.existsSync(to))
+                to = `${stem} (${++n})${ext}`;
+            fs_1.default.renameSync(m.from, to);
+            done.push({ from: m.from, to });
+            if (done.length % 25 === 0)
+                fs_1.default.writeFileSync(manifest, JSON.stringify(done));
+        }
+        catch {
+            skipped++;
+        }
+    }
+    fs_1.default.writeFileSync(manifest, JSON.stringify(done));
+    return { moved: done.length, skipped, manifest };
+}
+/** Put every moved file back (newest first). A file that is no longer where it was put, or whose old spot is taken, is left alone and counted. */
+function undoMoves(manifest) {
+    const done = JSON.parse(fs_1.default.readFileSync(manifest, "utf8"));
+    let restored = 0, left = 0;
+    for (const m of [...done].reverse()) {
+        try {
+            if (!fs_1.default.existsSync(m.to) || fs_1.default.existsSync(m.from)) {
+                left++;
+                continue;
+            }
+            fs_1.default.mkdirSync(path_1.default.dirname(m.from), { recursive: true });
+            fs_1.default.renameSync(m.to, m.from);
+            restored++;
+        }
+        catch {
+            left++;
+        }
+    }
+    if (!left)
+        fs_1.default.renameSync(manifest, manifest.replace(/\.json$/, ".undone.json"));
+    return { restored, left };
+}