strom-research 1.6.0 → 1.7.0

package/dist/core/pack.js

@@ -0,0 +1,311 @@
+// A research handed to someone else: one ZIP file with the tree as it was last
+// saved (its history too), the images its records stand on, the images nobody
+// can fetch again (saved by hand, the family's material) and the connectors
+// that fetched the rest. The other images are left out: the archive gives the
+// same scan again when it is needed (strom fetch puts it back, checked).
+// The one who gets it unpacks it with strom: into their trees, the images into
+// their shared folder, the connectors into their plugins, and takes it over.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as git from "./git.js";
+import { connectorsDir } from "./connector.js";
+import { StromError, UsageError } from "./errors.js";
+import { createKey } from "./seal.js";
+import { safeFolderName } from "./text.js";
+import { Tree, VERSION } from "./tree.js";
+import { verifyFull } from "./integrity.js";
+import { readZip, unzipTo, ZipWriter } from "./zip.js";
+export const PACK_MANIFEST = "strom-pack.json";
+export const INSTALL_WINDOWS = "irm https://raw.githubusercontent.com/ACiDekCZ/strom-research/main/install/install.ps1 | iex";
+export const INSTALL_UNIX = "curl -fsSL https://raw.githubusercontent.com/ACiDekCZ/strom-research/main/install/install.sh | sh";
+/** What goes into a package of this tree: every image (all), or the ones its records stand on and the ones nobody can fetch again. */
+export function packPlan(tree, shared, all) {
+    const media = tree.list("media");
+    const cited = new Set();
+    for (const s of tree.list("source")) {
+        if (s.retracted)
+            continue;
+        for (const id of s.media ?? [])
+            cited.add(id);
+        for (const c of s.clips ?? [])
+            cited.add(c.media);
+    }
+    // an image's other copies and parts go along: a view uses the sharpest
+    const citedImages = new Set(media.filter((m) => cited.has(m.id) && m.recordset && m.image !== undefined).map((m) => `${m.recordset}:${m.image}`));
+    const take = new Map();
+    const missing = [];
+    const add = (file, size) => {
+        if (fs.existsSync(path.join(shared, file)))
+            take.set(file, size);
+        else
+            missing.push(file);
+    };
+    let leftCount = 0;
+    let leftBytes = 0;
+    const connectors = new Set();
+    for (const m of media) {
+        if (m.fetched)
+            connectors.add(m.fetched.connector);
+        const needed = all || cited.has(m.id) || !m.fetched || citedImages.has(`${m.recordset}:${m.image}`);
+        if (needed)
+            add(m.file, m.size);
+        else {
+            leftCount++;
+            leftBytes += m.size;
+        }
+    }
+    // the family's material kept in the shared store
+    for (const i of tree.list("input"))
+        if (i.file?.startsWith("media:"))
+            add(i.file.slice(6), i.size ?? 0);
+    const have = [...connectors].filter((c) => fs.existsSync(path.join(connectorsDir(shared), c, "connector.json")));
+    return {
+        media: [...take].map(([file, size]) => ({ file, size })).sort((a, b) => a.file.localeCompare(b.file)),
+        connectors: have.sort(),
+        left: { count: leftCount, bytes: leftBytes, connectors: connectors.size - have.length },
+        missing,
+    };
+}
+/** The files under a folder, and its empty folders ending in "/" (git needs them). */
+function walk(dir, rel = "") {
+    const out = [];
+    const entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true });
+    for (const e of entries) {
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) {
+            if (e.name === "node_modules")
+                continue;
+            out.push(...walk(dir, r));
+        }
+        else if (e.isFile() && e.name !== ".DS_Store")
+            out.push(r);
+    }
+    if (rel && !entries.length)
+        out.push(`${rel}/`);
+    return out;
+}
+function addTree(zip, prefix, dir) {
+    for (const f of walk(dir)) {
+        if (f.endsWith("/"))
+            zip.addDir(`${prefix}/${f}`);
+        else
+            zip.addFile(`${prefix}/${f}`, path.join(dir, ...f.split("/")));
+    }
+}
+/**
+ * What the one who gets the package starts with a double click once it is unpacked: strom installed where it is
+ * not (the official installer, nothing else), the research put in place from the folder the launcher lies in,
+ * then strom. `say`: the two sentences it may need, in the research language.
+ */
+export function launchers(say) {
+    const cmd = [
+        "@echo off",
+        "chcp 65001 >nul",
+        'cd /d "%~dp0"',
+        'if exist "%~dp0' + PACK_MANIFEST + '" goto found',
+        `echo ${say.extract}`,
+        "pause",
+        "exit /b 1",
+        ":found",
+        'set "STROM="',
+        'for /f "delims=" %%i in (\'where strom.cmd 2^>nul\') do if not defined STROM set "STROM=%%i"',
+        'if not defined STROM if exist "%LOCALAPPDATA%\\Programs\\Strom\\strom.cmd" set "STROM=%LOCALAPPDATA%\\Programs\\Strom\\strom.cmd"',
+        "if defined STROM goto run",
+        `powershell -NoProfile -ExecutionPolicy Bypass -Command "$env:STROM_INSTALL_ONLY='1'; ${INSTALL_WINDOWS}"`,
+        'if exist "%LOCALAPPDATA%\\Programs\\Strom\\strom.cmd" set "STROM=%LOCALAPPDATA%\\Programs\\Strom\\strom.cmd"',
+        "if defined STROM goto run",
+        `echo ${say.failed}`,
+        "pause",
+        "exit /b 1",
+        ":run",
+        'call "%STROM%" unpack "%~dp0."',
+        'call "%STROM%"',
+        "",
+    ].join("\r\n");
+    const sh = [
+        "#!/bin/bash",
+        'cd "$(dirname "$0")" || exit 1',
+        'if [ ! -f "' + PACK_MANIFEST + '" ]; then echo "' + say.extract.replace(/"/g, "'") + '"; read -r _; exit 1; fi',
+        'STROM="$(command -v strom || true)"',
+        '[ -z "$STROM" ] && [ -x "$HOME/.local/bin/strom" ] && STROM="$HOME/.local/bin/strom"',
+        'if [ -z "$STROM" ]; then',
+        `  ${INSTALL_UNIX.replace(/\| sh$/, "| STROM_INSTALL_ONLY=1 sh")}`,
+        '  [ -x "$HOME/.local/bin/strom" ] && STROM="$HOME/.local/bin/strom"',
+        "fi",
+        'if [ -z "$STROM" ]; then echo "' + say.failed.replace(/"/g, "'") + '"; read -r _; exit 1; fi',
+        '"$STROM" unpack "$(pwd)"',
+        '"$STROM"',
+        "",
+    ].join("\n");
+    return [
+        { name: "Windows.cmd", text: cmd, mode: 0o755 },
+        { name: "macOS.command", text: sh, mode: 0o755 },
+        { name: "Linux.sh", text: sh, mode: 0o755 },
+    ];
+}
+/** Write the package. `readme`: the file name and text for the person who gets it; `say`: what its launchers may need to say. */
+export function writePack(tree, shared, out, opts) {
+    const plan = packPlan(tree, shared, opts.all);
+    const folder = safeFolderName(tree.config.name) || "tree";
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "strom-pack-"));
+    const zip = new ZipWriter(out);
+    try {
+        // the tree as it was last saved, its history too — never what is half written
+        const clone = path.join(tmp, folder);
+        const r = git.runGit(tmp, ["clone", "--quiet", "--no-hardlinks", tree.root, clone]);
+        if (r.status !== 0)
+            throw new StromError(`could not copy the tree: ${r.stderr.trim()}`);
+        git.runGit(clone, ["remote", "remove", "origin"]);
+        git.runGit(clone, ["gc", "--quiet", "--prune=now"]);
+        const commit = git.head(clone) ?? "";
+        const manifest = {
+            kind: "strom-research-pack",
+            format: 1,
+            tree: { id: tree.config.id, name: tree.config.name, lang: tree.config.lang },
+            folder,
+            created: new Date().toISOString(),
+            strom: VERSION,
+            commit,
+            images: opts.all ? "all" : "records",
+            media: plan.media.map((m) => m.file),
+            connectors: plan.connectors,
+            left: { count: plan.left.count, bytes: plan.left.bytes },
+        };
+        // CRLF: Notepad of an older Windows shows it right too
+        zip.add(opts.readme.name, Buffer.from(opts.readme.text.replace(/\n/g, "\r\n"), "utf8"));
+        for (const l of launchers(opts.say))
+            zip.add(l.name, Buffer.from(l.text, "utf8"), { mode: l.mode });
+        zip.add(PACK_MANIFEST, Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8"));
+        addTree(zip, folder, clone);
+        for (const m of plan.media)
+            zip.addFile(`shared/${m.file}`, path.join(shared, ...m.file.split("/")));
+        for (const c of plan.connectors) {
+            addTree(zip, `shared/plugins/connectors/${c}`, path.join(connectorsDir(shared), c));
+        }
+        zip.close();
+        return { file: out, bytes: fs.statSync(out).size, manifest, plan };
+    }
+    catch (e) {
+        zip.abort();
+        throw e;
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** A package given as the ZIP file or the folder a system unpacked it into: its manifest and where it lies. */
+export function findPack(src) {
+    if (!fs.existsSync(src))
+        throw new UsageError(`there is no ${src}`, { hint: "give the ZIP file you were sent (drag it into the terminal)" });
+    const read = (text) => {
+        const m = JSON.parse(text);
+        if (m.kind !== "strom-research-pack" || !m.tree?.id || !m.folder)
+            throw new UsageError("this is not a research packed by strom");
+        if (m.format > 1)
+            throw new UsageError("this package is of a newer strom", { hint: "strom update" });
+        return m;
+    };
+    if (fs.statSync(src).isDirectory()) {
+        // the folder itself, or the one folder a system's unpacking put around it
+        const candidates = [src, ...fs.readdirSync(src, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(src, e.name))];
+        const dir = candidates.find((d) => fs.existsSync(path.join(d, PACK_MANIFEST)));
+        if (!dir)
+            throw new UsageError(`no ${PACK_MANIFEST} in ${src}: not a research packed by strom`, { hint: "give the ZIP file you were sent" });
+        return { manifest: read(fs.readFileSync(path.join(dir, PACK_MANIFEST), "utf8")), dir };
+    }
+    const entries = readZip(src);
+    const m = entries.find((e) => e.name === PACK_MANIFEST || e.name.endsWith(`/${PACK_MANIFEST}`));
+    if (!m)
+        throw new UsageError("this ZIP file holds no research packed by strom", { hint: "the sender makes one with strom pack" });
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "strom-unpack-"));
+    try {
+        unzipTo(src, dir, entries);
+        const root = path.join(dir, ...m.name.split("/").slice(0, -1));
+        return { manifest: read(fs.readFileSync(path.join(root, PACK_MANIFEST), "utf8")), zip: src, dir: root, tmp: dir };
+    }
+    catch (e) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+}
+/**
+ * Put a package in place: the tree into the trees folder (a free name), its images into the shared store (each
+ * checked against its name, the SHA-256 of its content), its connectors into the plugins where there is none of
+ * that name; then check the tree whole and take it over on this computer. Nothing is left half done.
+ */
+/** The tree's folder among the trees: its name, or with (2), (3)… when that is taken. */
+export function freeRoot(treesDir, name) {
+    const base = safeFolderName(name) || "tree";
+    let root = path.join(treesDir, base);
+    for (let n = 2; fs.existsSync(root); n++)
+        root = path.join(treesDir, `${base} (${n})`);
+    return root;
+}
+export function unpack(pack, treesDir, shared, env) {
+    const src = pack.dir;
+    const m = pack.manifest;
+    // a system that unpacked the names in another code page: the one folder with a tree in it
+    let from = path.join(src, m.folder);
+    if (!fs.existsSync(path.join(from, "strom.json"))) {
+        const trees = fs.readdirSync(src, { withFileTypes: true }).filter((e) => e.isDirectory() && fs.existsSync(path.join(src, e.name, "strom.json")));
+        if (trees.length !== 1)
+            throw new UsageError(`the package has no tree ${m.folder}`);
+        from = path.join(src, trees[0].name);
+    }
+    const root = freeRoot(treesDir, m.tree.name);
+    fs.mkdirSync(treesDir, { recursive: true });
+    const media = [];
+    for (const f of m.media) {
+        const file = path.join(src, "shared", ...f.split("/"));
+        if (!fs.existsSync(file))
+            throw new StromError(`the package is missing ${f}`);
+        const sha = path.basename(f).replace(/\.[^.]+$/, "");
+        if (/^[0-9a-f]{64}$/.test(sha) && crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") !== sha)
+            throw new StromError(`${f} in the package is not the image its name says — damaged on the way?`, { hint: "ask for the package again" });
+        media.push({ from: file, to: path.join(shared, ...f.split("/")) });
+    }
+    fs.cpSync(from, root, { recursive: true, errorOnExist: true });
+    try {
+        const tree = Tree.open(root, env);
+        const bad = verifyFull(tree).findings.filter((f) => f.level === "error");
+        if (bad.length)
+            throw new StromError(`the tree in the package does not check out: ${bad[0].message}${bad.length > 1 ? ` (+${bad.length - 1})` : ""}`, { hint: "ask for the package again" });
+        let adopted = false;
+        if (!tree.key) {
+            tree.withTreeLock(() => {
+                createKey(env, tree.config.id);
+                tree.reloadKey();
+                tree.appendOp({ op: "seal.adopt", targets: [], files: [], summary: "Tree adopted on this computer (unpacked)" });
+                tree.commit("Seal: tree adopted on this computer");
+            });
+            adopted = true;
+        }
+        let imagesHad = 0;
+        for (const x of media) {
+            if (fs.existsSync(x.to)) {
+                imagesHad++;
+                continue;
+            }
+            fs.mkdirSync(path.dirname(x.to), { recursive: true });
+            fs.copyFileSync(x.from, x.to);
+        }
+        const connectors = [];
+        const kept = [];
+        for (const c of m.connectors) {
+            const to = path.join(connectorsDir(shared), c);
+            if (fs.existsSync(to)) {
+                kept.push(c);
+                continue;
+            }
+            fs.cpSync(path.join(src, "shared", "plugins", "connectors", c), to, { recursive: true });
+            connectors.push(c);
+        }
+        return { root, name: tree.config.name, images: media.length - imagesHad, imagesHad, connectors, connectorsKept: kept, adopted };
+    }
+    catch (e) {
+        fs.rmSync(root, { recursive: true, force: true });
+        throw e;
+    }
+}

package/dist/core/sync.js

@@ -40,6 +40,45 @@ const kindOf = (k) => (k === "CHR" ? "BAPM" : k);
 export const factKey = (f) => [kindOf(f.kind), f.date ?? "", exact(f.place), exact(f.value), f.date || f.place ? "" : fold(f.label)].join("|");
 /** A name for a comparison: "? /Novák/", "Jan //" and "Jan /?/" are the names the research has. */
 const nameKey = (n) => exact(n.replace(/[/?]/g, " "));
+/** A place's name as the Strom app keys its coordinates (placeKey of its places.ts): no accents, case, stops or commas. */
+export const placeKey = (s) => foldText(s.replace(/[.,;]/g, " ")).replace(/\s+/g, " ").trim();
+/** The Strom app's own key of a place's coordinates in its JSON (places.ts). */
+const appPlaceKey = (s) => s
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[.,;]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+/** GEDCOM's N50.042 / E15.358 (also a bare or negative number): degrees, the south and west negative. */
+function degrees(v, neg, max) {
+    const m = /^\s*([NSEW])?\s*(-?\d{1,3}(?:\.\d+)?)\s*$/i.exec(v ?? "");
+    if (!m)
+        return undefined;
+    const n = Number(m[2]) * (m[1]?.toUpperCase() === neg ? -1 : 1);
+    return Number.isFinite(n) && Math.abs(n) <= max ? n : undefined;
+}
+/** The places of a GEDCOM with their MAP > LATI/LONG, wherever a PLAC is. */
+function gedPlaces(records) {
+    const out = new Map();
+    const walk = (n) => {
+        for (const c of n.children) {
+            const map = c.tag === "PLAC" ? c.children.find((x) => x.tag === "MAP") : undefined;
+            const lat = map ? degrees(val(map, "LATI"), "S", 90) : undefined;
+            const lon = map ? degrees(val(map, "LONG"), "W", 180) : undefined;
+            const name = c.value.replace(/\s+/g, " ").trim();
+            if (lat !== undefined && lon !== undefined && name && !out.has(placeKey(name)))
+                out.set(placeKey(name), { name, lat, lon });
+            walk(c);
+        }
+    };
+    for (const r of records)
+        if (r.tag === "INDI" || r.tag === "FAM")
+            walk(r);
+    return out;
+}
+/** The same point: the Strom app keeps six decimals. */
+const samePoint = (a, b) => Math.abs(a.lat - b.lat) < 5e-7 && Math.abs(a.lon - b.lon) < 5e-7;
 /** The Strom app's "Birth (alternative record)": a second birth or death of ours coming back as an event of its own. */
 const ALTERNATIVE = {
     "birth (alternative record)": "BIRT", "death (alternative record)": "DEAT",
@@ -155,7 +194,7 @@ export function readGedcom(text) {
     }
     const treeId = val(head, "_STROM_TREE");
     const at = val(head, "_STROM_HEAD");
-    return { format: "gedcom", ...(treeId ? { treeId } : {}), ...(at ? { head: at } : {}), persons, families, problems };
+    return { format: "gedcom", ...(treeId ? { treeId } : {}), ...(at ? { head: at } : {}), persons, families, places: gedPlaces(records), problems };
 }
 /** The Strom app's life events → our kinds. */
 const APP_EVENTS = {
@@ -236,8 +275,19 @@ export function readStromJson(data) {
         }
         families.push({ partners, children: (u.childIds ?? []).map((c) => keys.get(c)).filter((k) => !!k), facts });
     }
+    // the app's coordinates are kept for the place's name (its placeKey): the names are its facts'
+    const places = new Map();
+    const geo = d.places && typeof d.places === "object" ? d.places : {};
+    for (const f of [...persons.values()].flatMap((p) => p.facts).concat(families.flatMap((x) => x.facts))) {
+        const k = f.place ? placeKey(f.place) : "";
+        const g = f.place ? geo[appPlaceKey(f.place)] : undefined;
+        if (!g || places.has(k) || typeof g.lat !== "number" || typeof g.lon !== "number")
+            continue;
+        if (Math.abs(g.lat) <= 90 && Math.abs(g.lon) <= 180)
+            places.set(k, { name: f.place, lat: g.lat, lon: g.lon });
+    }
     const r = d.research;
-    return { format: "strom-json", ...(r?.id ? { treeId: r.id } : {}), ...(r?.head ? { head: r.head } : {}), persons, families, problems: [] };
+    return { format: "strom-json", ...(r?.id ? { treeId: r.id } : {}), ...(r?.head ? { head: r.head } : {}), persons, families, places, problems: [] };
 }
 /** A file coming back: GEDCOM or the Strom app's JSON; empty or unreadable throws. */
 export function readTreeFile(file) {
@@ -635,8 +685,32 @@ export function planSync(tree, incoming, edits, opts = {}) {
                     push({ kind: "child.gone", action: "report", family: fam.id, partners, child: c });
         }
     }
+    // places on the map: no record proves a position, so the user's is taken — set where the research has none,
+    // or changed in the app since it was given (the research's as it was given); anything else only when picked
+    const ourPlaces = researchPlaces(tree);
+    for (const [k, p] of incoming.places ?? []) {
+        const mine = ourPlaces.get(k);
+        const here = mine?.coords;
+        if (here && samePoint(here, p))
+            continue;
+        const given = base?.places?.get(k);
+        if (given && samePoint(given, p))
+            continue; // as it was given: the research moved it since
+        const action = !here || (given && samePoint(given, here)) ? "set" : "pick";
+        push({ kind: "place.coords", action, place: { ...p, ...(mine ? { id: mine.id } : {}), ...(here ? { was: here } : {}) } });
+    }
     return { changes, base: !!base, ...(incoming.head ? { head: incoming.head } : {}), partial, identity };
 }
