strom-research 1.6.1 → 1.7.0

package/README.md

@@ -99,6 +99,12 @@ npm: `npm install -g strom-research@latest`.
   (`strom stats`), what is new (`strom recent`), what the agent does next
   (`strom plan`), one person's life with its
   records (`strom person card`), the ancestors as a tree (`strom pedigree`)
+- Hand the research to a relative in one small ZIP file (`strom pack`): the
+  family tree with its history, the images its records stand on and the
+  connectors — the pages only searched through the archive gives again. They
+  double-click the launcher inside (Windows, macOS, Linux): it installs strom
+  where it is missing, puts the research in place and takes it over
+  (`strom unpack`)
 
 **Safe by design**
 - What the agent may do alone is your choice: ask, auto (default) or full

package/assets/lang/cs.json

@@ -62,8 +62,8 @@
   "ui.menu.waitlist": "Co čeká na vás",
   "ui.menu.settings": "Nastavení: agent, samostatná práce, zprávy, archivy, kontrola",
   "ui.menu.doctor": "Kontrola instalace",
-  "ui.menu.trees": "Jiný rodokmen",
-  "ui.menu.newtree": "Založit rodokmen",
+  "ui.menu.trees": "Jiný rodokmen · poslat nebo přijmout",
+  "ui.menu.newtree": "Založit rodokmen · poslat nebo přijmout",
   "ui.menu.quit": "Konec",
   "ui.menu.bye": "Na shledanou. Příště stačí spustit: strom",
   "ui.run.how": "Kolik úkolů? (skončí dřív, když už nebude co dělat; 0 vrátí zpět)",
@@ -808,5 +808,36 @@
   "ui.menu.failed": "Tohle se nepovedlo: {reason}",
   "ui.review.next.human": "Agent se do nich pustí v rozhovoru nebo při samostatné práci.",
   "ui.review.wake.human": "    pokud v něm chcete pokračovat, řekněte to agentovi v rozhovoru",
-  "ui.waiting.gone": "Tohle už na vás nečeká – agent se toho mezitím ujal."
+  "ui.waiting.gone": "Tohle už na vás nečeká – agent se toho mezitím ujal.",
+  "ui.trees.pack": "zabalit „{name}“ a poslat někomu (soubor ZIP)",
+  "ui.trees.unpack": "rodokmen, který vám někdo poslal (soubor ZIP)",
+  "ui.pack.which": "Které snímky přibalit?",
+  "ui.pack.opt.records": "ty, na kterých jsou zápisy – {mb} MB (prohledané stránky dá archiv znovu)",
+  "ui.pack.opt.all": "všechny – {mb} MB",
+  "ui.pack.done": "Zabaleno „{name}“: {file} ({mb} MB)",
+  "ui.pack.saved": "  rodokmen, jak byl naposledy uložený, i s historií",
+  "ui.pack.images": "  snímky: {n} ({mb} MB) – ty, na kterých jsou zápisy, a ty, které nikdo znovu nestáhne",
+  "ui.pack.images.all": "  snímky: všech {n} ({mb} MB)",
+  "ui.pack.left": "  vynechané snímky: {n} ({mb} MB) – prohledané stránky; až budou potřeba, strom je z archivu stáhne znovu",
+  "ui.pack.connectors": "  konektory: {list}",
+  "ui.pack.noconnector": "⚠ některé vynechané snímky přišly konektorem, který na tomto počítači není – nikdo by je znovu nestáhl: strom pack --all-images",
+  "ui.pack.missing": "⚠ snímky, které rodokmen uvádí, ale na tomto počítači nejsou: {n} – v balíčku chybí",
+  "ui.pack.send": "Soubor pošlete. Příjemce ho rozbalí a dvojklikem spustí Windows.cmd nebo macOS.command uvnitř: strom se nainstaluje, pokud chybí, a výzkum se otevře (kdo už strom má: strom unpack „<soubor>“).",
+  "ui.pack.readme.file": "JAK-NAVAZAT.txt",
+  "ui.pack.readme": "Výzkum „{name}“ – jak na něj navázat\n====================================\n\n1. Rozbalte celý soubor ZIP: ve Windows pravým tlačítkem – Extrahovat vše; na Macu dvojklikem.\n\n2. V rozbalené složce spusťte dvojklikem:\n     Windows:  Windows.cmd\n     macOS:    macOS.command  (poprvé pravým tlačítkem – Otevřít; když to macOS nedovolí:\n               Nastavení systému – Soukromí a zabezpečení – Přesto otevřít)\n     Linux:    v terminálu: bash Linux.sh\n   Nainstaluje Strom Research, pokud ještě není (oficiálním instalátorem), dá výzkum\n   na místo – rodokmen mezi vaše, snímky do vaší sdílené složky, všechno zkontroluje –,\n   převezme ho na váš počítač a otevře strom.\n\n3. Pokračujte: v nabídce stromu rozhovor s agentem.\n\nBez spouštěčů: nainstalujte strom sami\n   Windows (PowerShell):      {win}\n   macOS, Linux (Terminál):   {unix}\npak: strom unpack \"<tento soubor ZIP>\" (napište strom unpack a mezeru, přetáhněte soubor\ndo terminálu, Enter) – nebo v nabídce stromu: jiný rodokmen – rodokmen, který vám někdo poslal.\n\nSnímky, na kterých jsou zápisy, v balíčku jsou. Ostatní stránky knih (prohledané,\nnic se na nich nenašlo) kvůli velikosti ne – až budou potřeba, strom je stáhne\nz archivu znovu.\n",
+  "ui.unpack.file": "Přetáhněte sem soubor ZIP (nebo napište, kde je; 0 vrátí zpět):",
+  "ui.unpack.what": "„{name}“ (ze stromu {strom}, uloženo {date}) · snímky: {images}{connectors} → {root}",
+  "ui.unpack.ask": "Dát ho sem a převzít na tento počítač?",
+  "ui.unpack.done": "„{name}“ je tady: {root}",
+  "ui.unpack.images": "  snímky do sdílené složky: {n}{had}",
+  "ui.unpack.had": " (už tu byly: {n})",
+  "ui.unpack.connectors": "  konektory: {list}",
+  "ui.unpack.kept": "  konektor {name} tu už byl – zůstává váš",
+  "ui.unpack.left": "  prohledané stránky, které v něm nejsou: {n} – až budou potřeba, strom je stáhne z archivu",
+  "ui.unpack.adopted": "  převzato na tento počítač",
+  "ui.unpack.next": "Pokračujte: strom (nabídka) nebo strom chat.",
+  "ui.unpack.same": "tento výzkum už tu je: {root}",
+  "ui.unpack.person": "výzkum rozbaluje jen člověk u počítače (přidává konektory)",
+  "ui.pack.launch.extract": "Nejdřív rozbalte celý soubor ZIP – ve Windows pravým tlačítkem: Extrahovat vše – a spusťte tohle znovu z rozbalené složky.",
+  "ui.pack.launch.failed": "Strom Research se nepodařilo nainstalovat. Nainstalujte ho řádkem z JAK-NAVAZAT.txt a spusťte tohle znovu."
 }

