strom-research 1.0.0

package/dist/core/stories.js

@@ -0,0 +1,61 @@
+// Stories of the ancestors (the setting `stories`, on by default): once records
+// tell enough of a person's life, strom proposes the task of writing it for the
+// family — and of adding to it when records brought more after it was written.
+// The story goes into the family book of the Strom app (GEDCOM _STORY).
+import { ancestorGenerations, displayName, familiesAsPartner, lifespan } from "./people.js";
+import { phrase } from "./phrases.js";
+const FROM_RECORDS = new Set(["proven", "probable"]);
+const BIRTHS = new Set(["BIRT", "CHR", "BAPM"]);
+const OPEN = new Set(["open", "doing", "parked", "waiting"]);
+const FINISHED = new Set(["done", "dropped"]);
+/** Enough to tell a life: a birth or baptism from a record, and more facts from records. */
+export const STORY_MIN_FACTS = 3;
+/** New facts from records that make a written story worth adding to. */
+export const STORY_NEW_FACTS = 2;
+/** The facts of a person's life that records support: their own, and their marriages. */
+export function factsFromRecords(tree, p) {
+    const own = p.events.filter((e) => !e.retracted && FROM_RECORDS.has(e.status));
+    const marriages = familiesAsPartner(tree, p.id).flatMap((f) => f.events.filter((e) => !e.retracted && FROM_RECORDS.has(e.status)));
+    return [...own, ...marriages];
+}
+/** The stories strom proposes to write (or add to) for the ancestors of a research. */
+export function storyProposals(tree, research) {
+    if (research.direction !== "ancestors")
+        return [];
+    const lang = tree.lang;
+    const narrate = tree.list("task").filter((t) => t.level === "narrate");
+    const out = [];
+    for (const [id, generation] of ancestorGenerations(tree, research.focus, research.limits?.generations ?? 50)) {
+        const p = tree.get(id);
+        if (!p || p.retracted)
+            continue;
+        const facts = factsFromRecords(tree, p);
+        if (facts.length < STORY_MIN_FACTS || !facts.some((e) => BIRTHS.has(e.kind)))
+            continue;
+        const mine = narrate.filter((t) => t.subject.includes(id));
+        if (mine.some((t) => OPEN.has(t.state)))
+            continue;
+        // Dropped since the story was written (or with none): that was the answer — not again until the story changes.
+        const since = p.story?.at ?? "";
+        if (mine.some((t) => t.state === "dropped" && t.updated >= since))
+            continue;
+        // Done, yet no story: somebody decided so; the user can add the task by hand.
+        if (!p.story && mine.some((t) => FINISHED.has(t.state)))
+            continue;
+        const name = `${displayName(p)}${lifespan(p) ? ` (${lifespan(p)})` : ""}`;
+        const fresh = p.story ? facts.filter((e) => !p.story.facts.includes(e.id)) : facts;
+        if (p.story && fresh.length < STORY_NEW_FACTS)
+            continue;
+        out.push({
+            level: "narrate",
+            priority: 1, // the research first; a story when there is a moment for it
+            what: phrase(lang, p.story ? "story.more.what" : "story.what", { name, count: fresh.length }),
+            where: [phrase(lang, "story.where", { id })],
+            why: phrase(lang, "story.why", { count: facts.length, generation, research: research.name }),
+            doneWhen: phrase(lang, "story.done", { id }),
+            subject: [id],
+            research: research.id,
+        });
+    }
+    return out;
+}

package/dist/core/stromapp.js

