strom-research 1.0.0

package/dist/commands/guide.js

@@ -0,0 +1,160 @@
+// The agent guide: what an agent needs to know to do research with strom,
+// with no other documentation. Keep it short — it is read at the start of
+// sessions and costs tokens every time. Every command in it must exist
+// (test/cli/examples.test.ts checks them against the registry).
+import { langName } from "../core/lang.js";
+export function guideText(lang) {
+    const language = lang
+        ? `The research language of this tree is ${langName(lang)} (${lang}): talk to the user in ${langName(lang)} and write notes, tasks and stories in ${langName(lang)}. Keep transcripts of records in their original language.`
+        : "Talk to the user in their language. Set it as the research language: strom setup --lang <code> (cs, en, de, pl, …).";
+    return `STROM — genealogical research with an AI agent
+
+WHAT THIS IS
+strom is the research toolkit you (the agent) work through. It keeps the
+evidence (people, families, events, sources, searches, tasks) in a git
+repository, enforces genealogical method, and produces a GEDCOM file for
+family tree programs such as the Strom app. You bring judgement and reading;
+strom keeps the record straight.
+
+HARD RULES
+1. Never create, edit, delete or read files under data/ yourself. Every change
+   goes through a strom command. Direct edits are detected and block writing.
+2. Never invent facts. What the user or a family tree says is a lead until a
+   record proves it.
+3. Nothing is deleted. Wrong facts are retracted with --reason.
+4. A namesake is not your person: check year, place, house and parents —
+   different parents mean two people, not a clerk's error.
+5. Negative results are results: record every search, also when nothing
+   was found.
+6. Do not answer consent questions yourself (exit code 4). Ask the user.
+7. Never download from an archive yourself (curl, a script, browser tools).
+   Scans come through a connector (strom fetch), paced by strom — an archive
+   the research needs has none yet: build one first (strom connector new,
+   its DISCOVERY.md) and tell the user in a sentence. The user saves images
+   by hand only where the archive does not allow automation.
+${language}
+
+GETTING STARTED (once)
+  strom setup --yes --lang <code>      the language the user speaks with you;
+                                       tell the user where the research lives
+  strom init "<family name>"
+  strom research new "<name>" --new-person "Josef /Novák/" --born "ABT 1885" --born-place "Kamenice nad Lipou"
+  strom intake --text "<what the user told you, in their words>"
+  strom intake <file or folder>        documents, photos, a GEDCOM or Strom tree
+
+EVERY SESSION
+  strom session start                  the brief: task, what is known, method
+  … work; record every finding at once …
+  strom task done T0001 --result "…"   a complete negative search is a result
+  strom session close --summary "…" --next "…"    (not finished: --continue)
+  in a conversation, the next task is best begun in a fresh context (Claude Code: /clear) —
+  suggest it to the user; many tasks waiting: the agent working on its own (strom run, the
+  user starts it from strom's menu), every task in a fresh session
+
+RECORDING
+A record (register entry, certificate) — the source first, then its facts:
+  strom source add "Křest Jana Nováka 1885" --kind baptism --recordset B0001 --locator "fol. 12, č. 3" --form original --information primary --transcript @zapis.txt
+  strom person add "Jan /Novák/" --sex M --born "24 JUN 1885" --born-place "Kamenice nad Lipou" --cite S0001
+  strom family add --partner P0002 --partner P0003 --child P0001    the baptism naming the parents proves the link
+  strom event add P0001 CHR --date "25 JUN 1885" --cite S0001 --locator "fol. 12" --with "godparent:Marie Dvořáková" --status proven
+  strom event add P0002 OCCU --value "rolník" --cite S0001
+The same fact from a second record: strom cite E0001 S0002 (never a second BIRT).
+Names a record gives: strom name add P0003 "Marie /Svobodová/" --kind birth --cite S0001
+(a maiden name completes "Marie"; --kind married for a married name). A record
+naming someone's parents (a grandchild's baptism) cites the family itself and
+the new names: strom person add "Josef /Svoboda/" --cite S0001 --information secondary,
+strom family add --partner P0004 --child P0003 --cite S0001 --information secondary.
+Corrections — a person, a fact, a source:
+  strom person edit P0003 --sex F --name "…" --reason "…"
+  strom event edit E0001 --date "…" --reason "…"
+  strom source edit S0001 --translation "…"
+One person recorded twice (an imported tree and the research) — parents
+recorded twice are merged first:
+  strom family merge F0002 F0005 --reason "…"
+  strom person merge P0001 P0007 --reason "…"
+Many facts from one record in one call — lines of commands, "#name" labels
+what a line creates, "@name" uses it later:
+  strom batch 'person add "Anna /Svobodová/" --sex F #anna' 'family add --partner P0001 --partner @anna --married 1910 --cite S0001'
+What the user remembers: strom intake --text "…", then people and facts
+WITHOUT --cite — they stay leads. A document the user has but you have not
+seen: record it as a source (--form original), cite it, and keep the facts
+probable — proven needs your own reading of the record.
+
+CERTAINTY
+status of a fact = how sure the conclusion is:
+  proven    you read the original record yourself and it states the fact
+  probable  good evidence, but indirect, or a hard reading
+  possible  weak evidence
+  lead      family memory, a family tree, an index, a guess
+evidence quality = what the record is (source --form original | derivative |
+authored) and what it knew about THIS fact (--information primary: written at
+the time by someone who knew | secondary). A baptism entry is primary for the
+date of the baptism, secondary for the age of a parent: say so on the citation
+(--information on cite/event add). A family tree, a memory or a compiled work
+never makes a fact more than a lead; proven needs primary information.
+An age gives a birth estimate: aged 25 at a marriage in 1910 →
+  strom event add P0001 BIRT --date "CAL 1885" --cite S0001 --quote "25 let" --information secondary
+Ages as the record gives them: --age "25 let", "annorum 25", "3 months" (a
+marriage gives both: strom family add … --age husband:25 --age wife:22).
+
+SEARCHING
+  strom searched B0001 --years 1880-1890     before opening anything
+  strom search add "Křty Novák 1880-1890" --recordset B0001 --years 1880-1890 --surname Novák --method page-by-page --result negative
+  strom search edit Q0001 --recordset B0002 --reason "…"   a search recorded wrongly is corrected, never added again
+  strom repo add … · strom recordset add … · strom place jurisdiction …   where the records are
+  strom connector list                 connectors: they find books and fetch scans
+  strom fetch <connector> --find "<place>" --years 1780-1850
+  strom fetch <connector> <book> --images 40-69 --recordset B0001    registered at once
+  strom connector use <connector> --via browser    only when the user asks: images through their own
+                                       browser (strom fetch then says what to do; --via direct: back)
+  strom connector new <name> --url <portal>    an archive you need has none: build it (its DISCOVERY.md)
+
+FINDING YOUR WAY
+  strom research show G0001 · strom person show P0001 · strom family show F0001
+  strom gaps · strom find <text> [<text>…] · strom frontier · strom task list
+STORIES OF THE ANCESTORS (the setting stories — on by default; strom shows it)
+  Once records tell a person's life (a baptism and more facts from records), strom proposes a narrate
+  task: write the story for the family book — plain words, the research language, every statement on a
+  recorded fact (strom story set P… --text @notes/story-P….md --fact E… …). More facts later: it
+  proposes adding to it. A story is a draft until the user approves it (--final). Not told yet: when the
+  research starts, tell the user in a sentence, and that they may say no (strom config set stories no).
+
+The result: strom export gedcom writes output/tree.ged (standard GEDCOM for any program) and
+output/tree-strom.ged (for the Strom app) — both from the same evidence, also on session close.
+Changes are committed automatically; you never run git yourself.
+
+THE STROM APP — where the user sees the result
+  The Strom app (https://stromapp.info) is strom's companion: a free family tree app, no account,
+  the family's data stay on their computer; it shows the tree, the sources, a map, a family book.
+  When the user wants to see the results (or once, when the first ones are there), suggest it
+  gently, in a sentence or two — best installed as an app from the browser, then it works offline:
+  https://stromapp.info/run/   the app itself: opened in the browser, installed from there (the
+                        install icon at the end of the address bar; Safari: File → Add to Dock)
+  strom app install     opens it there and says where to click
+  strom app             opens it — with this research when the app can take it (strom says so), and
+                        run by you, the app follows the research live: what you record shows there
+                        by itself — the best way to watch it grow; otherwise in the app: Import,
+                        and output/tree-strom.ged
+  Without the app, the user can simply ask you about anyone in the tree, a family, a line, what is
+  proven and by which record: answer from strom (person show, family show, research show, find,
+  source show, story show, gaps, frontier) in plain words — names, dates, places, no IDs.
+  strom (no arguments) says whether it is installed here (results): not yet — offer to install it; installed —
+  just open it. A program they already use is fine too: output/tree.ged. They do not want it:
+  never again.
+
+OUTPUT AND ERRORS
+- One line per record, IDs first. Read the text; add --json only to parse.
+- Listings are paged (--limit, --page). Do not pipe strom output.
+- People can be named by ID (P0001) or name ("Jan Novák", no diacritics ok).
+  An ambiguous name lists candidates (exit 2) — then use the ID.
+- Every error ends with "→ <what to run next>".
+- Exit codes: 0 ok · 1 error · 2 usage/ambiguous · 3 needs input (ask the
+  user, then run the given command) · 4 needs consent (the USER must run the
+  given command in their terminal) · 5 locked by another session.
+- Settings and how to override them: strom config where.
+
+MORE
+  strom help <command>                 short help with examples
+  strom commands <group> --json        options and examples of a group
+`;
+}