package/assets/lang/de.json

@@ -62,8 +62,8 @@
   "ui.menu.waitlist": "Was auf Sie wartet",
   "ui.menu.settings": "Einstellungen: Agent, allein arbeiten, Nachrichten, Archive, Prüfung",
   "ui.menu.doctor": "Installation prüfen",
-  "ui.menu.trees": "Anderer Stammbaum",
-  "ui.menu.newtree": "Stammbaum anlegen",
+  "ui.menu.trees": "Anderer Stammbaum · einen schicken oder empfangen",
+  "ui.menu.newtree": "Stammbaum anlegen · einen schicken oder empfangen",
   "ui.menu.quit": "Beenden",
   "ui.menu.bye": "Auf Wiedersehen. Nächstes Mal genügt: strom",
   "ui.run.how": "Wie viele Aufgaben? (er hört früher auf, wenn es nichts mehr zu tun gibt; 0 geht zurück)",
@@ -808,5 +808,36 @@
   "ui.menu.failed": "Das ging nicht: {reason}",
   "ui.review.next.human": "Der Agent nimmt sie im Gespräch oder bei der Arbeit allein auf.",
   "ui.review.wake.human": "    wenn es weitergehen soll, sagen Sie es dem Agenten im Gespräch",
-  "ui.waiting.gone": "Das wartet nicht mehr auf Sie – der Agent hat es inzwischen übernommen."
+  "ui.waiting.gone": "Das wartet nicht mehr auf Sie – der Agent hat es inzwischen übernommen.",
+  "ui.trees.pack": "„{name}“ einpacken und jemandem schicken (eine ZIP-Datei)",
+  "ui.trees.unpack": "ein Stammbaum, den Ihnen jemand geschickt hat (eine ZIP-Datei)",
+  "ui.pack.which": "Welche Bilder kommen mit?",
+  "ui.pack.opt.records": "die, auf denen die Einträge stehen – {mb} MB (die durchgesehenen Seiten gibt das Archiv wieder)",
+  "ui.pack.opt.all": "alle – {mb} MB",
+  "ui.pack.done": "„{name}“ eingepackt: {file} ({mb} MB)",
+  "ui.pack.saved": "  der Stammbaum, wie er zuletzt gespeichert wurde, mit seiner Geschichte",
+  "ui.pack.images": "  Bilder: {n} ({mb} MB) – die, auf denen die Einträge stehen, und die, die niemand wieder laden kann",
+  "ui.pack.images.all": "  Bilder: alle {n} ({mb} MB)",
+  "ui.pack.left": "  weggelassen: {n} Bilder ({mb} MB) – durchgesehene Seiten; strom lädt sie aus dem Archiv wieder, wenn sie gebraucht werden",
+  "ui.pack.connectors": "  Konnektoren: {list}",
+  "ui.pack.noconnector": "⚠ einige weggelassene Bilder kamen über einen Konnektor, der auf diesem Computer fehlt – niemand könnte sie wieder laden: strom pack --all-images",
+  "ui.pack.missing": "⚠ {n} Bild(er), die der Stammbaum nennt, sind nicht auf diesem Computer – nicht im Paket",
+  "ui.pack.send": "Schicken Sie die Datei. Wer sie bekommt, packt sie aus und startet darin Windows.cmd oder macOS.command per Doppelklick: strom wird installiert, wo es fehlt, und die Forschung öffnet sich (mit strom schon: strom unpack „<die Datei>“).",
+  "ui.pack.readme.file": "SO-GEHT-ES-WEITER.txt",
+  "ui.pack.readme": "Die Forschung „{name}“ – so geht es weiter\n=========================================\n\n1. Packen Sie die ganze ZIP-Datei aus: unter Windows Rechtsklick – Alle extrahieren; auf dem Mac Doppelklick.\n\n2. Starten Sie im ausgepackten Ordner mit Doppelklick:\n     Windows:  Windows.cmd\n     macOS:    macOS.command  (beim ersten Mal Rechtsklick – Öffnen; wenn macOS es ablehnt:\n               Systemeinstellungen – Datenschutz & Sicherheit – Dennoch öffnen)\n     Linux:    im Terminal: bash Linux.sh\n   Es installiert Strom Research, wo es noch fehlt (der offizielle Installer), bringt die\n   Forschung an ihren Platz – den Stammbaum zu Ihren, die Bilder in Ihren gemeinsamen\n   Ordner, alles geprüft –, übernimmt sie auf Ihren Computer und öffnet strom.\n\n3. Weiter: im Menü von strom das Gespräch mit dem Agenten.\n\nOhne die Starter: installieren Sie strom selbst\n   Windows (PowerShell):      {win}\n   macOS, Linux (Terminal):   {unix}\ndann: strom unpack \"<diese ZIP-Datei>\" (strom unpack und ein Leerzeichen tippen, die Datei\nins Terminal ziehen, Enter) – oder im Menü von strom: ein anderer Stammbaum – ein Stammbaum, den Ihnen jemand geschickt hat.\n\nDie Bilder, auf denen die Einträge stehen, sind im Paket. Die anderen Seiten der Bücher\n(durchgesehen, nichts gefunden) wegen der Größe nicht – strom lädt sie aus dem Archiv\nwieder, wenn sie gebraucht werden.\n",
+  "ui.unpack.file": "Ziehen Sie die ZIP-Datei hierher (oder tippen Sie, wo sie liegt; 0 geht zurück):",
+  "ui.unpack.what": "„{name}“ (aus strom {strom}, gespeichert {date}): {images} Bild(er){connectors} → {root}",
+  "ui.unpack.ask": "Hierher legen und auf diesem Computer übernehmen?",
+  "ui.unpack.done": "„{name}“ ist da: {root}",
+  "ui.unpack.images": "  {n} Bild(er) in den gemeinsamen Ordner{had}",
+  "ui.unpack.had": " ({n} waren schon da)",
+  "ui.unpack.connectors": "  Konnektoren: {list}",
+  "ui.unpack.kept": "  Konnektor {name} war schon da – Ihrer bleibt",
+  "ui.unpack.left": "  {n} durchgesehene Seiten sind nicht darin: strom lädt sie aus dem Archiv, wenn sie gebraucht werden",
+  "ui.unpack.adopted": "  auf diesem Computer übernommen",
+  "ui.unpack.next": "Weiter: strom (das Menü) oder strom chat.",
+  "ui.unpack.same": "diese Forschung ist schon da: {root}",
+  "ui.unpack.person": "eine Forschung packt nur die Person am Computer aus (sie fügt Konnektoren hinzu)",
+  "ui.pack.launch.extract": "Packen Sie zuerst die ganze ZIP-Datei aus – unter Windows mit Rechtsklick: Alle extrahieren – und starten Sie dies dann im ausgepackten Ordner neu.",
+  "ui.pack.launch.failed": "Strom Research ließ sich nicht installieren. Installieren Sie es mit der Zeile aus SO-GEHT-ES-WEITER.txt und starten Sie dies neu."
 }