+/** The research's places by placeKey of each of their names — one with coordinates first, as the export gives them. */
+function researchPlaces(tree) {
+    const out = new Map();
+    for (const p of tree.list("place"))
+        if (!p.retracted)
+            for (const n of p.names)
+                if (!out.has(placeKey(n.name)) || (p.coords && !out.get(placeKey(n.name)).coords))
+                    out.set(placeKey(n.name), p);
+    return out;
+}
 /** Does the research's fact say all the file's fact says, and more: the same kind, and each of its date, place, value the same or missing in the file. */
 /**
  * The Strom app keeps a couple's marriages and divorces as the course of one union: two marriages with no divorce
@@ -798,6 +872,25 @@ export function applySync(tree, plan, incoming, source, only) {
                 applied.push({ do: "child.add", id: c.family, before: child });
                 break;
             }
+            case "place.coords": {
+                const p = c.place;
+                if (!p)
+                    break;
+                const coords = { lat: p.lat, lon: p.lon };
+                const mine = p.id ? tree.get(p.id) : undefined;
+                if (mine && !mine.retracted) {
+                    update(tree, mine.id, "place", ({ unlocated: _found, ...rest }) => ({ ...rest, coords }), {
+                        op: "place.edit",
+                        summary: `${mine.id} at ${p.lat}, ${p.lon}: ${reason}`,
+                    });
+                    applied.push({ do: "place.edit", id: mine.id, before: JSON.stringify({ coords: mine.coords, unlocated: mine.unlocated }) });
+                }
+                else {
+                    const made = create(tree, "place", { names: [{ name: p.name }], coords, jurisdictions: [], note: `the position from ${reason}` }, (id) => `+${id} place "${p.name}" (from ${source.id})`);
+                    applied.push({ do: "place.add", id: made.id });
+                }
+                break;
+            }
             default:
                 break;
         }
@@ -858,6 +951,17 @@ export function undoSync(tree, input) {
                 if (!tree.get(a.id)?.retracted)
                     retractPerson(tree, a.id, reason);
                 break;
+            case "place.edit": {
+                const b = JSON.parse(String(a.before ?? "{}"));
+                update(tree, a.id, "place", ({ coords: _now, unlocated: _u, ...p }) => ({ ...p, ...(b.coords ? { coords: b.coords } : {}), ...(b.unlocated ? { unlocated: b.unlocated } : {}) }), {
+                    op: "place.edit",
+                    summary: `${a.id} position back: ${reason}`,
+                });
+                break;
+            }
+            case "place.add":
+                update(tree, a.id, "place", (p) => ({ ...p, retracted: { at: now(), reason } }), { op: "place.retract", summary: `${a.id} retracted: ${reason}` });
+                break;
         }
         n++;
     }

package/dist/core/tree.js

@@ -23,7 +23,7 @@ import * as git from "./git.js";
 import { commitSeal, createKey, fingerprint, loadKey, sha256, signOp } from "./seal.js";
 import { stringifyCanonical } from "./json.js";
 export const TREE_FILE = "strom.json";
-export const VERSION = "1.6.0";
+export const VERSION = "1.7.0";
 const GITIGNORE = `# Strom Research — local state and large files are not versioned
 .strom/
 /media/

package/dist/core/views.js

@@ -69,8 +69,16 @@ export function tiles(region, max = VIEW_MAX, overlap = 0.1) {
 }
 /** Make (or reuse) a view of an image file. `key` names it (M0012, I0003). */
 export function makeView(tree, source, key, spec) {
-    if (!fs.existsSync(source))
-        throw new UsageError(`the image file is missing: ${source}`, { hint: "the shared folder may have moved: strom config where" });
+    if (!fs.existsSync(source)) {
+        // a research handed over without its images: the archive gives the same scan again
+        const m = /^M\d+$/.test(key) ? tree.get(key) : undefined;
+        const again = m?.fetched && m.recordset && m.image !== undefined
+            ? `strom fetch ${m.fetched.connector} ${m.fetched.book} --recordset ${m.recordset} --images ${m.image}${m.part ? ` --crop ${[m.part.x, m.part.y, m.part.w, m.part.h].join(",")}` : ""}`
+            : undefined;
+        throw new UsageError(`the image file is missing: ${source}`, {
+            hint: again ? `fetch it again from the archive (checked: the same scan): ${again} — or the shared folder moved: strom config where` : "the shared folder may have moved: strom config where",
+        });
+    }
     const bytes = new Uint8Array(fs.readFileSync(source));
     const size = imageSize(bytes);
     if (!size) {