strom-research 1.0.0

package/dist/core/update.js

@@ -0,0 +1,193 @@
+// A new version of strom: noticed (at most once a day, quietly, never in the
+// way) and installed with the user's yes (strom update). strom's code comes
+// from the project's releases (strom-app.tar.gz, checked against the release's
+// SHASUMS256.txt like the installer does) and replaces app/ of the
+// installation; the Node beside it is replaced only when the release asks for
+// another one (NODE_VERSION) — the official build from nodejs.org, checked
+// against nodejs.org's SHASUMS256.txt. A release carries a VERSION file, so the
+// newest version is one small file — the same way from GitHub, a mirror or a
+// folder (STROM_DOWNLOAD_BASE, STROM_NODE_BASE).
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { VERSION } from "./tree.js";
+export const RELEASES = "https://github.com/ACiDekCZ/strom-research/releases/latest/download";
+/** How often strom asks whether there is a new version. */
+export const CHECK_EVERY_MS = 24 * 3600_000;
+export function releaseBase(env) {
+    return (env.STROM_DOWNLOAD_BASE ?? "").trim() || RELEASES;
+}
+/** Is version a newer than b? (1.10.0 > 1.9.2) */
+export function isNewer(a, b) {
+    const n = (v) => v.replace(/^v/, "").split(/[.-]/).map((x) => Number.parseInt(x, 10) || 0);
+    const [x, y] = [n(a), n(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
+/** Where the official Node comes from (nodejs.org's layout: <base>/v<version>/<archive>, SHASUMS256.txt beside). */
+export function nodeBase(env) {
+    return (env.STROM_NODE_BASE ?? "").trim() || "https://nodejs.org/dist";
+}
+/** The official Node archive for this computer. */
+export function nodeArchive(version, platform = process.platform, arch = process.arch) {
+    const cpu = arch === "arm64" ? "arm64" : "x64";
+    if (platform === "win32")
+        return `node-v${version}-win-${cpu}.zip`;
+    return `node-v${version}-${platform === "darwin" ? "darwin" : "linux"}-${cpu}.tar.gz`;
+}
+async function get(url, timeoutMs) {
+    if (url.startsWith("file://"))
+        return fs.readFileSync(new URL(url));
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: "follow" });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} for ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+/** The newest version released, or undefined when it cannot be learned now. */
+export async function latestVersion(env, timeoutMs = 4000) {
+    try {
+        const v = (await get(`${releaseBase(env)}/VERSION`, timeoutMs)).toString("utf8").trim();
+        return /^\d+\.\d+\.\d+/.test(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Does strom look for new versions? (the setting updates: check, the default, or off) */
+export function checksUpdates(settings, env) {
+    return (env.STROM_UPDATES ?? settings.config.updates ?? "check") !== "off";
+}
+/**
+ * A newer version than this one, if there is one — asked at most once a day
+ * (the answer is kept in the user config), with a short wait, silent when
+ * there is no network. `fresh` asks now (strom update, strom doctor).
+ */
+export async function newerVersion(settings, env, opts = {}) {
+    if (!checksUpdates(settings, env))
+        return undefined;
+    const seen = settings.config.updateCheck;
+    const due = opts.fresh || !seen || Date.now() - Date.parse(seen.at) > CHECK_EVERY_MS;
+    let latest = seen?.latest;
+    if (due) {
+        const found = await latestVersion(env, opts.timeoutMs ?? 1500);
+        if (found) {
+            latest = found;
+            settings.config.updateCheck = { at: new Date().toISOString(), latest: found };
+            try {
+                settings.save();
+            }
+            catch {
+                // a read-only config: ask again next time
+            }
+        }
+    }
+    return latest && isNewer(latest, VERSION) ? latest : undefined;
+}
+/** A newer version known already (no network): for places that must not wait. */
+export function knownNewerVersion(settings, env) {
+    if (!checksUpdates(settings, env))
+        return undefined;
+    const latest = settings.config.updateCheck?.latest;
+    return latest && isNewer(latest, VERSION) ? latest : undefined;
+}
+const sha256 = (data) => crypto.createHash("sha256").update(data).digest("hex");
+/** The line of a SHASUMS256.txt for one file, or undefined. */
+function wanted(sums, name) {
+    return sums
+        .toString("utf8")
+        .split("\n")
+        .find((l) => l.trim().endsWith(`  ${name}`))
+        ?.split(/\s+/)[0]
+        ?.toLowerCase();
+}
+function untar(archive, into) {
+    // tar unpacks both: .tar.gz, and .zip on Windows 10 and later.
+    fs.mkdirSync(into, { recursive: true });
+    const r = spawnSync("tar", ["-xf", archive, "-C", into], { stdio: "ignore", windowsHide: true });
+    if (r.status !== 0)
+        throw new Error("the download could not be unpacked");
+}
+/** Put the official Node of this version into the installation (node/node.exe, node/bin/node). */
+async function installNode(env, root, version, work, platform) {
+    const name = nodeArchive(version, platform);
+    const dir = `${nodeBase(env)}/v${version}`;
+    const [archive, sums] = await Promise.all([get(`${dir}/${name}`, 300_000), get(`${dir}/SHASUMS256.txt`, 20_000)]);
+    if (wanted(sums, name) !== sha256(archive))
+        throw new Error("the Node download is damaged (checksum mismatch) — try again");
+    const file = path.join(work, name);
+    fs.writeFileSync(file, archive);
+    untar(file, path.join(work, "node"));
+    const top = path.join(work, "node", name.replace(/\.(zip|tar\.gz)$/, ""));
+    const rel = platform === "win32" ? "node.exe" : path.join("bin", "node");
+    const fresh = path.join(top, rel);
+    if (!fs.existsSync(fresh))
+        throw new Error("the Node download has no node program");
+    const target = path.join(root, "node", rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (platform === "win32") {
+        // The running node.exe cannot be overwritten on Windows, but it can be renamed; deleted after strom ends.
+        const old = path.join(root, "node", "node.old.exe");
+        fs.rmSync(old, { force: true });
+        if (fs.existsSync(target))
+            fs.renameSync(target, old);
+        fs.copyFileSync(fresh, target);
+        const child = spawn(env.ComSpec ?? "cmd.exe", ["/d", "/c", `ping 127.0.0.1 -n 3 >nul & del /f /q "${old}"`], { detached: true, stdio: "ignore", windowsHide: true });
+        child.unref();
+    }
+    else {
+        fs.copyFileSync(fresh, `${target}.new`);
+        fs.chmodSync(`${target}.new`, 0o755);
+        fs.renameSync(`${target}.new`, target);
+    }
+    const license = path.join(top, "LICENSE");
+    if (fs.existsSync(license))
+        fs.copyFileSync(license, path.join(root, "node", "LICENSE"));
+}
+/**
+ * Download, check and put the newest strom into the installation at `root`
+ * (the installer's folder: node/, app/, install.json). Returns the version
+ * installed; throws with a plain reason when it cannot — strom stays as it was.
+ */
+export async function installUpdate(env, root, platform = process.platform) {
+    const base = releaseBase(env);
+    const version = await latestVersion(env, 10_000);
+    if (!version)
+        throw new Error("the newest version could not be learned (no network?)");
+    const [archive, sums, nodeWanted] = await Promise.all([
+        get(`${base}/strom-app.tar.gz`, 120_000),
+        get(`${base}/SHASUMS256.txt`, 20_000),
+        get(`${base}/NODE_VERSION`, 20_000).then((b) => b.toString("utf8").trim(), () => ""),
+    ]);
+    if (wanted(sums, "strom-app.tar.gz") !== sha256(archive))
+        throw new Error("the download is damaged (checksum mismatch) — try again");
+    const infoFile = path.join(root, "install.json");
+    const info = JSON.parse(fs.readFileSync(infoFile, "utf8"));
+    // Unpacked beside the installation (the same disk: a rename moves it into place).
+    const work = fs.mkdtempSync(path.join(root, ".update-"));
+    try {
+        const file = path.join(work, "strom-app.tar.gz");
+        fs.writeFileSync(file, archive);
+        untar(file, work);
+        if (!fs.existsSync(path.join(work, "app", "dist", "cli.js")))
+            throw new Error("the download has no strom in it");
+        if (/^\d+\.\d+\.\d+$/.test(nodeWanted) && nodeWanted !== info.node) {
+            await installNode(env, root, nodeWanted, work, platform);
+            info.node = nodeWanted;
+        }
+        const app = path.join(root, "app");
+        const old = path.join(root, "app.old");
+        fs.rmSync(old, { recursive: true, force: true });
+        fs.renameSync(app, old);
+        fs.renameSync(path.join(work, "app"), app);
+        fs.rmSync(old, { recursive: true, force: true });
+        info.version = version;
+        fs.writeFileSync(infoFile, `${JSON.stringify(info, null, 2)}\n`);
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+    return version;
+}

package/dist/core/validate.js

@@ -0,0 +1,260 @@
+// Record validation. Returns a list of problems instead of throwing, so the
+// same code serves write-time validation and `strom check`.
+import { DIRECTIONS, EVENT_KINDS, NOTE_MAX, RECORD_TYPES, RESEARCH_STATES, STATUSES, } from "./model.js";
+import { normalizeDate } from "./gdate.js";
+import { isGedcomAge } from "./age.js";
+import { SCHEMAS, checkFields } from "./schema.js";
+import { ALL_PREFIXES, CHILD_RELATIONS, NAME_KINDS, PARTICIPANT_ROLES } from "./model.js";
+const ID_RE = Object.fromEntries(Object.entries(RECORD_TYPES).map(([t, v]) => [t, new RegExp(`^${v.prefix}\\d{4,}$`)]));
+const EVENT_ID = /^E\d{4,}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T/;
+function isObj(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function checkNotes(notes, path, out) {
+    if (!Array.isArray(notes)) {
+        out.push({ path, message: "must be an array" });
+        return;
+    }
+    notes.forEach((n, i) => {
+        const p = `${path}[${i}]`;
+        if (!isObj(n))
+            return void out.push({ path: p, message: "must be an object" });
+        const note = n;
+        if (!str(note.text))
+            out.push({ path: `${p}.text`, message: "is required" });
+        else if (note.text.length > NOTE_MAX)
+            out.push({ path: `${p}.text`, message: `is longer than ${NOTE_MAX} characters — use a conflict, hypothesis or story` });
+        if (!str(note.at) || !ISO.test(note.at))
+            out.push({ path: `${p}.at`, message: "must be an ISO timestamp" });
+        if (!str(note.by))
+            out.push({ path: `${p}.by`, message: "is required" });
+    });
+}
+function checkCitations(list, path, out) {
+    if (list === undefined)
+        return;
+    if (!Array.isArray(list))
+        return void out.push({ path, message: "must be an array" });
+    list.forEach((c, i) => {
+        if (!isObj(c) || !str(c.source))
+            out.push({ path: `${path}[${i}].source`, message: "is required" });
+        const info = isObj(c) ? c.information : undefined;
+        if (info !== undefined && !["primary", "secondary", "unknown"].includes(String(info)))
+            out.push({ path: `${path}[${i}].information`, message: "must be primary, secondary or unknown" });
+    });
+}
+export function checkEvent(e, path, out, family = false) {
+    if (!isObj(e))
+        return void out.push({ path, message: "must be an object" });
+    const ev = e;
+    if (!str(ev.id) || !EVENT_ID.test(ev.id))
+        out.push({ path: `${path}.id`, message: "must be an event ID like E0001" });
+    if (!str(ev.kind) || !(ev.kind in EVENT_KINDS))
+        out.push({ path: `${path}.kind`, message: `unknown event kind "${String(ev.kind)}"` });
+    if (ev.date !== undefined && (!str(ev.date) || normalizeDate(ev.date) !== ev.date))
+        out.push({ path: `${path}.date`, message: `"${String(ev.date)}" is not a normalized GEDCOM date` });
+    if (!STATUSES.includes(ev.status))
+        out.push({ path: `${path}.status`, message: `must be one of ${STATUSES.join(", ")}` });
+    if (!Array.isArray(ev.citations))
+        out.push({ path: `${path}.citations`, message: "must be an array" });
+    else
+        checkCitations(ev.citations, `${path}.citations`, out);
+    if ((ev.status === "proven" || ev.status === "probable") && Array.isArray(ev.citations) && ev.citations.length === 0)
+        out.push({ path: `${path}.status`, message: `${ev.status} needs at least one citation` });
+    if (ev.house !== undefined && !str(ev.house))
+        out.push({ path: `${path}.house`, message: "must be a non-empty string" });
+    if (ev.cause !== undefined && !str(ev.cause))
+        out.push({ path: `${path}.cause`, message: "must be a non-empty string" });
+    if (ev.kind === "EVEN" && !ev.label && !ev.value)
+        out.push({ path: `${path}.label`, message: "EVEN needs a label (what happened)" });
+    if (["OCCU", "RELI", "TITL", "NATI"].includes(String(ev.kind)) && !ev.value)
+        out.push({ path: `${path}.value`, message: `${ev.kind} needs a value (the fact itself, e.g. "blacksmith")` });
+    if (ev.participants !== undefined) {
+        if (!Array.isArray(ev.participants))
+            out.push({ path: `${path}.participants`, message: "must be a list" });
+        else
+            ev.participants.forEach((pt, i) => {
+                const pp = `${path}.participants[${i}]`;
+                if (!isObj(pt))
+                    return void out.push({ path: pp, message: "must be an object" });
+                if (!pt.person && !pt.name)
+                    out.push({ path: pp, message: "needs a person ID or a name" });
+                if (!PARTICIPANT_ROLES.includes(pt.role))
+                    out.push({ path: `${pp}.role`, message: `must be one of ${PARTICIPANT_ROLES.join(", ")}` });
+            });
+    }
+    if (ev.age !== undefined) {
+        if (family)
+            out.push({ path: `${path}.age`, message: "a family event gives the age of each partner: ages" });
+        else if (!str(ev.age) || !isGedcomAge(ev.age))
+            out.push({ path: `${path}.age`, message: `"${String(ev.age)}" is not a GEDCOM age like 27y, 27y 3m, INFANT` });
+    }
+    if (ev.ages !== undefined) {
+        if (!family)
+            out.push({ path: `${path}.ages`, message: "ages are for family events; a person's event has age" });
+        else if (!isObj(ev.ages))
+            out.push({ path: `${path}.ages`, message: "must be an object: person ID → age" });
+        else
+            for (const [who, age] of Object.entries(ev.ages)) {
+                if (!/^P\d{4,}$/.test(who))
+                    out.push({ path: `${path}.ages`, message: `"${who}" is not a person ID` });
+                if (typeof age !== "string" || !isGedcomAge(age))
+                    out.push({ path: `${path}.ages.${who}`, message: `"${String(age)}" is not a GEDCOM age` });
+            }
+    }
+}
+function checkBase(r, type, out) {
+    const re = ID_RE[type];
+    if (!str(r.id) || !re?.test(r.id))
+        out.push({ path: "id", message: `must be a ${type} ID` });
+    if (!str(r.created) || !ISO.test(r.created))
+        out.push({ path: "created", message: "must be an ISO timestamp" });
+    if (!str(r.updated) || !ISO.test(r.updated))
+        out.push({ path: "updated", message: "must be an ISO timestamp" });
+}
+function checkStory(st, out) {
+    if (st === undefined)
+        return;
+    if (!isObj(st))
+        return void out.push({ path: "story", message: "must be an object" });
+    const s = st;
+    if (!str(s.text))
+        out.push({ path: "story.text", message: "is required" });
+    if (s.status !== "draft" && s.status !== "final")
+        out.push({ path: "story.status", message: "must be draft or final" });
+    if (!Array.isArray(s.facts) || s.facts.some((f) => !EVENT_ID.test(String(f))))
+        out.push({ path: "story.facts", message: "must be a list of event IDs" });
+}
+function checkPerson(p, out) {
+    if (!Array.isArray(p.names) || p.names.length === 0)
+        out.push({ path: "names", message: "needs at least one name" });
+    else
+        p.names.forEach((n, i) => {
+            if (!isObj(n))
+                return void out.push({ path: `names[${i}]`, message: "must be an object" });
+            if (typeof n.given !== "string")
+                out.push({ path: `names[${i}].given`, message: "must be a string" });
+            if (typeof n.surname !== "string")
+                out.push({ path: `names[${i}].surname`, message: "must be a string" });
+            if (!n.given && !n.surname)
+                out.push({ path: `names[${i}]`, message: "needs a given name or a surname" });
+            if (n.kind !== undefined && !NAME_KINDS.includes(n.kind))
+                out.push({ path: `names[${i}].kind`, message: `must be one of ${NAME_KINDS.join(", ")}` });
+            checkCitations(n.citations, `names[${i}].citations`, out);
+        });
+    if (!["M", "F", "U"].includes(p.sex))
+        out.push({ path: "sex", message: "must be M, F or U" });
+    checkStory(p.story, out);
+    if (!Array.isArray(p.events))
+        out.push({ path: "events", message: "must be an array" });
+    else
+        p.events.forEach((e, i) => checkEvent(e, `events[${i}]`, out));
+    checkNotes(p.notes, "notes", out);
+}
+function checkFamily(f, out) {
+    if (!Array.isArray(f.partners) || f.partners.length > 2)
+        out.push({ path: "partners", message: "must be an array of at most 2 persons" });
+    if (Array.isArray(f.events) && Array.isArray(f.partners))
+        f.events.forEach((e, i) => {
+            for (const who of Object.keys(e?.ages ?? {}))
+                if (!f.partners.includes(who))
+                    out.push({ path: `events[${i}].ages.${who}`, message: "is not a partner of this family" });
+        });
+    if (!Array.isArray(f.children))
+        out.push({ path: "children", message: "must be an array" });
+    else
+        f.children.forEach((c, i) => {
+            if (!isObj(c) || !str(c.person))
+                return void out.push({ path: `children[${i}].person`, message: "is required" });
+            if (!CHILD_RELATIONS.includes(c.relation))
+                out.push({ path: `children[${i}].relation`, message: `must be one of ${CHILD_RELATIONS.join(", ")}` });
+            if (c.relations !== undefined) {
+                if (!isObj(c.relations))
+                    out.push({ path: `children[${i}].relations`, message: "must be an object: partner ID → relation" });
+                else
+                    for (const [who, rel] of Object.entries(c.relations)) {
+                        if (!f.partners?.includes(who))
+                            out.push({ path: `children[${i}].relations.${who}`, message: "is not a partner of this family" });
+                        if (!CHILD_RELATIONS.includes(rel))
+                            out.push({ path: `children[${i}].relations.${who}`, message: `must be one of ${CHILD_RELATIONS.join(", ")}` });
+                    }
+            }
+        });
+    checkCitations(f.citations, "citations", out);
+    checkStory(f.story, out);
+    const members = (f.partners?.length ?? 0) + (f.children?.length ?? 0);
+    if (members === 0)
+        out.push({ path: "partners", message: "a family needs at least one member" });
+    if (!Array.isArray(f.events))
+        out.push({ path: "events", message: "must be an array" });
+    else
+        f.events.forEach((e, i) => checkEvent(e, `events[${i}]`, out, true));
+    checkNotes(f.notes, "notes", out);
+}
+function checkResearch(r, out) {
+    if (!str(r.name))
+        out.push({ path: "name", message: "is required" });
+    if (!str(r.focus))
+        out.push({ path: "focus", message: "is required (a person ID)" });
+    if (!DIRECTIONS.includes(r.direction))
+        out.push({ path: "direction", message: `must be one of ${DIRECTIONS.join(", ")}` });
+    if (!RESEARCH_STATES.includes(r.state))
+        out.push({ path: "state", message: `must be one of ${RESEARCH_STATES.join(", ")}` });
+    if (typeof r.priority !== "number" || r.priority < 1 || r.priority > 5)
+        out.push({ path: "priority", message: "must be 1..5" });
+    if (r.direction === "question" && !str(r.question))
+        out.push({ path: "question", message: "is required for direction question" });
+    checkNotes(r.notes, "notes", out);
+}
+export function validateRecord(value) {
+    const out = [];
+    if (!isObj(value))
+        return [{ path: "", message: "record must be an object" }];
+    const type = value.type;
+    if (typeof type !== "string" || !(type in RECORD_TYPES))
+        return [{ path: "type", message: `unknown record type "${String(type)}"` }];
+    checkBase(value, type, out);
+    const rec = value;
+    if (rec.type === "person")
+        checkPerson(rec, out);
+    else if (rec.type === "family")
+        checkFamily(rec, out);
+    else if (rec.type === "research")
+        checkResearch(rec, out);
+    else {
+        const spec = SCHEMAS[rec.type];
+        if (spec)
+            checkFields(value, spec, ALL_PREFIXES, "", out, []);
+        checkNotes(value.notes, "notes", out);
+    }
+    return out;
+}
+/** Every reference a record makes to another record (for dangling-reference checks). */
+export function recordRefs(value) {
+    const refs = [];
+    const events = value.events ?? [];
+    events.forEach((e, i) => {
+        e.citations?.forEach((c, j) => refs.push({ path: `events[${i}].citations[${j}]`, id: c.source, to: ["source"] }));
+        e.participants?.forEach((pt, j) => pt.person && refs.push({ path: `events[${i}].participants[${j}]`, id: pt.person, to: ["person"] }));
+    });
+    if (value.type === "person")
+        value.names.forEach((n, i) => n.citations?.forEach((c, j) => refs.push({ path: `names[${i}].citations[${j}]`, id: c.source, to: ["source"] })));
+    if (value.type === "family") {
+        value.citations?.forEach((c, j) => refs.push({ path: `citations[${j}]`, id: c.source, to: ["source"] }));
+        value.partners.forEach((p, i) => refs.push({ path: `partners[${i}]`, id: p, to: ["person"] }));
+        value.children.forEach((c, i) => refs.push({ path: `children[${i}]`, id: c.person, to: ["person"] }));
+    }
+    if (value.type === "research") {
+        refs.push({ path: "focus", id: value.focus, to: ["person"] });
+        if (value.parent)
+            refs.push({ path: "parent", id: value.parent, to: ["research"] });
+    }
+    const spec = SCHEMAS[value.type];
+    if (spec)
+        checkFields(value, spec, ALL_PREFIXES, "", [], refs);
+    return refs;
+}

package/dist/core/views.js

@@ -0,0 +1,164 @@
+// Views of images: the only way an agent looks at a scan. A view is a file in
+// .strom/views/ (the one folder of images an agent may read) made from a
+// registered image: a crop, a half of a double page, scaled to what a reader
+// can take in, contrast stretched on the part being read. Making views through
+// strom also tells strom which images were looked at.
+//
+// Why: an image an agent opens stays in its context and is paid for on every
+// later turn; a whole double page at full resolution is the most expensive
+// thing there is, and readers shrink big images anyway — small script then
+// becomes illegible. So: browse at a reduced size, read at full resolution
+// only the column or entry that matters.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./errors.js";
+import { now } from "./tree.js";
+import { crop, grid, resize, rotate, stretch, toGrey } from "../image/image.js";
+import { decodeImage, encodeImage, ImageFormatError, imageSize } from "../image/index.js";
+/** Longest side of a view by default: what vision models take in without shrinking it again. */
+export const VIEW_MAX = 1568;
+/** Small crops are enlarged at least to this long side (script gets bigger, not sharper). */
+const VIEW_MIN = 800;
+export function parseCrop(spec, w, h) {
+    const nums = spec.split(/[,\s]+/).filter(Boolean).map(Number);
+    if (nums.length !== 4 || nums.some((n) => !Number.isFinite(n) || n < 0))
+        throw new UsageError(`invalid --crop "${spec}"`, { hint: 'give x,y,width,height as fractions ("0.1,0.35,0.4,0.2") or pixels ("400,1200,1500,600")' });
+    const relative = nums.every((n) => n <= 1);
+    const [x, y, cw, ch] = relative ? [nums[0] * w, nums[1] * h, nums[2] * w, nums[3] * h] : nums;
+    if (cw <= 0 || ch <= 0)
+        throw new UsageError("--crop needs a width and a height");
+    return { x: Math.max(0, x), y: Math.max(0, y), w: Math.min(cw, w - x), h: Math.min(ch, h - y) };
+}
+/** The part of a W×H image a view shows (--half, then --crop within it), in its pixels. */
+export function viewRegion(spec, W, H) {
+    let region = { x: 0, y: 0, w: W, h: H };
+    if (spec.half === "left")
+        region = { x: 0, y: 0, w: Math.ceil(W / 2), h: H };
+    else if (spec.half === "right")
+        region = { x: Math.floor(W / 2), y: 0, w: W - Math.floor(W / 2), h: H };
+    else if (spec.half === "top")
+        region = { x: 0, y: 0, w: W, h: Math.ceil(H / 2) };
+    else if (spec.half === "bottom")
+        region = { x: 0, y: Math.floor(H / 2), w: W, h: H - Math.floor(H / 2) };
+    if (spec.crop) {
+        const c = parseCrop(spec.crop, region.w, region.h);
+        region = { x: region.x + c.x, y: region.y + c.y, w: c.w, h: c.h };
+    }
+    return region;
+}
+/**
+ * A region too big for one look at full resolution, as overlapping tiles of at
+ * most `max` px (in original pixels, "x,y,w,h" for --crop). One tile when it fits.
+ */
+export function tiles(region, max = VIEW_MAX, overlap = 0.1) {
+    const step = Math.floor(max * (1 - overlap));
+    const cols = Math.max(1, Math.ceil((region.w - max) / step) + 1);
+    const rows = Math.max(1, Math.ceil((region.h - max) / step) + 1);
+    const out = [];
+    for (let r = 0; r < rows; r++)
+        for (let c = 0; c < cols; c++) {
+            const x = cols === 1 ? region.x : Math.round(region.x + ((region.w - Math.min(max, region.w)) * c) / (cols - 1));
+            const y = rows === 1 ? region.y : Math.round(region.y + ((region.h - Math.min(max, region.h)) * r) / (rows - 1));
+            const w = Math.round(Math.min(max, region.w));
+            const h = Math.round(Math.min(max, region.h));
+            const where = [rows > 1 ? ["top", "middle", "bottom"][r === 0 ? 0 : r === rows - 1 ? 2 : 1] : "", cols > 1 ? ["left", "centre", "right"][c === 0 ? 0 : c === cols - 1 ? 2 : 1] : ""].filter(Boolean).join(" ");
+            out.push({ crop: `${Math.round(x)},${Math.round(y)},${w},${h}`, label: `part ${r * cols + c + 1} of ${rows * cols}${where ? ` (${where})` : ""}` });
+        }
+    return out;
+}
+/** 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" });
+    const bytes = new Uint8Array(fs.readFileSync(source));
+    const size = imageSize(bytes);
+    if (!size) {
+        // not JPEG/PNG: decodeImage says what to do
+        try {
+            decodeImage(bytes);
+        }
+        catch (err) {
+            if (err instanceof ImageFormatError)
+                throw new UsageError(err.message);
+            throw err;
+        }
+    }
+    const W = size.width;
+    const H = size.height;
+    let region = viewRegion(spec, W, H);
+    region = { x: Math.round(region.x), y: Math.round(region.y), w: Math.max(1, Math.round(region.w)), h: Math.max(1, Math.round(region.h)) };
+    const long = Math.max(region.w, region.h);
+    const scale = spec.scale !== undefined
+        ? spec.scale
+        : long > (spec.max ?? VIEW_MAX)
+            ? (spec.max ?? VIEW_MAX) / long
+            : spec.crop || spec.half
+                ? Math.min(3, Math.max(1, VIEW_MIN / long))
+                : 1;
+    if (!(scale > 0) || scale > 8)
+        throw new UsageError("--scale must be between 0 and 8");
+    const outW = Math.max(1, Math.round(region.w * scale));
+    const outH = Math.max(1, Math.round(region.h * scale));
+    if (Math.max(outW, outH) > 6000)
+        throw new UsageError(`the view would be ${outW}×${outH} px`, { hint: "crop a smaller part, or a smaller --scale" });
+    const sha = crypto.createHash("sha256").update(bytes).update(JSON.stringify({ region, scale, spec: { ...spec, crop: undefined, half: undefined, scale: undefined, max: undefined } })).digest("hex");
+    const ext = spec.png ? "png" : "jpg";
+    const dir = path.join(tree.root, ".strom", "views");
+    const file = path.join(dir, `${key}-${sha.slice(0, 10)}.${ext}`);
+    const cached = fs.existsSync(file);
+    let dims = { width: outW, height: outH };
+    if (!cached) {
+        let img = decodeImage(bytes);
+        img = crop(img, region.x, region.y, region.w, region.h);
+        if (spec.grey)
+            img = toGrey(img);
+        if (outW !== img.width || outH !== img.height)
+            img = resize(img, outW, outH);
+        if (spec.contrast)
+            img = stretch(img);
+        if (spec.rotate)
+            img = rotate(img, spec.rotate);
+        if (spec.grid)
+            img = grid(img);
+        dims = { width: img.width, height: img.height };
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, encodeImage(img, spec.png ? "png" : "jpeg"));
+    }
+    else if (spec.rotate === 90 || spec.rotate === 270)
+        dims = { width: outH, height: outW };
+    // Which images were looked at, and by whom (session costs, "who read this").
+    fs.appendFileSync(path.join(dir, "views.jsonl"), JSON.stringify({ at: now(), key, by: tree.actor, view: path.basename(file), region, scale }) + "\n");
+    return { file, ...dims, scale, original: { width: W, height: H }, region, cached };
+}
+/** One line telling the reader what it sees and how to see more. */
+export function describeView(v, display, fetchPart) {
+    const pct = Math.round(v.scale * 100);
+    const part = v.region.w === v.original.width && v.region.h === v.original.height ? "whole image" : `part ${v.region.x},${v.region.y} ${v.region.w}×${v.region.h} px`;
+    const hint = v.scale < 0.75
+        ? " — reduced: crop the part you need to read it at full size (--crop x,y,w,h, --half left|right, --grid to find it)"
+        : v.scale > 1.25
+            ? `\nenlarged from ${v.region.w}×${v.region.h} px of the scan: it has no more detail than that. What you cannot read for sure is marked [?] in the transcript and stays out of the fields; ${fetchPart
+                ? `this part sharper from the archive (one request): ${fetchPart}`
+                : 'a sharper scan: ask the user (strom task wait … --images B…:<n> --on "…": zoomed in on the entry, or the full-resolution scan)'}`
+            : "";
+    return `${display(v.file)}\n${v.width}×${v.height} px · ${part} of ${v.original.width}×${v.original.height} · ${pct} %${hint}`;
+}
+/** A part of an image from --half / --crop (fractions, or pixels of the registered whole image). */
+export function partRegion(opts, whole) {
+    const half = opts.half === undefined ? undefined : String(opts.half);
+    if (half !== undefined && !["left", "right", "top", "bottom"].includes(half))
+        throw new UsageError(`invalid --half "${half}"`, { hint: "left, right, top or bottom" });
+    const crop = opts.crop === undefined ? undefined : String(opts.crop);
+    const pixels = !!crop && crop.split(/[,\s]+/).filter(Boolean).map(Number).some((n) => n > 1);
+    if (pixels && !(whole?.width && whole.height))
+        throw new UsageError("--crop in pixels needs the image registered (its size); give fractions of it", { hint: "--crop 0.5,0.2,0.5,0.3 — x, y, width, height as parts of the whole image" });
+    // fractions are measured on a large image, so that halves come out exact
+    const [W, H] = pixels ? [whole.width, whole.height] : [1_000_000, 1_000_000];
+    const px = viewRegion({ half: half, crop }, W, H);
+    const f = (n) => Math.round(n * 10_000) / 10_000;
+    const r = { x: f(px.x / W), y: f(px.y / H), w: f(px.w / W), h: f(px.h / H) };
+    if (r.w * r.h > 0.95)
+        throw new UsageError("that is the whole image", { hint: "without --crop and --half it is the image itself" });
+    return r;
+}

package/dist/core/which.js

@@ -0,0 +1,51 @@
+// Find executables on PATH without running them (running an outdated,
+// blocked binary can trigger OS malware warnings).
+import fs from "node:fs";
+import path from "node:path";
+import { agentBinDirs } from "./install.js";
+export function which(cmd, env, platform = process.platform) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+    const exts = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").map((e) => e.toLowerCase()) : [""];
+    for (const dir of dirs)
+        for (const ext of exts) {
+            const file = path.join(dir, cmd + ext);
+            try {
+                const st = fs.statSync(file);
+                if (st.isFile() && (platform === "win32" || (st.mode & 0o111) !== 0))
+                    return file;
+            }
+            catch {
+                // not here
+            }
+        }
+    return undefined;
+}
+/** Agent CLIs strom can drive. */
+export const AGENTS = [
+    { id: "claude", command: "claude", name: "Claude Code" },
+    { id: "codex", command: "codex", name: "OpenAI Codex CLI" },
+    { id: "antigravity", command: "agy", name: "Antigravity CLI" },
+    { id: "opencode", command: "opencode", name: "OpenCode" },
+];
+/** Which AI agent's shell tool runs strom? (they set these variables) */
+export function detectAgent(env) {
+    if (env.CLAUDECODE)
+        return "claude";
+    if (Object.keys(env).some((k) => k.startsWith("ANTIGRAVITY_")))
+        return "antigravity";
+    if (Object.keys(env).some((k) => k.startsWith("CODEX_")))
+        return "codex";
+    if (env.OPENCODE === "1" || env.OPENCODE_PID)
+        return "opencode";
+    if (env.AI_AGENT)
+        return env.AI_AGENT.toLowerCase();
+    return undefined;
+}
+/** Is an agent running strom — its shell tool, or an agent strom run started? */
+export function isAgent(env) {
+    return Boolean(detectAgent(env) || env.STROM_SESSION);
+}
+/** An agent CLI on PATH, or where its installer puts it (a PATH not updated yet in this terminal). */
+export function findAgent(cmd, env, platform = process.platform) {
+    return which(cmd, env, platform) ?? which(cmd, { ...env, PATH: agentBinDirs(env, platform).join(path.delimiter), Path: undefined }, platform);
+}