package/dist/cli/menu.js

@@ -25,7 +25,9 @@ import { liveWorkers, runsAtWork } from "../core/workers.js";
 import { askStromApp } from "./wizard.js";
 import { openForUser } from "../core/open.js";
 import { displayName } from "../core/people.js";
-import { agentReady, guarded, pause as partsPause, pickPerson, subMenu } from "./menu-parts.js";
+import { agentReady, droppedPaths, guarded, pause as partsPause, pickPerson, subMenu } from "./menu-parts.js";
+import { packPlan } from "../core/pack.js";
+import { expandHome } from "../core/paths.js";
 import { offerAgent } from "./fixes.js";
 import { addToResearch } from "./menu-research.js";
 import { waitingForYou } from "./menu-waiting.js";
@@ -423,6 +425,9 @@ async function pickTree(ctx, run, lang) {
     }
     const at = known.findIndex((k) => k.root === here);
     const options = [...known.map((k) => ({ label: `${k.name}  (${ctx.display(k.root)})` })), { label: ui(lang, "ui.trees.new") }];
+    // handing a research over: this one packed, one someone sent unpacked
+    const packAt = at >= 0 ? options.push({ label: ui(lang, "ui.trees.pack", { name: known[at].name }) }) - 1 : -1;
+    const unpackAt = options.push({ label: ui(lang, "ui.trees.unpack") }) - 1;
     const back = at >= 0 ? { back: ui(lang, "ui.back.stay", { name: known[at].name }) } : {};
     const i = await ctx.choose(ui(lang, "ui.trees.pick"), options, Math.max(0, at), back);
     if (i === undefined || i === at)
@@ -431,6 +436,28 @@ async function pickTree(ctx, run, lang) {
         await run(["trees", "use", known[i].root], true);
         return;
     }
+    if (i === packAt) {
+        const tree = Tree.open(known[at].root, ctx.env);
+        const shared = ctx.settings.shared().value;
+        const size = (all) => (packPlan(tree, shared, all).media.reduce((s, m) => s + m.size, 0) / 1e6).toFixed(0);
+        const which = await ctx.choose(ui(lang, "ui.pack.which"), [{ label: ui(lang, "ui.pack.opt.records", { mb: size(false) }) }, { label: ui(lang, "ui.pack.opt.all", { mb: size(true) }) }], 0, { back: ui(lang, "ui.browse.back") });
+        if (which === undefined)
+            return;
+        await run(["pack", "--tree", tree.root, ...(which === 1 ? ["--all-images"] : [])]);
+        await partsPause(ctx, lang);
+        return;
+    }
+    if (i === unpackAt) {
+        const answer = (await ctx.ask(ui(lang, "ui.unpack.file"))).trim();
+        if (!answer || answer === "0")
+            return;
+        const resolve = (p) => path.resolve(ctx.cwd, expandHome(p, ctx.env));
+        const dropped = droppedPaths(answer).map(resolve);
+        const file = dropped.length === 1 && fs.existsSync(dropped[0]) ? dropped[0] : resolve(answer);
+        await run(["unpack", file]);
+        await partsPause(ctx, lang);
+        return;
+    }
     const name = (await ctx.ask(ui(lang, "ui.tree.name.new"), ui(lang, "ui.tree.default"))).trim();
     if (name === "0")
         return;

package/dist/cli/ui.js