package/dist/commands/index.js

@@ -0,0 +1,19 @@
+// Registers every command. Order here is the order in help listings.
+import "./meta.js";
+import "./start.js";
+import "./trees.js";
+import "./research.js";
+import "./intake.js";
+import "./tasks.js";
+import "./people.js";
+import "./batch.js";
+import "./sources.js";
+import "./media.js";
+import "./connectors.js";
+import "./read.js";
+import "./analysis.js";
+import "./story.js";
+import "./output.js";
+import "./session.js";
+import "./checks.js";
+import "./setup.js";

package/dist/commands/intake.js

@@ -0,0 +1,234 @@
+// intake · input list · show · skip · done — what a research starts from.
+//
+// Anything can be an input: a folder of scans and documents, a GEDCOM file,
+// a tree exported from the Strom app, a text the user types. Inputs are the
+// unchanged BASE of a research; the agent builds the working tree from them
+// through tasks, and the tree it builds is exported as GEDCOM.
+import fs from "node:fs";
+import path from "node:path";
+import { register } from "../cli/registry.js";
+import { lines, moreLine, paginate, table, truncate } from "../cli/format.js";
+import { UsageError } from "../core/errors.js";
+import { likelyDuplicates } from "../core/people.js";
+import { collectFiles, fileSha256, inputPath, MAX_IN_TREE, mimeOf, storeShared } from "../core/media.js";
+import { create, normId, requireRecord, update } from "../core/records.js";
+import { phrase } from "../core/phrases.js";
+import { importGedcom, importStromJson, isStromJson } from "../core/import.js";
+import { safeFolderName } from "../core/text.js";
+function kindOf(file, text) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".ged")
+        return "tree";
+    if (ext === ".json" && text) {
+        try {
+            if (isStromJson(JSON.parse(text)))
+                return "tree";
+        }
+        catch {
+            // not JSON: other
+        }
+    }
+    if ([".jpg", ".jpeg", ".png", ".tif", ".tiff", ".gif", ".webp", ".heic", ".pdf"].includes(ext))
+        return "document";
+    if ([".txt", ".md", ".rtf", ".doc", ".docx", ".odt", ".html", ".csv"].includes(ext))
+        return "text";
+    return "other";
+}
+/** The research the inputs are for: the one named, else the only active one. */
+function researchFor(tree, named) {
+    if (typeof named === "string")
+        return requireRecord(tree, named, "research").id;
+    const active = tree.list("research").filter((r) => r.state === "active");
+    return active.length === 1 ? active[0].id : undefined;
+}
+function intakeTask(tree, input, research, imported) {
+    return groupTask(tree, [input], research, imported);
+}
+/** One intake task for the inputs of one folder (or one file, or one text). */
+function groupTask(tree, inputs, research, imported, folder) {
+    const input = inputs[0];
+    const many = inputs.length > 1;
+    const tree1 = input.kind === "tree" && !many;
+    const lang = tree.lang;
+    const what = many
+        ? phrase(lang, "intake.files", { count: inputs.length, folder: folder ?? phrase(lang, "intake.the.material"), first: input.id, last: inputs.at(-1).id })
+        : tree1
+            ? phrase(lang, imported ? "intake.tree.imported" : "intake.tree.read", { id: input.id, name: input.name })
+            : input.kind === "text"
+                ? phrase(lang, input.text ? "intake.text" : "intake.text.file", { id: input.id, name: input.name })
+                : phrase(lang, "intake.other", { id: input.id, name: input.name });
+    const why = tree1
+        ? imported
+            ? phrase(lang, "intake.why.imported", { persons: imported.persons, matched: imported.matched ? phrase(lang, "intake.why.matched", { matched: imported.matched }) : "" })
+            : phrase(lang, "intake.why.read")
+        : phrase(lang, "intake.why");
+    const doneWhen = tree1 ? phrase(lang, imported ? "intake.done.imported" : "intake.done.read", { id: input.id }) : phrase(lang, "intake.done");
+    const ids = inputs.map((i) => i.id);
+    return create(tree, "task", { level: "intake", priority: 4, what, where: ids, why, doneWhen, subject: ids, research, state: "open", origin: tree.actor }, (id) => `+${id} task "${truncate(what, 60)}"`);
+}
+/** More images than this in one folder look like the scans of a book, not family documents. */
+const BOOK_OF_SCANS = 20;
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".tif", ".tiff", ".jp2", ".gif", ".webp", ".heic"]);
+register({
+    path: ["intake"],
+    summary: "Take in material to research from: folders, files, a family tree (GEDCOM / Strom JSON), or text",
+    group: "inputs",
+    tree: true,
+    writes: true,
+    lock: "sections",
+    description: "Every file is registered unchanged as an input (duplicates skipped) and gets an intake task.\n" +
+        `Files up to ${MAX_IN_TREE / 1024 / 1024} MB are kept in the tree (and its history); bigger ones in shared/media.\n` +
+        "Family trees are imported at once — every person and fact as a lead citing that tree.",
+    args: [{ name: "paths", description: "files or folders", variadic: true }],
+    options: [
+        { name: "text", type: "string", value: "<text>", description: "what the user tells you, as an input of its own" },
+        { name: "no-import", type: "boolean", description: "register trees without importing them" },
+        { name: "documents", type: "boolean", description: `a folder with more than ${BOOK_OF_SCANS} images really is family documents (not scans of a book)` },
+        { name: "research", type: "string", value: "<G…>", description: "the research it is for (default: the only active one)" },
+    ],
+    examples: ['strom intake ~/Downloads/rodina', "strom intake strom-export.json", 'strom intake --text "Děda Jan, narozen asi 1905 v Týnci, byl mlynář"', "strom intake ~/Downloads/rodina/dopis.txt --research G0001"],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (args.length === 0 && !opts.text)
+            throw new UsageError("give files/folders or --text");
+        const research = researchFor(tree, opts.research);
+        // Files per argument: a folder becomes one intake task, not one per file.
+        const groups = args.map((a) => {
+            const p = ctx.resolvePath(a);
+            if (!fs.existsSync(p))
+                throw new UsageError(`no such file or folder: ${a}`);
+            const folder = fs.statSync(p).isDirectory();
+            const files = collectFiles([p]);
+            const images = files.filter((f) => IMAGE_EXT.has(path.extname(f).toLowerCase())).length;
+            if (folder && images > BOOK_OF_SCANS && !opts.documents)
+                throw new UsageError(`${images} images in ${ctx.display(p)} look like the scans of a book, not family documents`, {
+                    hint: `scans of a register: strom recordset add "<the book>" … then strom media add "${a}" --recordset B…\nif they are family documents after all: strom intake "${a}" --documents`,
+                });
+            return { folder: folder ? path.basename(p) : undefined, files };
+        });
+        const known = new Set(tree.list("input").map((i) => i.sha).filter(Boolean));
+        const report = [];
+        const added = [];
+        let skipped = 0;
+        tree.withTreeLock(() => {
+            for (const group of groups) {
+                const plain = [];
+                for (const file of group.files) {
+                    const sha = fileSha256(file);
+                    if (known.has(sha)) {
+                        skipped++;
+                        continue;
+                    }
+                    known.add(sha);
+                    const size = fs.statSync(file).size;
+                    const isText = size < 50 * 1024 * 1024 && [".ged", ".json", ".txt", ".md", ".csv"].includes(path.extname(file).toLowerCase());
+                    const text = isText ? fs.readFileSync(file, "utf8") : undefined;
+                    const kind = kindOf(file, text);
+                    const id = tree.peekId("I");
+                    let stored;
+                    if (size <= MAX_IN_TREE) {
+                        const rel = `inputs/${id}-${safeFolderName(path.basename(file))}`;
+                        if (!tree.dryRun) {
+                            tree.remember(path.join(tree.root, rel));
+                            fs.copyFileSync(file, path.join(tree.root, rel));
+                        }
+                        stored = rel;
+                    }
+                    else
+                        stored = `media:${path.relative(ctx.settings.shared().value, tree.dryRun ? file : storeShared(ctx.settings.shared().value, file, sha))}`;
+                    const input = create(tree, "input", { name: path.basename(file), file: stored, sha, size, mime: mimeOf(file), from: ctx.display(file), kind, state: "new" }, (iid) => `+${iid} input ${kind} "${truncate(path.basename(file), 50)}"`);
+                    let imported;
+                    if (kind === "tree" && !opts["no-import"] && text !== undefined) {
+                        imported = path.extname(file).toLowerCase() === ".ged"
+                            ? importGedcom(tree, text, { input: input.id, name: input.name, sha })
+                            : importStromJson(tree, JSON.parse(text), { input: input.id, name: input.name });
+                        update(tree, input.id, "input", (i) => ({ ...i, source: imported.source, imported: { persons: imported.persons, families: imported.families, sources: 1 } }), {
+                            op: "input.imported",
+                            summary: `${input.id} imported: ${imported.persons} persons, ${imported.families} families${imported.matched ? `, ${imported.matched} matched` : ""}`,
+                        });
+                        report.push(`  ${input.id} tree: ${imported.persons} persons, ${imported.families} families, ${imported.events} facts as leads${imported.matched ? `, ${imported.matched} matched to existing` : ""}${imported.problems.length ? ` (${imported.problems.length} unreadable lines)` : ""}`);
+                        if (imported.extended.length)
+                            report.push(`  added to what we have (leads — check them): ${imported.extended.slice(0, 6).join(" · ")}${imported.extended.length > 6 ? " …" : ""}`);
+                        const system = `gedcom:${sha.slice(0, 12)}`;
+                        const dupes = likelyDuplicates(tree, tree.list("person").filter((p) => p.refs?.some((r) => r.system === system)).map((p) => p.id));
+                        if (dupes.length)
+                            report.push(`  probably already in the tree: ${dupes.map((d) => `${d.person.id}≈${d.same.id}`).join(", ")} (the review task lists them)`);
+                    }
+                    // A family tree gets its own review task; the other files of a folder share one.
+                    if (kind === "tree" || !group.folder)
+                        intakeTask(tree, input, research, imported);
+                    else
+                        plain.push(input);
+                    added.push(input);
+                }
+                if (plain.length)
+                    groupTask(tree, plain, research, undefined, group.folder);
+            }
+            if (typeof opts.text === "string" && opts.text.trim()) {
+                const input = create(tree, "input", { name: truncate(opts.text, 60), text: opts.text.trim(), kind: "text", state: "new", from: "user" }, (iid) => `+${iid} input text`);
+                intakeTask(tree, input, research);
+                added.push(input);
+            }
+        });
+        const text = lines(`${added.length} input(s) registered${skipped ? `, ${skipped} already known (same content)` : ""}${tree.dryRun ? " (dry run)" : ""}`, added.length ? table(added.map((i) => [`  ${i.id}`, i.kind, truncate(i.name, 60)])) : undefined, ...report, tree.written.some((o) => o.op === "task.add") ? `\n${tree.written.filter((o) => o.op === "task.add").length} intake task(s) created → strom task next` : undefined);
+        return { text, data: { inputs: added, skipped } };
+    },
+}, {
+    path: ["input", "list"],
+    summary: "Inputs of this tree and their state",
+    group: "inputs",
+    tree: true,
+    options: [{ name: "state", type: "string", value: "<state>", description: "new, processed or skipped" }, { name: "full", type: "boolean", description: "--json: whole records instead of one row each" }],
+    run(ctx, { opts }) {
+        const all = ctx.tree().list("input").filter((i) => !opts.state || i.state === opts.state);
+        const page = paginate(all, ctx.limit, ctx.page);
+        return {
+            text: all.length ? lines(table(page.items.map((i) => [i.id, i.kind, i.state, truncate(i.name, 60)])), moreLine(page, "strom input list")) : 'no inputs → strom intake <files or folder>',
+            data: { total: all.length, inputs: opts.full ? page.items : page.items.map((i) => ({ id: i.id, kind: i.kind, state: i.state, name: i.name })) },
+        };
+    },
+}, {
+    path: ["input", "show"],
+    summary: "One input: where the file is (to read it), what came of it",
+    group: "inputs",
+    tree: true,
+    args: [{ name: "input", description: "input ID (I0001)", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const i = requireRecord(tree, args[0], "input");
+        const abs = inputPath(tree, i);
+        const tasks = tree.list("task").filter((t) => t.where.includes(i.id));
+        const text = lines(`${i.id} ${i.name}  [${i.kind} · ${i.state}]`, abs ? `file   ${abs}` : undefined, i.from ? `from   ${i.from}` : undefined, i.mime ? `type   ${i.mime}${i.size !== undefined ? ` · ${Math.round(i.size / 1024)} kB` : ""}` : undefined, i.imported ? `import ${i.imported.persons} persons, ${i.imported.families} families as leads, cited as ${i.source}` : undefined, i.text ? `\n${i.text}` : undefined, !i.text && i.kind === "text" && abs && fs.existsSync(abs) && (i.size ?? 0) < 20_000 && /\.(txt|md|csv)$/i.test(abs) ? `\n${fs.readFileSync(abs, "utf8").trim()}` : undefined, tasks.length ? `\ntasks\n${table(tasks.map((t) => [`  ${t.id}`, t.state, truncate(t.what, 60)]))}` : undefined, ...i.notes.map((n) => `note   ${n.text}`), i.kind === "document" && abs
+            ? `\nread the file (a big image: strom media view ${i.id} --grid, then --crop), then record what it says: strom source add … --input ${i.id}`
+            : undefined);
+        return { text, data: { input: i, path: abs, tasks: tasks.map((t) => t.id) } };
+    },
+}, {
+    path: ["input", "done"],
+    summary: "Mark an input as processed",
+    group: "inputs",
+    tree: true,
+    writes: true,
+    args: [{ name: "input", description: "input ID", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const id = normId(args[0], "input");
+        update(tree, id, "input", (i) => ({ ...i, state: "processed" }), { op: "input.done", summary: `${id} processed` });
+        return { text: lines(...tree.written.map((o) => o.summary)), data: { id } };
+    },
+}, {
+    path: ["input", "skip"],
+    summary: "Mark an input as not useful (with the reason)",
+    group: "inputs",
+    tree: true,
+    writes: true,
+    args: [{ name: "input", description: "input ID", required: true }],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (!opts.reason)
+            throw new UsageError("--reason is required");
+        const id = normId(args[0], "input");
+        update(tree, id, "input", (i) => ({ ...i, state: "skipped" }), { op: "input.skip", summary: `${id} skipped`, reason: String(opts.reason) });
+        return { text: lines(...tree.written.map((o) => o.summary)), data: { id } };
+    },
+});