@@ -0,0 +1,138 @@
+// The Strom app (https://stromapp.info) — a web app, often installed from the
+// browser as an app of its own. strom notices it quietly and never asks: the
+// app says so when it starts strom (STROM_APP), or its shortcut is found among
+// the apps the browser installed (only names are looked at — never the
+// browser's history). What strom does with it: say which file to import into
+// the app. The user can say yes or no for good (strom config set strom.app).
+import fs from "node:fs";
+import path from "node:path";
+import { userHome } from "./paths.js";
+import { foldText } from "./text.js";
+export const STROM_APP_URL = "https://stromapp.info/run/";
+/** The Strom app's address: STROM_APP_URL points strom at another copy of it (its development, http://127.0.0.1:8080/). */
+export function stromAppUrl(env) {
+    const url = env.STROM_APP_URL?.trim();
+    return url && /^https?:\/\//.test(url) ? url : STROM_APP_URL;
+}
+/**
+ * The Strom app opens a research by itself (from its version 3.0.0; its import
+ * contract, docs/GEDCOM-IMPORT.md in the Strom repository): ?import-url=<the
+ * tree's GEDCOM on this computer> opens that tree — created the first time,
+ * updated after — and ?live=<the bridge> follows it while it goes on (see
+ * core/live.ts). On since stromapp.info runs 3.0.0; a copy of the app named by
+ * STROM_APP_URL (a beta, its development) is taken as current too.
+ */
+export const APP_OPENS_RESEARCH = true;
+export function appOpensResearch(env) {
+    return APP_OPENS_RESEARCH || Boolean(env.STROM_APP_URL?.trim());
+}
+/** The address that opens the Strom app following a research through its bridge. */
+export function liveAppUrl(bridge, env) {
+    return `${stromAppUrl(env)}?live=${encodeURIComponent(bridge)}`;
+}
+/** The address that opens a research's GEDCOM (served on this computer) in the Strom app. */
+export function importAppUrl(file, env) {
+    return `${stromAppUrl(env)}?import-url=${encodeURIComponent(file)}`;
+}
+/** The page for people starting research with an AI agent: what an agent is, which one, how to install it. */
+export const RESEARCH_URL = "https://stromapp.info/research/";
+/** That page in the user's language (it speaks en, cs, de), at a section: "agents". */
+export function researchUrl(lang, section) {
+    return `${RESEARCH_URL}${["cs", "de"].includes(lang) ? `?lang=${lang}` : ""}${section ? `#${section}` : ""}`;
+}
+/** "Strom", "Strom - Family Tree" — not this tool ("Strom Research"). */
+export function isStromName(name) {
+    const n = foldText(name).trim();
+    return /^strom(\s*[-–:|]\s*.*)?$/u.test(n) && !/research|vyzkum/u.test(n);
+}
+function entries(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** The Strom app installed from a browser, if there is one. */
+export function installedStromApp(env, platform = process.platform) {
+    const home = userHome(env);
+    if (platform === "darwin") {
+        const apps = path.join(home, "Applications");
+        const browsers = [
+            ["Chrome Apps.localized", "Chrome app"],
+            ["Chrome Apps", "Chrome app"],
+            ["Edge Apps.localized", "Edge app"],
+            ["Brave Browser Apps.localized", "Brave app"],
+            ["Chromium Apps.localized", "Chromium app"],
+            ["Vivaldi Apps.localized", "Vivaldi app"],
+        ];
+        for (const [dir, kind] of browsers)
+            for (const f of entries(path.join(apps, dir)))
+                if (f.endsWith(".app") && isStromName(f.slice(0, -4)))
+                    return { path: path.join(apps, dir, f), kind };
+        // Safari: File → Add to Dock puts the web app straight into ~/Applications.
+        for (const f of entries(apps))
+            if (f.endsWith(".app") && isStromName(f.slice(0, -4)))
+                return { path: path.join(apps, f), kind: "Safari web app" };
+        return undefined;
+    }
+    if (platform === "win32") {
+        const programs = path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Microsoft", "Windows", "Start Menu", "Programs");
+        for (const dir of ["Chrome Apps", "Edge Apps", ""]) {
+            const d = path.join(programs, dir);
+            for (const f of entries(d))
+                if (f.toLowerCase().endsWith(".lnk") && isStromName(f.slice(0, -4)))
+                    return { path: path.join(d, f), kind: dir ? dir.replace(/s$/, "") : "app" };
+        }
+        return undefined;
+    }
+    const dir = path.join(env.XDG_DATA_HOME ?? path.join(home, ".local", "share"), "applications");
+    for (const f of entries(dir)) {
+        if (!f.endsWith(".desktop"))
+            continue;
+        let text = "";
+        try {
+            text = fs.readFileSync(path.join(dir, f), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const name = /^Name=(.*)$/m.exec(text)?.[1];
+        if (name && isStromName(name) && /--app-id=|--app=/.test(text))
+            return { path: path.join(dir, f), kind: "browser app" };
+    }
+    return undefined;
+}
+/** What strom knows of the Strom app: the user's word first, then what it noticed. */
+export function stromAppState(settings) {
+    const said = settings.config.stromApp;
+    if (said === "yes" || said === "no")
+        return said;
+    return settings.config.stromAppSeen ? "seen" : "unknown";
+}
+/**
+ * Notice the Strom app and remember it (quietly, in the user config). `look`
+ * also checks the apps installed from browsers — a few folder listings, done
+ * where it is cheap to do (setup, the menu), not on every command.
+ */
+export function noticeStromApp(settings, env, opts = {}) {
+    if (settings.config.stromApp === "no")
+        return undefined;
+    const at = new Date().toISOString();
+    if (env.STROM_APP) {
+        const version = env.STROM_APP_VERSION;
+        const seen = settings.config.stromAppSeen;
+        if (!seen || seen.via !== "started strom" || seen.version !== version) {
+            settings.config.stromAppSeen = { via: "started strom", at, ...(version ? { version } : {}) };
+            settings.save();
+        }
+    }
+    if (!opts.look)
+        return undefined;
+    const app = installedStromApp(env);
+    if (app && !settings.config.stromAppSeen) {
+        settings.config.stromAppSeen = { via: app.kind, at };
+        settings.save();
+    }
+    return app;
+}

package/dist/core/text.js

@@ -0,0 +1,104 @@
+// Text helpers for matching names across spellings and diacritics.
+/** Lowercase, strip diacritics, collapse whitespace: "Víšek  Antonín" -> "visek antonin". */
+export function foldText(s) {
+    return s
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/ß/g, "ss")
+        .replace(/[łŁ]/g, "l")
+        .replace(/[đĐ]/g, "d")
+        .replace(/[øØ]/g, "o")
+        .replace(/[æÆ]/g, "ae")
+        .replace(/[œŒ]/g, "oe")
+        .replace(/[þÞ]/g, "th")
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Words of a folded text — in any script: "Шевчук Іван" has words too. */
+export function tokens(s) {
+    return foldText(s)
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(Boolean);
+}
+// Named character references of web pages. A Latin letter with a mark is composed from its
+// name (á š ů ő …); the rest are listed.
+const MARKS = {
+    acute: "\u0301", grave: "\u0300", circ: "\u0302", tilde: "\u0303", uml: "\u0308", ring: "\u030a", cedil: "\u0327",
+    caron: "\u030c", ogon: "\u0328", dblac: "\u030b", breve: "\u0306", macr: "\u0304", dot: "\u0307",
+};
+const GREEK = "Alpha Beta Gamma Delta Epsilon Zeta Eta Theta Iota Kappa Lambda Mu Nu Xi Omicron Pi Rho Sigma Tau Upsilon Phi Chi Psi Omega".split(" ");
+const NAMED = {
+    amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", shy: "\u00ad", ensp: "\u2002", emsp: "\u2003", thinsp: "\u2009",
+    zwnj: "\u200c", zwj: "\u200d", lrm: "\u200e", rlm: "\u200f", ndash: "–", mdash: "—", hellip: "…", bull: "•", middot: "·",
+    laquo: "«", raquo: "»", lsaquo: "‹", rsaquo: "›", ldquo: "“", rdquo: "”", bdquo: "„", lsquo: "‘", rsquo: "’", sbquo: "‚",
+    prime: "′", Prime: "″", copy: "©", reg: "®", trade: "™", deg: "°", plusmn: "±", times: "×", divide: "÷", sect: "§", para: "¶",
+    dagger: "†", Dagger: "‡", permil: "‰", euro: "€", pound: "£", cent: "¢", yen: "¥", curren: "¤", brvbar: "¦", not: "¬",
+    micro: "µ", ordf: "ª", ordm: "º", sup1: "¹", sup2: "²", sup3: "³", frac14: "¼", frac12: "½", frac34: "¾", iexcl: "¡",
+    iquest: "¿", acute: "´", uml: "¨", cedil: "¸", macr: "¯", larr: "←", rarr: "→", uarr: "↑", darr: "↓", harr: "↔",
+    szlig: "ß", aelig: "æ", AElig: "Æ", oelig: "œ", OElig: "Œ", oslash: "ø", Oslash: "Ø", eth: "ð", ETH: "Ð", thorn: "þ",
+    THORN: "Þ", lstrok: "ł", Lstrok: "Ł", dstrok: "đ", Dstrok: "Đ", hstrok: "ħ", Hstrok: "Ħ", tstrok: "ŧ", Tstrok: "Ŧ",
+    eng: "ŋ", ENG: "Ŋ", imath: "ı", inodot: "ı", sigmaf: "ς", sdot: "⋅",
+    ...Object.fromEntries(GREEK.flatMap((g, i) => [
+        [g, String.fromCodePoint(0x391 + i + (i > 16 ? 1 : 0))],
+        [g.toLowerCase(), String.fromCodePoint(0x3b1 + i + (i > 16 ? 1 : 0))],
+    ])),
+};
+function reference(name) {
+    if (name[0] === "#") {
+        const cp = name[1] === "x" || name[1] === "X" ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+        return cp > 0 && cp <= 0x10ffff && (cp < 0xd800 || cp > 0xdfff) ? String.fromCodePoint(cp) : undefined;
+    }
+    if (Object.hasOwn(NAMED, name))
+        return NAMED[name];
+    const m = /^([A-Za-z])([a-z]+)$/.exec(name);
+    // a dot above only on the letters that have one (&odot; is ⊙, not ȯ)
+    const mark = m && Object.hasOwn(MARKS, m[2]) && (m[2] !== "dot" || "cegzCEGIZ".includes(m[1])) ? MARKS[m[2]] : undefined;
+    const ch = mark && (m[1] + mark).normalize("NFC");
+    return ch && ch.length === 1 ? ch : undefined;
+}
+const ESCAPED = { "/": "/", "\\": "\\", '"': '"', "'": "'", n: "\n", r: "\r", t: "\t" };
+/**
+ * A page's text as a person reads it, with where each of its characters is in the page:
+ * character references (&aacute; &#237; &#xE1; &nbsp;) and the escapes of scripts and JSON
+ * (\u00e1 \/ \") written out. `at[i]` is the page's index of the text's character i, and
+ * `at[text.length]` the page's length. Undefined when there is nothing to write out.
+ */
+export function readable(page) {
+    const at = new Int32Array(page.length + 1); // written out, a text is never longer than its page
+    const parts = [];
+    let n = 0;
+    let last = 0;
+    const keep = (to) => {
+        for (let i = last; i < to; i++)
+            at[n++] = i;
+        parts.push(page.slice(last, to));
+    };
+    for (const m of page.matchAll(/&(#[0-9]{1,7}|#[xX][0-9a-fA-F]{1,6}|[A-Za-z][A-Za-z0-9]{1,31});|\\(u[0-9a-fA-F]{4}|[/\\"'nrt])/g)) {
+        const ch = m[1] !== undefined ? reference(m[1]) : m[2][0] === "u" ? String.fromCharCode(parseInt(m[2].slice(1), 16)) : ESCAPED[m[2]];
+        if (ch === undefined)
+            continue;
+        keep(m.index);
+        for (let k = 0; k < ch.length; k++)
+            at[n++] = m.index;
+        parts.push(ch);
+        last = m.index + m[0].length;
+    }
+    if (!parts.length)
+        return undefined;
+    keep(page.length);
+    at[n] = page.length;
+    return { text: parts.join(""), at: at.subarray(0, n + 1) };
+}
+/** Folder-safe name keeping diacritics (works on Windows, macOS, Linux). */
+export function safeFolderName(name) {
+    const cleaned = name
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/[. ]+$/, "");
+    const reserved = /^(con|prn|aux|nul|com\d|lpt\d)$/i;
+    if (cleaned === "" || reserved.test(cleaned) || cleaned.toLowerCase() === "shared")
+        return `${cleaned || "tree"}-1`;
+    return cleaned;
+}