@@ -41,8 +41,8 @@ export const UI = {
     "ui.menu.waitlist": "What waits for you",
     "ui.menu.settings": "Settings: the agent, working alone, messages, archives, the check",
     "ui.menu.doctor": "Check the installation",
-    "ui.menu.trees": "Another family tree",
-    "ui.menu.newtree": "Create a family tree",
+    "ui.menu.trees": "Another family tree · send or receive one",
+    "ui.menu.newtree": "Create a family tree · send or receive one",
     "ui.menu.quit": "Quit",
     "ui.menu.bye": "See you next time. Start again with: strom",
     "ui.run.how": "How many tasks? (it stops earlier when there is nothing to do; 0 goes back)",
@@ -740,6 +740,37 @@ export const UI = {
     "ui.review.next.human": "The agent takes them up in a conversation or when it works alone.",
     "ui.review.wake.human": "    to go on with it, tell the agent in a conversation",
     "ui.waiting.gone": "This one no longer waits for you — the agent has taken it up meanwhile.",
+    "ui.trees.pack": "pack \"{name}\" to send to someone (a ZIP file)",
+    "ui.trees.unpack": "a family tree someone sent you (a ZIP file)",
+    "ui.pack.which": "Which images go along?",
+    "ui.pack.opt.records": "the ones its records stand on — {mb} MB (the pages searched through the archive gives again)",
+    "ui.pack.opt.all": "all of them — {mb} MB",
+    "ui.pack.done": "Packed \"{name}\": {file} ({mb} MB)",
+    "ui.pack.saved": "  the family tree as last saved, with its history",
+    "ui.pack.images": "  images: {n} ({mb} MB) — the ones its records stand on and the ones nobody can fetch again",
+    "ui.pack.images.all": "  images: all {n} ({mb} MB)",
+    "ui.pack.left": "  left out: {n} images ({mb} MB) — pages searched through; strom fetches them from the archive again when they are needed",
+    "ui.pack.connectors": "  connectors: {list}",
+    "ui.pack.noconnector": "⚠ some images left out came through a connector that is not on this computer — nobody could fetch them again: strom pack --all-images",
+    "ui.pack.missing": "⚠ {n} image(s) the family tree names are not on this computer — not in the package",
+    "ui.pack.send": "Send the file. The one who gets it unpacks it and double-clicks Windows.cmd or macOS.command inside: strom is installed where it is missing and the research opens (with strom already: strom unpack \"<the file>\").",
+    "ui.pack.readme.file": "HOW-TO-CONTINUE.txt",
+    "ui.pack.readme": "The research \"{name}\" - how to go on with it\n=============================================\n\n1. Unpack the whole ZIP file: on Windows right click it - Extract All; on a Mac double click it.\n\n2. In the unpacked folder start, by a double click:\n     Windows:  Windows.cmd\n     macOS:    macOS.command  (the first time: right click - Open; when macOS refuses:\n               System Settings - Privacy & Security - Open Anyway)\n     Linux:    in a terminal: bash Linux.sh\n   It installs Strom Research where it is not yet (the official installer), puts the\n   research in place - the family tree among yours, the images into your shared folder,\n   all of it checked - takes it over on your computer and opens strom.\n\n3. Go on: in strom's menu, the conversation with the agent.\n\nWithout the launchers: install strom yourself\n   Windows (PowerShell):      {win}\n   macOS, Linux (Terminal):   {unix}\nthen: strom unpack \"<this ZIP file>\" (type strom unpack and a space, drag the file into\nthe terminal, press Enter) - or in strom's menu: another family tree - a family tree someone sent you.\n\nThe images the records stand on are in the package. The other pages of the books\n(searched through, nothing found on them) are not, for size - strom fetches them from\nthe archive again when they are needed.\n",
+    "ui.unpack.file": "Drag the ZIP file here (or type where it is; 0 goes back):",
+    "ui.unpack.what": "\"{name}\" (sent from strom {strom}, saved {date}): {images} image(s){connectors} → {root}",
+    "ui.unpack.ask": "Put it here and take it over on this computer?",
+    "ui.unpack.done": "\"{name}\" is here: {root}",
+    "ui.unpack.images": "  {n} image(s) into the shared folder{had}",
+    "ui.unpack.had": " ({n} were here already)",
+    "ui.unpack.connectors": "  connectors: {list}",
+    "ui.unpack.kept": "  connector {name} was here already — yours stays",
+    "ui.unpack.left": "  {n} pages searched through are not in it: strom fetches them from the archive when they are needed",
+    "ui.unpack.adopted": "  taken over on this computer",
+    "ui.unpack.next": "Go on: strom (the menu) or strom chat.",
+    "ui.unpack.same": "this research is here already: {root}",
+    "ui.unpack.person": "only the person at the computer unpacks a research (it adds connectors)",
+    "ui.pack.launch.extract": "First unpack the whole ZIP file - on Windows: right click, Extract All - then start this again from the unpacked folder.",
+    "ui.pack.launch.failed": "Strom Research could not be installed. Install it by the line in HOW-TO-CONTINUE.txt and run this again.",
 };
 /** A text for the person, in their language. */
 export function ui(lang, key, values = {}) {

package/dist/commands/connectors.js

@@ -1094,14 +1094,16 @@ async function fetchWith(ctx, c, request, recordset) {
         });
     if (recordset && request.cmd === "fetch") {
         // what is registered already is not asked for again (a part of an image is not the image)
-        const have = new Set(tree.list("media").filter((m) => m.recordset === recordset && !m.part && m.image !== undefined).map((m) => m.image));
+        // …unless its file is not here (a research handed over without its images): fetched again, put back
+        const here = (m) => fs.existsSync(path.join(shared(ctx), m.file));
+        const have = new Set(tree.list("media").filter((m) => m.recordset === recordset && !m.part && m.image !== undefined && here(m)).map((m) => m.image));
         const asked = request.images;
         request.images = asked.filter((n) => !have.has(n));
         if (!request.images.length)
             return { text: `images ${runs(asked)} of ${recordset} are registered already — nothing fetched`, data: { added: [], again: asked } };
     }
     if (recordset && request.cmd === "part") {
-        const had = tree.list("media").find((m) => m.recordset === recordset && m.image === request.image && m.part && sameRegion(m.part, request.region));
+        const had = tree.list("media").find((m) => m.recordset === recordset && m.image === request.image && m.part && sameRegion(m.part, request.region) && fs.existsSync(path.join(shared(ctx), m.file)));
         if (had)
             return { text: `part ${regionText(request.region)} of image ${request.image} of ${recordset} is registered already: ${had.id} — nothing fetched`, data: { added: [], again: [had.id] } };
     }
@@ -1158,16 +1160,18 @@ async function fetchWith(ctx, c, request, recordset) {
             ? lines(`part ${regionText(m.part)} of image ${request.image} of ${recordset} fetched and registered: ${m.id}${m.width ? ` · ${m.width}×${m.height} px` : ""}${gain ? ` · ${gain.toFixed(1)}× the detail of the whole image` : ""} · ${took}`, gain !== undefined && gain < 1.2 ? "  no sharper than the whole image: the portal gives no more detail than that" : undefined, `look at it: strom media view ${recordset}:${request.image} --crop ${regionText(m.part)} (a view of the image uses the part by itself)`)
             : res.again.length && whole && res.again.includes(whole.id) && r.images.every((i) => isWhole(i.region))
                 ? lines(`the portal's sharpest of image ${request.image} is the whole scan, registered already: ${whole.id}${whole.width ? ` · ${whole.width}×${whole.height} px` : ""} — no part needed`, `look at it: strom media view ${recordset}:${request.image} --crop ${regionText(request.region)}`)
-                : res.again.length
-                    ? lines(`that part is registered already: ${res.again.join(" ")}`, ...res.clashes.map((x) => `⚠ ${x}`))
-                    : "no part fetched";
+                : res.restored.length
+                    ? `part ${regionText(request.region)} of image ${request.image} of ${recordset} fetched again and put back (its file was not here; the same scan): ${res.restored.join(" ")} · ${took}`
+                    : res.again.length
+                        ? lines(`that part is registered already: ${res.again.join(" ")}`, ...res.clashes.map((x) => `⚠ ${x}`))
+                        : "no part fetched";
         data = { ...data, added: res.added.map((x) => ({ id: x.id, image: x.image, part: x.part })), again: res.again };
     }
     else if (recordset && r.images.length) {
         const res = registerImages(tree, shared(ctx), r.images.map((i) => ({ file: i.file, image: i.n, url: i.url, from: from(i.file), fetched })), recordset);
         const nums = res.added.map((m) => m.image).filter((n) => n !== undefined);
-        text = lines(`${res.added.length} image(s) of ${recordset}${nums.length ? ` (images ${Math.min(...nums)}–${Math.max(...nums)})` : ""} fetched and registered · ${took}`, res.again.length ? `${res.again.length} already registered` : undefined, ...res.clashes.slice(0, 10).map((x) => `⚠ ${x}`), res.woken.length ? `back in the queue (they waited for these images): ${res.woken.join(" ")}` : undefined);
-        data = { ...data, added: res.added.map((m) => ({ id: m.id, image: m.image })), again: res.again, woken: res.woken, clashes: res.clashes };
+        text = lines(res.added.length || !res.restored.length ? `${res.added.length} image(s) of ${recordset}${nums.length ? ` (images ${Math.min(...nums)}–${Math.max(...nums)})` : ""} fetched and registered · ${took}` : undefined, res.restored.length ? `${res.restored.length} image(s) of ${recordset} fetched again and put back (their file was not here; the same scan): ${res.restored.slice(0, 5).join(" ")}${res.restored.length > 5 ? " …" : ""} · ${took}` : undefined, res.again.length ? `${res.again.length} already registered` : undefined, ...res.clashes.slice(0, 10).map((x) => `⚠ ${x}`), res.woken.length ? `back in the queue (they waited for these images): ${res.woken.join(" ")}` : undefined);
+        data = { ...data, added: res.added.map((m) => ({ id: m.id, image: m.image })), again: res.again, restored: res.restored, woken: res.woken, clashes: res.clashes };
         fs.rmSync(workDir, { recursive: true, force: true });
     }
     else if (r.images.length) {
@@ -1307,7 +1311,7 @@ async function takeOver(ctx, c, result) {
         if (plan.recordset) {
             const res = registerImages(tree, shared(ctx), mine.map((t) => ({ file: t.file, image: t.item.n, url: t.item.url, from: `connector ${c.name} · your browser · ${path.basename(t.file)}`, part: t.item.region, fetched })), plan.recordset);
             added.push(...res.added.map((m) => ({ id: m.id, ...(m.image !== undefined ? { image: m.image } : {}) })));
-            again.push(...res.again);
+            again.push(...res.again, ...res.restored);
             notes.push(...res.clashes);
             woken.push(...res.woken);
             for (const t of mine)

package/dist/commands/index.js

@@ -5,6 +5,7 @@ import "./trees.js";
 import "./research.js";
 import "./intake.js";
 import "./sync.js";
+import "./pack.js";
 import "./tasks.js";
 import "./people.js";
 import "./batch.js";

package/dist/commands/media.js

@@ -26,12 +26,20 @@ export function registerImages(tree, shared, items, recordset) {
     const known = new Map(tree.list("media").filter((m) => !m.retracted).map((m) => [m.sha, m]));
     const added = [];
     const again = [];
+    const restored = [];
     const clashes = [];
     const copies = [];
     tree.withTreeLock(() => {
         for (const it of items) {
             const sha = fileSha256(it.file);
             const k = known.get(sha);
+            if (k && !tree.dryRun && !fs.existsSync(path.join(shared, k.file))) {
+                // its file is not here (a research handed over without its images): the same scan, put back where it was
+                fs.mkdirSync(path.dirname(path.join(shared, k.file)), { recursive: true });
+                fs.copyFileSync(it.file, path.join(shared, k.file));
+                restored.push(k.id);
+                continue;
+            }
             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
@@ -85,7 +93,7 @@ export function registerImages(tree, shared, items, recordset) {
             });
             woken.push(t.id);
         }
-    return { added, again, woken, clashes, copies };
+    return { added, again, restored, woken, clashes, copies };
 }
 function sharedDir(ctx) {
     return ctx.settings.shared().value;
@@ -264,7 +272,7 @@ register({
                     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);
+        const { added, again, restored, 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
@@ -275,7 +283,7 @@ register({
         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);
+            : restored.length ? undefined : "no new images", restored.length ? `${restored.length} image(s) put back (their file was not here; the same scan): ${restored.slice(0, 5).join(" ")}${restored.length > 5 ? " …" : ""}` : undefined, 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 } };
     },
 }, {

package/dist/commands/pack.js

@@ -0,0 +1,131 @@
+// pack · unpack — a research handed to someone else as one ZIP file.
+import fs from "node:fs";
+import path from "node:path";
+import { register } from "../cli/registry.js";
+import { lines } from "../cli/format.js";
+import { ui } from "../cli/ui.js";
+import { NeedsConsentError, UsageError } from "../core/errors.js";
+import { findPack, freeRoot, INSTALL_UNIX, INSTALL_WINDOWS, packPlan, unpack, writePack } from "../core/pack.js";
+import { desktopDir, userHome } from "../core/paths.js";
+import { safeFolderName } from "../core/text.js";
+import { Tree } from "../core/tree.js";
+import { syncAgentFiles } from "../agents/files.js";
+import { setupWizard } from "../cli/wizard.js";
+import { isAgent } from "../core/which.js";
+import { ensureShared } from "./setup.js";
+const mb = (bytes) => (bytes / 1e6 < 10 ? (bytes / 1e6).toFixed(1) : Math.round(bytes / 1e6).toString());
+register({
+    path: ["pack"],
+    summary: "Pack the research into one ZIP file for someone to go on with it (the tree, the images its records stand on, the connectors)",
+    group: "research",
+    tree: true,
+    description: "The family tree as it was last saved, with its history; the images its records stand on, the images nobody can\n" +
+        "fetch again (saved by hand, the family's material) and the connectors that fetched the others. The pages only\n" +
+        "searched through are left out — the archive gives the same scan again (strom fetch puts it back, checked);\n" +
+        "--all-images takes them too. Logins, settings and seal keys never go along. The one who gets it: strom unpack.",
+    options: [
+        { name: "out", type: "string", value: "<file.zip>", description: "where to write it (default: the desktop, named after the tree and the day)" },
+        { name: "all-images", type: "boolean", description: "every image, the pages searched through too" },
+    ],
+    examples: ["strom pack", "strom pack --all-images", 'strom pack --out "~/Novákovi.zip"'],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        const shared = ctx.settings.shared().value;
+        const lang = ctx.uiLang();
+        const all = Boolean(opts["all-images"]);
+        const day = new Date().toISOString().slice(0, 10);
+        const base = `${safeFolderName(tree.config.name) || "tree"} ${day}`;
+        let out;
+        if (opts.out)
+            out = ctx.resolvePath(String(opts.out));
+        else {
+            const desk = desktopDir(ctx.env);
+            const dir = fs.existsSync(desk) ? desk : userHome(ctx.env);
+            out = path.join(dir, `${base}.zip`);
+            for (let n = 2; fs.existsSync(out); n++)
+                out = path.join(dir, `${base} (${n}).zip`);
+        }
+        if (!out.toLowerCase().endsWith(".zip"))
+            out += ".zip";
+        if (fs.existsSync(out))
+            throw new UsageError(`${ctx.display(out)} is there already`, { hint: "another --out, or without it" });
+        if (ctx.dryRun) {
+            const plan = packPlan(tree, shared, all);
+            const bytes = plan.media.reduce((s, m) => s + m.size, 0);
+            return { text: `dry run: would pack "${tree.config.name}" with ${plan.media.length} image(s) (${mb(bytes)} MB) into ${ctx.display(out)} — nothing written`, data: { out, plan } };
+        }
+        const readme = {
+            name: ui(tree.config.lang, "ui.pack.readme.file"),
+            text: ui(tree.config.lang, "ui.pack.readme", { name: tree.config.name, win: INSTALL_WINDOWS, unix: INSTALL_UNIX }),
+        };
+        const say = { extract: ui(tree.config.lang, "ui.pack.launch.extract"), failed: ui(tree.config.lang, "ui.pack.launch.failed") };
+        const r = writePack(tree, shared, out, { all, readme, say });
+        const took = r.plan.media.reduce((s, m) => s + m.size, 0);
+        const text = lines(ui(lang, "ui.pack.done", { name: tree.config.name, file: ctx.display(r.file), mb: mb(r.bytes) }), ui(lang, "ui.pack.saved"), ui(lang, all ? "ui.pack.images.all" : "ui.pack.images", { n: r.plan.media.length, mb: mb(took) }), r.plan.left.count ? ui(lang, "ui.pack.left", { n: r.plan.left.count, mb: mb(r.plan.left.bytes) }) : undefined, r.plan.connectors.length ? ui(lang, "ui.pack.connectors", { list: r.plan.connectors.join(", ") }) : undefined, r.plan.left.count && r.plan.left.connectors ? ui(lang, "ui.pack.noconnector") : undefined, r.plan.missing.length ? ui(lang, "ui.pack.missing", { n: r.plan.missing.length }) : undefined, "", ui(lang, "ui.pack.send"));
+        return { text, data: { file: r.file, bytes: r.bytes, manifest: r.manifest, missing: r.plan.missing } };
+    },
+});
+register({
+    path: ["unpack"],
+    summary: "Put a research someone packed for you in place and take it over on this computer (the person runs this)",
+    group: "research",
+    description: "The ZIP file of strom pack, or the folder it was unpacked into. The tree goes among the trees (a free name), its\n" +
+        "images into the shared folder (each checked against its SHA-256), its connectors into the plugins where there is\n" +
+        "none of that name (yours stays); the tree is checked whole and taken over on this computer. It adds connectors:\n" +
+        "only the person at the computer runs it — never an agent.",
+    args: [{ name: "file", description: "the ZIP file (or the folder it was unpacked into)", required: true }],
+    examples: ['strom unpack "~/Downloads/Novákovi 2026-09-29.zip"'],
+    async run(ctx, { args }) {
+        const lang = ctx.uiLang();
+        const src = ctx.resolvePath(args[0]);
+        if (!ctx.interactive)
+            throw new NeedsConsentError([{ key: "unpack", kind: "consent", question: ui(lang, "ui.unpack.person"), set: `strom unpack "${src}"` }]);
+        // someone new to strom (a launcher of the package installed it just now): the setup wizard first
+        if (!ctx.settings.home() && !isAgent(ctx.env)) {
+            await setupWizard(ctx);
+            ctx.settings.reload();
+        }
+        await ctx.requireHome();
+        const treesDir = ctx.settings.trees().value;
+        const shared = ctx.settings.shared().value;
+        const pack = findPack(src);
+        try {
+            const m = pack.manifest;
+            const same = ctx.knownTrees().find((t) => {
+                try {
+                    return JSON.parse(fs.readFileSync(path.join(t.root, "strom.json"), "utf8")).id === m.tree.id;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (same)
+                throw new UsageError(ui(lang, "ui.unpack.same", { root: ctx.display(same.root) }), { hint: `strom trees use "${same.root}"` });
+            const target = freeRoot(treesDir, m.tree.name);
+            ctx.io.stdout(ui(lang, "ui.unpack.what", {
+                name: m.tree.name,
+                strom: m.strom,
+                date: m.created.slice(0, 10),
+                images: m.media.length,
+                connectors: m.connectors.length ? ` · ${m.connectors.join(", ")}` : "",
+                root: ctx.display(target),
+            }) + "\n");
+            if (!(await ctx.confirm(ui(lang, "ui.unpack.ask"), true)))
+                return { text: "", data: { unpacked: false } };
+            ensureShared(shared);
+            const r = unpack(pack, treesDir, shared, ctx.env);
+            // the tree's own instructions and permissions, for this computer's folders
+            const tree = Tree.open(r.root, ctx.env);
+            const files = syncAgentFiles(tree);
+            tree.withTreeLock(() => tree.commit(`Agent instructions: ${files.join(", ")}`, files));
+            ctx.settings.config.currentTree = r.root;
+            ctx.settings.save();
+            const text = lines(ui(lang, "ui.unpack.done", { name: r.name, root: ctx.display(r.root) }), r.images || r.imagesHad ? ui(lang, "ui.unpack.images", { n: r.images, had: r.imagesHad ? ui(lang, "ui.unpack.had", { n: r.imagesHad }) : "" }) : undefined, r.connectors.length ? ui(lang, "ui.unpack.connectors", { list: r.connectors.join(", ") }) : undefined, ...r.connectorsKept.map((c) => ui(lang, "ui.unpack.kept", { name: c })), m.left.count ? ui(lang, "ui.unpack.left", { n: m.left.count }) : undefined, r.adopted ? ui(lang, "ui.unpack.adopted") : undefined, "", ui(lang, "ui.unpack.next"));
+            return { text, data: { unpacked: true, ...r } };
+        }
+        finally {
+            if (pack.tmp)
+                fs.rmSync(pack.tmp, { recursive: true, force: true });
+        }
+    },
+});

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/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.1";
+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) {

package/dist/core/zip.js

@@ -0,0 +1,226 @@
+// ZIP files without a dependency: written as they go (deflated where it helps,
+// images stored as they are), read by their central directory. No ZIP64: a
+// package over 4 GB or 65 535 files is refused. Names are UTF-8.
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { StromError } from "./errors.js";
+const LOCAL = 0x04034b50;
+const CENTRAL = 0x02014b50;
+const END = 0x06054b50;
+const MAX = 0xffffffff;
+/** Already compressed: deflating them again only costs time. */
+const PACKED = /\.(jpe?g|png|gif|webp|tiff?|jp2|zip|gz|pdf|mp4|mov|mp3|heic)$/i;
+export class ZipTooLarge extends StromError {
+}
+function dos(d) {
+    const y = Math.max(1980, d.getFullYear());
+    return {
+        time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+        date: ((y - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+    };
+}
+export class ZipWriter {
+    fd;
+    offset = 0;
+    entries = [];
+    file;
+    constructor(file) {
+        this.file = file;
+        this.fd = fs.openSync(file, "w");
+    }
+    get bytes() {
+        return this.offset;
+    }
+    write(b) {
+        fs.writeSync(this.fd, b);
+        this.offset += b.length;
+    }
+    /** One file; `name` with forward slashes. */
+    add(name, data, opts = {}) {
+        let body = data;
+        let method = 0;
+        if (!PACKED.test(name) && !name.endsWith("/") && data.length > 64) {
+            const z = zlib.deflateRawSync(data);
+            if (z.length < data.length) {
+                body = z;
+                method = 8;
+            }
+        }
+        const n = Buffer.from(name, "utf8");
+        if (this.entries.length >= 0xffff || this.offset + 30 + n.length + body.length + 46 * (this.entries.length + 1) > MAX)
+            throw new ZipTooLarge("the package would be over 4 GB or 65 535 files");
+        const e = { name: n, crc: zlib.crc32(data), size: data.length, csize: body.length, method, offset: this.offset, ...dos(opts.mtime ?? new Date()), mode: opts.mode ?? (name.endsWith("/") ? 0o755 : 0o644) };
+        const h = Buffer.alloc(30);
+        h.writeUInt32LE(LOCAL, 0);
+        h.writeUInt16LE(20, 4);
+        h.writeUInt16LE(0x0800, 6); // names in UTF-8
+        h.writeUInt16LE(method, 8);
+        h.writeUInt16LE(e.time, 10);
+        h.writeUInt16LE(e.date, 12);
+        h.writeUInt32LE(e.crc, 14);
+        h.writeUInt32LE(e.csize, 18);
+        h.writeUInt32LE(e.size, 22);
+        h.writeUInt16LE(n.length, 26);
+        h.writeUInt16LE(0, 28);
+        this.write(h);
+        this.write(n);
+        this.write(body);
+        this.entries.push(e);
+    }
+    /** An empty folder (git needs its empty ones). */
+    addDir(name) {
+        this.add(name.endsWith("/") ? name : `${name}/`, Buffer.alloc(0));
+    }
+    /** A file from disk, its mode and time kept. */
+    addFile(name, file) {
+        const st = fs.statSync(file);
+        this.add(name, fs.readFileSync(file), { mode: st.mode & 0o777, mtime: st.mtime });
+    }
+    close() {
+        const start = this.offset;
+        for (const e of this.entries) {
+            const c = Buffer.alloc(46);
+            c.writeUInt32LE(CENTRAL, 0);
+            c.writeUInt16LE((3 << 8) | 20, 4); // made on Unix: the mode is kept
+            c.writeUInt16LE(20, 6);
+            c.writeUInt16LE(0x0800, 8);
+            c.writeUInt16LE(e.method, 10);
+            c.writeUInt16LE(e.time, 12);
+            c.writeUInt16LE(e.date, 14);
+            c.writeUInt32LE(e.crc, 16);
+            c.writeUInt32LE(e.csize, 20);
+            c.writeUInt32LE(e.size, 24);
+            c.writeUInt16LE(e.name.length, 28);
+            const dir = e.name[e.name.length - 1] === 0x2f;
+            c.writeUInt32LE((((dir ? 0o040000 : 0o100000) | e.mode) << 16 | (dir ? 0x10 : 0)) >>> 0, 38);
+            c.writeUInt32LE(e.offset, 42);
+            this.write(c);
+            this.write(e.name);
+        }
+        const end = Buffer.alloc(22);
+        end.writeUInt32LE(END, 0);
+        end.writeUInt16LE(this.entries.length, 8);
+        end.writeUInt16LE(this.entries.length, 10);
+        end.writeUInt32LE(this.offset - start, 12);
+        end.writeUInt32LE(start, 16);
+        this.write(end);
+        fs.closeSync(this.fd);
+    }
+    /** Give up: the half-written file goes. */
+    abort() {
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch {
+            // closed already
+        }
+        fs.rmSync(this.file, { force: true });
+    }
+}
+export class BadZip extends StromError {
+}
+/** A name a package may carry: relative, inside it, no drive, no "..". Undefined for anything else. */
+export function safeEntryName(raw) {
+    const name = raw.replace(/\\/g, "/");
+    if (!name || name.startsWith("/") || /^[A-Za-z]:/.test(name) || name.includes("\0"))
+        return undefined;
+    const parts = name.split("/").filter((p) => p !== "" && p !== ".");
+    if (parts.some((p) => p === ".."))
+        return undefined;
+    return parts.join("/") + (name.endsWith("/") ? "/" : "");
+}
+/** The entries of a ZIP file (what a system's own "compress" makes too). Unsafe names: BadZip. */
+export function readZip(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const tail = Buffer.alloc(Math.min(size, 22 + 0xffff));
+        fs.readSync(fd, tail, 0, tail.length, size - tail.length);
+        let at = -1;
+        for (let i = tail.length - 22; i >= 0; i--)
+            if (tail.readUInt32LE(i) === END) {
+                at = i;
+                break;
+            }
+        if (at < 0)
+            throw new BadZip("not a ZIP file");
+        const count = tail.readUInt16LE(at + 10);
+        const cdSize = tail.readUInt32LE(at + 12);
+        const cdStart = tail.readUInt32LE(at + 16);
+        if (cdStart === MAX || count === 0xffff)
+            throw new BadZip("a ZIP64 file (over 4 GB) — unpack it with the system and give the folder");
+        const cd = Buffer.alloc(cdSize);
+        fs.readSync(fd, cd, 0, cdSize, cdStart);
+        const out = [];
+        let p = 0;
+        for (let i = 0; i < count; i++) {
+            if (cd.readUInt32LE(p) !== CENTRAL)
+                throw new BadZip("a damaged ZIP file");
+            const flags = cd.readUInt16LE(p + 8);
+            const nameLen = cd.readUInt16LE(p + 28);
+            const extraLen = cd.readUInt16LE(p + 30);
+            const commentLen = cd.readUInt16LE(p + 32);
+            const raw = cd.subarray(p + 46, p + 46 + nameLen);
+            const rawName = flags & 0x0800 ? raw.toString("utf8") : raw.toString("latin1");
+            const name = safeEntryName(rawName);
+            if (name === undefined)
+                throw new BadZip(`a file outside the package: ${rawName}`);
+            const attr = cd.readUInt32LE(p + 38) >>> 16;
+            out.push({
+                name,
+                method: cd.readUInt16LE(p + 10),
+                crc: cd.readUInt32LE(p + 16),
+                csize: cd.readUInt32LE(p + 20),
+                size: cd.readUInt32LE(p + 24),
+                offset: cd.readUInt32LE(p + 42),
+                dir: name.endsWith("/"),
+                link: (attr & 0o170000) === 0o120000,
+            });
+            p += 46 + nameLen + extraLen + commentLen;
+        }
+        return out;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** The content of one entry, its checksum checked. */
+export function readEntry(file, e) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const h = Buffer.alloc(30);
+        fs.readSync(fd, h, 0, 30, e.offset);
+        if (h.readUInt32LE(0) !== LOCAL)
+            throw new BadZip(`a damaged ZIP file (${e.name})`);
+        const start = e.offset + 30 + h.readUInt16LE(26) + h.readUInt16LE(28);
+        const body = Buffer.alloc(e.csize);
+        fs.readSync(fd, body, 0, e.csize, start);
+        const data = e.method === 0 ? body : e.method === 8 ? zlib.inflateRawSync(body) : undefined;
+        if (!data)
+            throw new BadZip(`${e.name}: a compression strom does not read (${e.method})`);
+        if (data.length !== e.size || zlib.crc32(data) !== e.crc)
+            throw new BadZip(`${e.name} is damaged in the ZIP file`);
+        return data;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Unpack into a folder (which must not hold the names already). Links and the system's own litter are left out. */
+export function unzipTo(file, dir, entries = readZip(file)) {
+    const written = [];
+    for (const e of entries) {
+        if (e.link || e.name.startsWith("__MACOSX/") || path.posix.basename(e.name) === ".DS_Store")
+            continue;
+        const to = path.join(dir, ...e.name.split("/").filter(Boolean));
+        if (e.dir) {
+            fs.mkdirSync(to, { recursive: true });
+            continue;
+        }
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.writeFileSync(to, readEntry(file, e));
+        written.push(e.name);
+    }
+    return written;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strom-research",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Genealogical research toolkit for AI coding agents",
   "type": "module",
   "bin": {