strom-research 1.0.0

package/dist/commands/media.js

@@ -0,0 +1,406 @@
+// media add · list · show · view — scans and photos of records.
+//
+// An image is registered once (its content hash is its identity), stored in
+// the shared media store, and tied to its record set and image number. It is
+// looked at only through views; only a registered image can be cited.
+import fs from "node:fs";
+import path from "node:path";
+import { register } from "../cli/registry.js";
+import { lines, moreLine, paginate, runs, shellArg, table } from "../cli/format.js";
+import { UsageError } from "../core/errors.js";
+import { makeNote } from "../core/actions.js";
+import { collectFiles, fileSha256, findImage, imageNumbers, imageOfRef, inboxFolders, inputPath, mimeOf, otherCopies, parseImageList, regionText, sharperPart, storeShared } from "../core/media.js";
+import { create, normId, requireRecord, update } from "../core/records.js";
+import { imageSizeOfFile } from "../image/index.js";
+import { imageOf, pageOf } from "../core/calibration.js";
+import { describeView, makeView, partRegion, viewRegion, VIEW_MAX } from "../core/views.js";
+import { listConnectors, missingConsents } from "../core/connector.js";
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".tif", ".tiff", ".gif", ".webp", ".heic", ".jp2", ".bmp"]);
+/**
+ * Register images of a record set: stored once by content, each with its number
+ * and provenance. Tasks that waited for images of the book go back into the queue.
+ */
+export function registerImages(tree, shared, items, recordset) {
+    const known = new Map(tree.list("media").map((m) => [m.sha, m]));
+    const added = [];
+    const again = [];
+    const clashes = [];
+    const copies = [];
+    tree.withTreeLock(() => {
+        for (const it of items) {
+            const sha = fileSha256(it.file);
+            const k = known.get(sha);
+            if (k) {
+                again.push(k.id);
+                // the same scan as another image: a portal serving another book's images, or a file given the wrong number
+                const as = (m) => `${m.recordset ?? "no record set"}${m.image !== undefined ? `:${m.image}` : ""}${m.part ? ` part ${regionText(m.part)}` : ""}`;
+                if (as(k) !== as({ recordset, image: it.image, part: it.part }))
+                    clashes.push(`${as({ recordset, image: it.image, part: it.part })} is the same file as ${k.id} (${as(k)}) — not registered again: the portal may have given another book's image, or a number is wrong; check before citing either`);
+                continue;
+            }
+            const stored = tree.dryRun ? it.file : storeShared(shared, it.file, sha);
+            const size = imageSizeOfFile(it.file);
+            const m = create(tree, "media", {
+                sha,
+                file: path.relative(shared, stored).split(path.sep).join("/"),
+                mime: mimeOf(it.file),
+                size: fs.statSync(it.file).size,
+                ...(size ? { width: size.width, height: size.height } : {}),
+                recordset,
+                image: it.image,
+                part: it.part,
+                url: it.url,
+                from: it.from,
+                fetched: it.fetched,
+                accessed: new Date().toISOString().slice(0, 10),
+            }, (id) => `+${id} ${it.part ? `part ${regionText(it.part)} of image` : "image"}${it.image !== undefined ? ` ${it.image}` : ""}${recordset ? ` of ${recordset}` : ""}`, recordset ? [recordset] : []);
+            known.set(sha, m);
+            added.push(m);
+            // another copy of an image already there (a reduced download, then the full one): the sharpest is the image
+            const others = otherCopies([...known.values()], m);
+            if (others.length && recordset && it.image !== undefined) {
+                const best = findImage([...known.values()], recordset, it.image);
+                const size = (x) => (x.width ? ` ${x.width}×${x.height}` : "");
+                copies.push(`${recordset}:${it.image} has ${others.length + 1} copies — ${best.id === m.id ? `${m.id}${size(m)} is the sharpest: it is the image now` : `${best.id}${size(best)} is sharper and stays the image`}; views of the others use it (${others.map((x) => `${x.id}${size(x)}`).join(", ")})`);
+            }
+        }
+    });
+    const woken = [];
+    if (recordset && added.length)
+        for (const t of tree.list("task").filter((t) => t.state === "waiting" && (t.where.includes(recordset) || (t.waitingOn ?? "").includes(recordset)))) {
+            // what it asked for and what is still missing, for the session that takes it up
+            const have = new Set(tree.list("media").filter((m) => m.recordset === recordset).map((m) => m.image)); // a part counts: it was asked for too
+            const missing = t.awaits?.recordset === recordset ? (parseImageList(t.awaits.images) ?? []).filter((n) => !have.has(n)) : [];
+            const note = `${added.length} image(s) of ${recordset} registered${t.awaits ? ` (it waited for images ${t.awaits.images}${missing.length ? `; still missing: ${runs(missing)}` : ""})` : ""}`;
+            update(tree, t.id, "task", (x) => {
+                const { awaits: _, ...rest } = x;
+                return { ...rest, state: "open", notes: [...x.notes, makeNote(tree, note)] };
+            }, {
+                op: "task.wake",
+                summary: `${t.id} wake: images of ${recordset} arrived`,
+            });
+            woken.push(t.id);
+        }
+    return { added, again, woken, clashes, copies };
+}
+function sharedDir(ctx) {
+    return ctx.settings.shared().value;
+}
+function pageLabel(tree, m) {
+    if (m.page)
+        return m.page;
+    const b = m.recordset && m.image !== undefined ? tree.get(m.recordset) : undefined;
+    return (b && pageOf(b, m.image)) ?? "";
+}
+/** "M0012", "B0001:57", "I0002" — or a record set with --image / --page. */
+function resolveTarget(tree, shared, ref, opts) {
+    const at = /^([Bb]\d+):(\d+)$/.exec(ref.trim());
+    if (at || /^[Bb]\d+$/.test(ref.trim())) {
+        const b = requireRecord(tree, at ? at[1] : ref, "recordset");
+        let image = at ? Number(at[2]) : opts.image !== undefined ? Number(opts.image) : undefined;
+        if (image === undefined && opts.page !== undefined) {
+            image = imageOf(b, Number.parseInt(String(opts.page), 10));
+            if (image === undefined)
+                throw new UsageError(`${b.id} has no consistent calibration to find page ${opts.page}`, { hint: `measure it: strom recordset calibrate ${b.id} --point <image>=<page>` });
+        }
+        if (image === undefined)
+            throw new UsageError("which image?", { hint: `${b.id}:57, or --image 57, or --page 112` });
+        const m = imageOfRef(tree.list("media"), b.id, image);
+        if (!m)
+            throw new UsageError(`image ${image} of ${b.id} is not registered`, { hint: `strom media list --recordset ${b.id} · strom media add <files> --recordset ${b.id}` });
+        return { key: m.id, file: path.join(shared, m.file), media: m };
+    }
+    const id = normId(ref);
+    if (id.startsWith("I")) {
+        const i = requireRecord(tree, id, "input");
+        const file = inputPath(tree, i);
+        if (!file)
+            throw new UsageError(`${i.id} has no file`);
+        return { key: i.id, file };
+    }
+    const m = requireRecord(tree, id, "media");
+    return { key: m.id, file: path.join(shared, m.file), media: m };
+}
+function viewSpec(opts) {
+    const num = (k) => {
+        if (opts[k] === undefined)
+            return undefined;
+        const n = Number(opts[k]);
+        if (!Number.isFinite(n) || n <= 0)
+            throw new UsageError(`--${k} must be a positive number`);
+        return n;
+    };
+    const half = opts.half;
+    if (half && !["left", "right", "top", "bottom"].includes(half))
+        throw new UsageError(`invalid --half "${half}"`, { hint: "left, right, top or bottom" });
+    const rot = opts.rotate === undefined ? undefined : Number(opts.rotate);
+    if (rot !== undefined && ![90, 180, 270].includes(rot))
+        throw new UsageError("--rotate must be 90, 180 or 270");
+    return {
+        crop: opts.crop,
+        half: half,
+        scale: num("scale"),
+        max: num("max"),
+        contrast: Boolean(opts.contrast),
+        grey: Boolean(opts.grey),
+        grid: Boolean(opts.grid),
+        rotate: rot,
+        png: Boolean(opts.png),
+    };
+}
+register({
+    path: ["media", "add"],
+    summary: "Register scans or photos of records (a folder, files, or the shared inbox) — tied to a record set",
+    group: "sources",
+    tree: true,
+    writes: true,
+    lock: "sections",
+    description: "Each image is stored once in the shared media store (by its content) and gets an ID (M…). The image number\n" +
+        "is the last number in the file name (s0057.jpg → 57), or counted from --first. Look at them with strom media view.",
+    args: [{ name: "paths", description: "image files or folders", variadic: true }],
+    options: [
+        { name: "recordset", type: "string", value: "<B…>", description: "the book or collection the images are of" },
+        { name: "image", type: "string", value: "<n>", description: "image number (one file)" },
+        { name: "first", type: "string", value: "<n>", description: "number the images in file order from n (instead of from their names)" },
+        { name: "url", type: "string", value: "<url>", description: "where the images come from (portal, catalog entry)" },
+        { name: "from", type: "string", value: "<text>", description: "who provided them or how they were obtained" },
+        { name: "inbox", type: "boolean", description: "take the files the user put in the shared inbox (they are moved into the store); a folder there is named as the argument — one folder, one record set" },
+        { name: "half", type: "string", value: "<side>", description: "the file is a half of image n: left, right, top or bottom (a half page saved on its own)" },
+        { name: "crop", type: "string", value: "<x,y,w,h>", description: "the file is this part of image n: fractions of it, or pixels of the registered image (a detail saved from the viewer)" },
+    ],
+    examples: [
+        "strom media add ~/Downloads/tynec17 --recordset B0001 --url https://archive.example.org/register/17",
+        "strom media add --inbox register-17 --recordset B0001",
+        "strom media add --inbox --recordset B0001",
+        "strom media add ~/Downloads/40-left.jpg --recordset B0001 --image 40 --half left",
+    ],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const shared = sharedDir(ctx);
+        const inbox = path.join(shared, "inbox");
+        let paths;
+        if (opts.inbox) {
+            // Each folder in the inbox is one download: never two books into one record set.
+            const folders = inboxFolders(inbox);
+            if (args.length === 0 && folders.length > 1)
+                throw new UsageError(`the inbox holds ${folders.length} downloads — one record set each`, {
+                    hint: folders.map((f) => `strom media add --inbox ${f.folder ? shellArg(f.folder) : "."} --recordset B…   (${f.files.length} file${f.files.length > 1 ? "s" : ""})`).join("\n"),
+                });
+            const only = folders.length === 1 && folders[0].folder ? path.join(inbox, folders[0].folder) : inbox;
+            // a folder named in any Unicode form (NFD from a macOS shell, NFC on Linux)
+            const inInbox = (a) => {
+                const hit = folders.find((f) => f.folder && f.folder.normalize("NFC") === a.normalize("NFC").replace(/[\\/]+$/, ""));
+                return hit ? path.join(inbox, hit.folder) : path.resolve(inbox, a);
+            };
+            paths = args.length ? args.map(inInbox) : [only];
+            for (const p of paths)
+                if (path.relative(inbox, p).startsWith(".."))
+                    throw new UsageError(`${ctx.display(p)} is not in the inbox`, { hint: "strom media add --inbox <folder in the inbox> --recordset B…" });
+            // "." = the files lying in the inbox itself, not its folders
+            paths = paths.flatMap((p) => (p === inbox ? (folders.find((f) => f.folder === "")?.files ?? []) : [p]));
+        }
+        else
+            paths = args.map((a) => ctx.resolvePath(a));
+        if (paths.length === 0)
+            throw new UsageError("give files or folders, or --inbox");
+        for (const p of paths)
+            if (!fs.existsSync(p))
+                throw new UsageError(`no such file or folder: ${ctx.display(p)}`);
+        const files = collectFiles(paths).filter((f) => IMAGE_EXT.has(path.extname(f).toLowerCase()));
+        // numbers are read per folder: one download names its files one way
+        const numbers = new Map();
+        for (const dir of new Set(files.map((f) => path.dirname(f)))) {
+            const group = files.filter((f) => path.dirname(f) === dir);
+            imageNumbers(group).forEach((n, i) => numbers.set(group[i], n));
+        }
+        if (files.length === 0)
+            throw new UsageError("no images there", { hint: "JPEG, PNG, TIFF … files; documents go in with strom intake" });
+        // a folder the user filled for a waiting task (strom task wait --images) says which book and which images
+        const folderOf = (p) => (opts.inbox && !path.relative(inbox, p).startsWith("..") ? path.relative(inbox, p).split(path.sep)[0]?.normalize("NFC") : undefined);
+        const folder = paths.length === 1 ? folderOf(paths[0]) : undefined;
+        const awaited = folder
+            ? tree.list("task").find((t) => t.state === "waiting" && t.awaits && t.awaits.folder.normalize("NFC") === folder && (!opts.recordset || normId(String(opts.recordset), "recordset") === t.awaits.recordset))?.awaits
+            : undefined;
+        const named = folder ? /^([Bb]\d+)(?=\s|$)/.exec(folder)?.[1] : undefined;
+        const recordset = opts.recordset
+            ? requireRecord(tree, String(opts.recordset), "recordset").id
+            : (awaited?.recordset ?? (named && tree.get(normId(named, "recordset")) ? normId(named, "recordset") : undefined));
+        if (opts.image !== undefined && files.length > 1)
+            throw new UsageError("--image is for one file; for many use --first or numbers in the file names");
+        // a part of an image saved on its own: registered with its image, as a part fetched sharper is
+        const wantsPart = opts.half !== undefined || opts.crop !== undefined;
+        if (wantsPart && (files.length > 1 || !opts.recordset))
+            throw new UsageError("a part is one file of one image of a record set", { hint: "strom media add <file> --recordset B… --image <n> --half left" });
+        const first = opts.first === undefined ? undefined : Number(opts.first);
+        const items = files.map((file, i) => ({
+            file,
+            image: opts.image !== undefined ? Number(opts.image) : first !== undefined ? first + i : numbers.get(file),
+            url: opts.url,
+            // the original file name always stays: it is how the archive numbered the image
+            from: opts.from ? `${opts.from} · ${path.basename(file)}` : path.basename(file),
+        }));
+        if (wantsPart && recordset) {
+            const it = items[0];
+            if (it.image === undefined)
+                throw new UsageError("which image is it a part of? --image <n>", { hint: "strom media add <file> --recordset B… --image <n> --half left" });
+            const whole = findImage(tree.list("media").filter((m) => !m.part), recordset, it.image);
+            it.part = partRegion(opts, whole);
+        }
+        if (recordset) {
+            // an image of a book without its number cannot be cited — nor found again
+            const bare = items.filter((it) => it.image === undefined);
+            if (bare.length)
+                throw new UsageError(`${bare.length} file(s) without an image number in the name: ${bare.slice(0, 5).map((it) => path.basename(it.file)).join(", ")}${bare.length > 5 ? " …" : ""}`, {
+                    hint: "name each by its number as the portal's viewer counts it (9.jpg), or --image <n> for one file, --first <n> for files in order",
+                });
+            // saved under the portal's own file name, a number can mean something else (×10, a call number)
+            const want = awaited ? parseImageList(awaited.images) : undefined;
+            if (want && !opts.first && opts.image === undefined && !items.some((it) => want.includes(it.image)))
+                throw new UsageError(`images ${awaited.images} of ${recordset} were asked for, but the file names give ${runs(items.map((it) => it.image))}`, {
+                    hint: "rename the files by the image number the viewer shows (9.jpg), or --image <n> for one file",
+                });
+        }
+        const { added, again, woken, clashes, copies } = registerImages(tree, shared, items, recordset);
+        if (opts.inbox && !tree.dryRun) {
+            for (const f of files)
+                fs.rmSync(f, { force: true }); // now in the store
+            for (const p of paths)
+                if (p !== inbox && fs.existsSync(p) && fs.statSync(p).isDirectory() && collectFiles([p]).length === 0)
+                    fs.rmSync(p, { recursive: true, force: true });
+        }
+        const nums = added.map((m) => m.image).filter((n) => n !== undefined);
+        const text = lines(added.length
+            ? `${added.length} image(s) registered: ${added[0].id}${added.length > 1 ? `–${added.at(-1).id}` : ""}${recordset ? ` of ${recordset}` : ""}${nums.length ? ` (images ${runs(nums)})` : ""}`
+            : "no new images", again.length ? `${again.length} already registered (same content): ${again.slice(0, 5).join(" ")}${again.length > 5 ? " …" : ""}` : undefined, ...clashes.slice(0, 10).map((c) => `⚠ ${c}`), ...copies.slice(0, 10), copies.length > 10 ? `… and ${copies.length - 10} more images with a sharper copy` : undefined, woken.length ? `back in the queue (they waited for these images): ${woken.join(" ")}` : undefined, tree.dryRun ? "(dry run — nothing written)" : undefined, added[0] ? `\nlook at one: strom media view ${recordset && added[0].image !== undefined ? `${recordset}:${added[0].image}` : added[0].id} --grid` : undefined);
+        return { text, data: { added: added.map((m) => ({ id: m.id, image: m.image })), again, woken, clashes, copies } };
+    },
+}, {
+    path: ["media", "list"],
+    summary: "Registered images (of one record set, a range of images)",
+    group: "sources",
+    tree: true,
+    options: [
+        { name: "recordset", type: "string", value: "<B…>", description: "only this record set" },
+        { name: "images", type: "string", value: "<from-to>", description: "only these image numbers, e.g. 90-120" },
+    ],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        let all = tree.list("media");
+        if (opts.recordset) {
+            const b = requireRecord(tree, String(opts.recordset), "recordset").id;
+            all = all.filter((m) => m.recordset === b);
+        }
+        if (opts.images) {
+            const m = /^(\d+)(?:-(\d+))?$/.exec(String(opts.images));
+            if (!m)
+                throw new UsageError("--images must be like 90-120");
+            const lo = Number(m[1]);
+            const hi = Number(m[2] ?? m[1]);
+            all = all.filter((x) => x.image !== undefined && x.image >= lo && x.image <= hi);
+        }
+        all.sort((a, b) => (a.recordset ?? "").localeCompare(b.recordset ?? "") || (a.image ?? 0) - (b.image ?? 0) || Number(!!a.part) - Number(!!b.part));
+        const page = paginate(all, ctx.limit, ctx.page);
+        return {
+            text: all.length
+                ? lines(table(page.items.map((m) => [m.id, m.recordset ? `${m.recordset}:${m.image ?? "?"}` : "", m.part ? `part ${regionText(m.part)}` : "", pageLabel(tree, m), m.width ? `${m.width}×${m.height}` : "", `${Math.round(m.size / 1024)} kB`])), moreLine(page, "strom media list"))
+                : "no images registered → strom media add <folder> --recordset B…",
+            data: { total: all.length, media: page.items.map((m) => ({ id: m.id, recordset: m.recordset, image: m.image, part: m.part, page: pageLabel(tree, m) || undefined, width: m.width, height: m.height })) },
+        };
+    },
+}, {
+    path: ["media", "show"],
+    summary: "One image: where it is from, its page, the sources on it",
+    group: "sources",
+    tree: true,
+    args: [{ name: "image", description: "M0012 or B0001:57", required: true }],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const t = resolveTarget(tree, sharedDir(ctx), args[0], opts);
+        const m = t.media;
+        if (!m)
+            throw new UsageError("not a registered image", { hint: "strom media list" });
+        const sources = tree.list("source").filter((s) => s.media?.includes(m.id));
+        const b = m.recordset ? tree.get(m.recordset) : undefined;
+        const all = tree.list("media");
+        const parts = !m.part && m.recordset && m.image !== undefined ? all.filter((x) => x.part && x.recordset === m.recordset && x.image === m.image) : [];
+        const copies = otherCopies(all, m);
+        const image = copies.length && m.recordset && m.image !== undefined ? findImage(all, m.recordset, m.image) : undefined;
+        return {
+            text: lines(`${m.id} ${m.part ? `part ${regionText(m.part)} of ` : ""}${b ? `image ${m.image ?? "?"} of ${b.id} ${b.title}` : "image"}${pageLabel(tree, m) ? ` · page ${pageLabel(tree, m)}` : ""}`, `${m.width ? `${m.width}×${m.height} px · ` : ""}${Math.round(m.size / 1024)} kB · ${m.mime}${m.from ? ` · from ${m.from}` : ""}${m.url ? ` · ${m.url}` : ""}`, parts.length ? `parts of it, sharper (a view of the image uses them by itself): ${parts.map((p) => `${p.id} ${regionText(p.part)}${p.width ? ` ${p.width}×${p.height}` : ""}`).join(" · ")}` : undefined, copies.length
+                ? `other copies of the image: ${copies.map((c) => `${c.id}${c.width ? ` ${c.width}×${c.height}` : ""}`).join(" · ")} — the image is the sharpest (${image.id}); a view of any copy uses it`
+                : undefined, sources.length ? `sources on it: ${sources.map((s) => `${s.id} ${s.title}`).join(" · ")}` : "no source cites it yet", `view: strom media view ${m.id} [--half left|right] [--crop x,y,w,h] [--grid]`),
+            data: { media: m, parts: parts.map((p) => p.id), copies: copies.map((c) => c.id), sources: sources.map((s) => s.id), page: pageLabel(tree, m) || undefined },
+        };
+    },
+}, {
+    path: ["media", "view"],
+    summary: "Make a view of an image to look at: a crop, a half page, enlarged, more contrast, a grid",
+    group: "sources",
+    tree: true,
+    description: `Writes the view to .strom/views/ and prints its path: open that file with your image reader. Views are at most\n` +
+        `${VIEW_MAX} px on the long side unless --scale says otherwise. Browse whole images reduced; read an entry by\n` +
+        "cropping it — use --grid first to see where it is (the labels are tenths of the image).",
+    args: [{ name: "image", description: "M0012, B0001:57 (record set:image), B0001 with --page, or an input I0002", required: true }],
+    options: [
+        { name: "crop", type: "string", value: "<x,y,w,h>", description: "part of the image: fractions (0.1,0.35,0.4,0.2) or pixels" },
+        { name: "half", type: "string", value: "<side>", description: "left or right page of a double page (top, bottom)" },
+        { name: "scale", type: "string", value: "<f>", description: "size of the result: 2 = twice the original pixels" },
+        { name: "max", type: "string", value: "<px>", description: `longest side when not scaled (default ${VIEW_MAX})` },
+        { name: "contrast", type: "boolean", description: "stretch faded ink (on the part shown)" },
+        { name: "grey", type: "boolean", description: "greyscale" },
+        { name: "grid", type: "boolean", description: "overlay a grid of tenths with labels, to point at a place" },
+        { name: "rotate", type: "string", value: "<deg>", description: "90, 180 or 270" },
+        { name: "image", type: "string", value: "<n>", description: "image number, with a record set ID" },
+        { name: "page", type: "string", value: "<n>", description: "page or folio, with a calibrated record set ID" },
+        { name: "png", type: "boolean", description: "lossless PNG instead of JPEG" },
+    ],
+    examples: [
+        "strom media view B0001:2 --grid",
+        "strom media view B0001:2 --half left --contrast",
+        "strom media view M0001 --crop 0.05,0.40,0.45,0.18",
+        "strom media view B0001 --page 112",
+    ],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const shared = sharedDir(ctx);
+        const t = resolveTarget(tree, shared, args[0], opts);
+        const spec = viewSpec(opts);
+        const all = tree.list("media");
+        // a part of the image fetched sharper (or a sharper copy of all of it) shows the same place with more detail: it is used by itself
+        let shown = t.media;
+        let v;
+        let sharper;
+        if (t.media?.width && t.media.height && !t.media.part) {
+            const px = viewRegion(spec, t.media.width, t.media.height);
+            const s = sharperPart(all, t.media, { x: px.x / t.media.width, y: px.y / t.media.height, w: px.w / t.media.width, h: px.h / t.media.height });
+            if (s) {
+                sharper = s;
+                shown = s.part;
+                const whole = !s.part.part && !spec.crop && !spec.half;
+                v = makeView(tree, path.join(shared, s.part.file), s.part.id, { ...spec, half: undefined, crop: whole ? undefined : regionText(s.crop) });
+            }
+        }
+        v ??= makeView(tree, t.file, t.key, spec);
+        const page = t.media ? pageLabel(tree, t.media) : "";
+        // still too little detail: a connector that fetched the image may fetch this part of it sharper
+        const base = shown?.part ?? { x: 0, y: 0, w: 1, h: 1 };
+        const inWhole = {
+            x: base.x + (v.region.x / v.original.width) * base.w,
+            y: base.y + (v.region.y / v.original.height) * base.h,
+            w: (v.region.w / v.original.width) * base.w,
+            h: (v.region.h / v.original.height) * base.h,
+        };
+        const whole = t.media?.recordset !== undefined && t.media.image !== undefined ? findImage(all, t.media.recordset, t.media.image) : undefined;
+        const from = whole?.fetched ? listConnectors(shared).find((c) => c.name === whole.fetched.connector) : undefined;
+        const canPart = from && from.manifest.can.includes("part") && from.manifest.policy.automation !== "manual" && !missingConsents(ctx.env, from).code;
+        const fetchPart = canPart && v.scale > 1.25 && inWhole.w * inWhole.h < 0.9
+            ? `strom fetch ${from.name} --recordset ${whole.recordset} --images ${whole.image} --crop ${regionText(inWhole)}`
+            : undefined;
+        return {
+            text: lines(describeView(v, (p) => ctx.display(p), fetchPart), sharper
+                ? `from ${sharper.part.id}, ${sharper.part.part ? "a part of the image fetched sharper" : "a sharper copy of the image"} (${sharper.gain.toFixed(1)}× the detail of ${sharper.part.part ? "the whole image" : t.media.id})`
+                : undefined, page ? `page ${page}` : undefined),
+            data: { view: v.file, width: v.width, height: v.height, scale: v.scale, region: v.region, original: v.original, image: t.key, ...(sharper ? { from: sharper.part.id } : {}), page: page || undefined },
+        };
+    },
+});

package/dist/commands/meta.js

@@ -0,0 +1,195 @@
+// Orientation and self-description: `strom` (no arguments), `strom guide`,
+// `strom commands`, `strom help`. An agent with no prior knowledge learns
+// from these what strom is and what to do next.
+import fs from "node:fs";
+import path from "node:path";
+import { newerVersion } from "../core/update.js";
+import { appOpensResearch, installedStromApp, stromAppUrl } from "../core/stromapp.js";
+import { register, commands, describe, GROUPS } from "../cli/registry.js";
+import { UsageError } from "../core/errors.js";
+import { helpFor } from "../cli/help.js";
+import { lines, table } from "../cli/format.js";
+import { guideText } from "./guide.js";
+import { langName } from "../core/lang.js";
+import { ui } from "../cli/ui.js";
+import { VERSION } from "../core/tree.js";
+import { gitVersion } from "../core/git.js";
+import { linuxGitCommand } from "../core/deps.js";
+import { verifyFast } from "../core/integrity.js";
+import { currentSession, openSessions } from "../core/session.js";
+import { liveHolder } from "../core/lock.js";
+import { isAgent } from "../core/which.js";
+import { taskQueue, waitingForUser, waitingLines } from "./tasks.js";
+import { liveWorkers } from "../core/workers.js";
+import { label } from "../core/people.js";
+function orientation(ctx) {
+    const lang = ctx.uiLang();
+    const t = (key, values = {}) => ui(lang, key, values);
+    const home = ctx.settings.home()?.value;
+    const known = home ? ctx.knownTrees() : [];
+    const base = { version: VERSION, trees: known, next: { why: "", command: "" } };
+    // A person at a terminal lets an agent do the work; an agent does it itself.
+    const human = ctx.io.tty && !isAgent(ctx.env);
+    if (home)
+        base.home = home;
+    if (!home) {
+        base.next = human
+            ? { why: t("ui.why.setup.human"), command: "strom setup" }
+            : { why: t("ui.why.setup.agent", { home: ctx.display(ctx.settings.suggestedHome()) }), command: "strom setup --yes --lang <code of the language the user speaks with you>" };
+        return base;
+    }
+    // Without git no family tree can be kept: that first (the user says yes to installing it).
+    if (!gitVersion(ctx.env)) {
+        base.next = { why: t(human ? "ui.why.git.human" : "ui.why.git.agent"), command: process.platform === "linux" ? linuxGitCommand() : "strom doctor --fix" };
+        return base;
+    }
+    if (!ctx.hasTree()) {
+        base.next =
+            known.length === 0
+                ? { why: t("ui.why.init"), command: 'strom init "<tree name, e.g. the family surname>"' }
+                : { why: t("ui.why.pick"), command: `strom trees use "${known[0].name}"` };
+        return base;
+    }
+    const tree = ctx.tree();
+    const findings = verifyFast(tree).findings;
+    base.tree = {
+        name: tree.config.name,
+        root: tree.root,
+        lang: tree.lang,
+        persons: tree.count("person"),
+        families: tree.count("family"),
+        errors: findings.filter((f) => f.level === "error").length,
+        warnings: findings.filter((f) => f.level === "warn").length,
+    };
+    const researches = tree.list("research");
+    base.researches = researches.map((r) => ({
+        id: r.id,
+        name: r.name,
+        state: r.state,
+        focus: tree.get(r.focus) ? label(tree.get(r.focus)) : r.focus,
+    }));
+    // Other agents at work here now (conversations, a run): shown, and their sessions are theirs.
+    const workers = liveWorkers(tree.root).filter((w) => w.id !== ctx.env.STROM_WORKER);
+    const sessions = openSessions(tree);
+    base.working = workers.map((w) => {
+        const s = sessions.find((x) => x.worker === w.id || (w.id === "run" && x.runner));
+        return { who: w.label, since: w.since, ...(s ? { session: s.id } : {}), ...(s?.task ? { task: s.task } : {}) };
+    });
+    if (!base.working.length)
+        delete base.working;
+    // The results, and where the user sees them: the Strom app — installed here, or to be offered.
+    const out = path.join(tree.root, "output");
+    const wanted = ctx.settings.config.stromApp !== "no";
+    const file = path.join(out, wanted ? "tree-strom.ged" : "tree.ged");
+    if (fs.existsSync(file))
+        base.results = { file, app: !wanted ? "not-wanted" : installedStromApp(ctx.env) ? "installed" : "offer" };
+    const stories = ctx.settings.stories(tree.config);
+    base.stories = !stories.on ? "off" : stories.said ? "on" : "tell";
+    // The session this agent works in; else one nobody is working in any more.
+    const busy = (s) => (s.worker && workers.some((w) => w.id === s.worker)) || (s.runner && workers.some((w) => w.id === "run"));
+    const open = currentSession(tree, ctx.env) ?? sessions.find((s) => !busy(s) && !(s.worker && s.worker !== ctx.env.STROM_WORKER && !human));
+    const queued = taskQueue(tree).length;
+    // An agent outside the tree that strom did not start (it set strom up from the web page, or was
+    // opened in some folder): the research goes on in its own conversation, where the tree lives.
+    const rel = path.relative(tree.root, ctx.cwd);
+    const inTree = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    const elsewhere = isAgent(ctx.env) && !ctx.env.STROM_WORKER && !ctx.env.STROM_SESSION && !inTree;
+    if (base.tree.errors > 0)
+        base.next = { why: t("ui.why.check"), command: "strom check" };
+    else if (elsewhere)
+        base.next = { why: t("ui.why.handover"), command: "strom chat" };
+    else if (open && human && open.runner && !liveHolder(path.join(tree.root, ".strom", "run.lock")))
+        base.next = { why: t("ui.why.runleft", { id: open.id }), command: "strom run" };
+    else if (open && human && open.runner)
+        base.next = { why: t("ui.why.running", { id: open.id }), command: "strom status" };
+    else if (open)
+        base.next = human
+            ? { why: t("ui.why.open.human", { id: open.id }), command: `strom session close ${open.id} --interrupted` }
+            : { why: t("ui.why.open.agent", { id: open.id, on: open.task ? ` ${t("ui.o.on", { task: open.task })}` : "" }), command: "strom brief" };
+    else if (researches.length === 0 && queued === 0)
+        base.next = { why: t("ui.why.research"), command: 'strom research new "<name>" --new-person "<Given /Surname/>" --born "<date>" --born-place "<place>"' };
+    else if (queued === 0 && waitingForUser(tree).length)
+        base.next = { why: t("ui.why.waiting"), command: "strom task list --state waiting" };
+    else if (queued === 0 && tree.count("input") === 0)
+        base.next = { why: t("ui.why.intake"), command: 'strom intake --text "<what the user told you>"' };
+    else if (queued > 0)
+        base.next = human ? { why: t("ui.why.run", { n: queued }), command: "strom run" } : { why: t("ui.why.session", { n: queued }), command: "strom session start" };
+    else {
+        const active = researches.find((r) => r.state === "active") ?? researches[0];
+        base.next = { why: t("ui.why.frontier"), command: `strom frontier --research ${active.id}` };
+    }
+    return base;
+}
+register({
+    path: [],
+    summary: "Orientation: what strom is, where you are, what to do next",
+    group: "start",
+    async run(ctx) {
+        const o = orientation(ctx);
+        const newer = await newerVersion(ctx.settings, ctx.env);
+        if (newer)
+            o.update = newer;
+        const lang = ctx.uiLang();
+        const t = (key, values = {}) => ui(lang, key, values);
+        // Labels in one column, whatever their length in the user's language.
+        const labels = [t("ui.o.home"), t("ui.o.tree"), t("ui.o.lang"), t("ui.o.data"), t("ui.o.results"), t("ui.o.stories"), t("ui.o.update"), t("ui.o.next")];
+        const width = Math.max(...labels.map((l) => l.length)) + 2;
+        const row = (label, value) => `${label.padEnd(width)}${value}`;
+        const check = o.tree ? `${o.tree.errors ? t("ui.o.errors", { n: o.tree.errors }) : t("ui.o.ok")}${o.tree.warnings ? `, ${t("ui.o.warnings", { n: o.tree.warnings })}` : ""}` : "";
+        const text = lines(t("ui.o.title", { version: o.version }), t("ui.o.rule"), "", row(t("ui.o.home"), o.home ? ctx.display(o.home) : t("ui.o.notsetup")), o.update ? row(t("ui.o.update"), t("ui.o.update.new", { version: o.update, current: o.version })) : undefined, o.tree
+            ? lines(row(t("ui.o.tree"), `${o.tree.name}  (${ctx.display(o.tree.root)})`), row(t("ui.o.lang"), `${langName(o.tree.lang, lang)} (${o.tree.lang}) — ${t("ui.o.langnote")}`), row(t("ui.o.data"), t("ui.o.counts", { persons: o.tree.persons, families: o.tree.families, check })), o.results
+                ? row(t("ui.o.results"), t(o.results.app === "installed"
+                    ? appOpensResearch(ctx.env) ? "ui.o.results.installed.live" : "ui.o.results.installed"
+                    : o.results.app === "offer"
+                        ? appOpensResearch(ctx.env) ? "ui.o.results.offer.live" : "ui.o.results.offer"
+                        : "ui.o.results.plain", { file: ctx.display(o.results.file), url: stromAppUrl(ctx.env) }))
+                : undefined, o.stories ? row(t("ui.o.stories"), t(`ui.o.stories.${o.stories}`)) : undefined, o.researches?.length
+                ? t("ui.o.research") + "\n" + table(o.researches.map((r) => [`  ${r.id}`, r.name, `[${r.state}]`, r.focus]))
+                : t("ui.o.research.none"), o.working?.length
+                ? t("ui.o.working") + "\n" + table(o.working.map((w) => [`  ${w.who}`, t("ui.o.since", { time: w.since.slice(11, 16) }), w.task ? t("ui.o.on", { task: w.task }) : ""]))
+                : undefined, ctx.hasTree() ? waitingLines(ctx.tree(), { shared: ctx.settings.shared()?.value, display: (p) => ctx.display(p) }) : undefined)
+            : o.trees.length > 1
+                ? t("ui.o.trees") + "\n" + table(o.trees.map((x) => [`  ${x.name}`, ctx.display(x.root)]))
+                : undefined, "", row(t("ui.o.next"), o.next.command), `${" ".repeat(width)}(${o.next.why})`);
+        return { text, data: o };
+    },
+}, {
+    path: ["guide"],
+    summary: "How to do research with strom — read this first (for agents)",
+    group: "start",
+    run(ctx) {
+        const lang = ctx.hasTree() ? ctx.tree().lang : ctx.settings.home() ? ctx.settings.lang().value : undefined;
+        const text = guideText(lang);
+        return { text, data: { guide: text, lang } };
+    },
+}, {
+    path: ["commands"],
+    summary: "Catalog of commands by group; --json gives options and examples (filter: strom commands person --json)",
+    group: "start",
+    args: [{ name: "filter", description: "only commands starting with these words, or of this group", variadic: true }],
+    examples: ["strom commands", "strom commands source --json", "strom commands analysis"],
+    run(_ctx, { args }) {
+        const words = args.flatMap((a) => a.split(/\s+/)).filter(Boolean);
+        const prefix = words.join(" ");
+        const defs = commands().filter((c) => c.path.length > 0 && (!prefix || c.group === prefix || c.path.join(" ") === prefix || c.path.join(" ").startsWith(`${prefix} `)));
+        if (defs.length === 0)
+            throw new UsageError(`no commands match "${prefix}"`, { hint: `groups: ${Object.keys(GROUPS).join(", ")}` });
+        const text = Object.entries(GROUPS)
+            .map(([g, title]) => {
+            const inGroup = defs.filter((c) => c.group === g);
+            return inGroup.length ? `${title}:\n${table(inGroup.map((c) => [`  ${c.path.join(" ")}`, c.summary]))}` : "";
+        })
+            .filter(Boolean)
+            .join("\n\n");
+        return { text, data: { version: VERSION, commands: defs.map(describe) } };
+    },
+}, {
+    path: ["help"],
+    summary: "Help for a command: strom help <command>",
+    group: "start",
+    args: [{ name: "command", description: "command words, e.g. person add", variadic: true }],
+    run(_ctx, input) {
+        const text = helpFor(input.args);
+        return { text, data: { help: text } };
+    },
+});