strom-research 1.0.0

package/dist/commands/tasks.js

@@ -0,0 +1,436 @@
+// task add · next · list · show · edit · start · done · park · wake · wait · drop
+//
+// A task is a contract: WHAT to find, WHERE to look (record sets or a clear
+// description), WHY it matters, and WHEN it is done. A task without "where"
+// is a wish; strom refuses it.
+import fs from "node:fs";
+import path from "node:path";
+import { ui } from "../cli/ui.js";
+import { register } from "../cli/registry.js";
+import { lines, moreLine, paginate, runs, table, truncate } from "../cli/format.js";
+import { UsageError } from "../core/errors.js";
+import { TASK_LEVELS } from "../core/model.js";
+import { create, csvOpt, listOpt, normId, requireRecord, update } from "../core/records.js";
+import { resolvePerson } from "../core/people.js";
+import { now, typeOfId } from "../core/tree.js";
+import { resolveResearch } from "./research.js";
+import { makeNote } from "../core/actions.js";
+import { lacksImages, rankTasks } from "../core/queue.js";
+import { inboxFolderFor, parseImageList } from "../core/media.js";
+function written(tree) {
+    return lines(...tree.written.map((o) => o.summary), tree.dryRun ? "(dry run — nothing written)" : undefined);
+}
+/** Resolve subject references: IDs of any type, or person names. */
+function subjects(tree, refs) {
+    return refs.map((r) => {
+        const id = normId(r);
+        if (typeOfId(id)) {
+            if (!tree.get(id))
+                throw new UsageError(`no record ${id}`);
+            return id;
+        }
+        return resolvePerson(tree, r).id;
+    });
+}
+function defaultResearch(tree, ref) {
+    if (typeof ref === "string")
+        return resolveResearch(tree, ref).id;
+    const active = tree.list("research").filter((r) => r.state === "active");
+    return active.length === 1 ? active[0].id : undefined;
+}
+/** What the research waits for from outside — mostly from the user: scans to download, a book to find, a reply. */
+export function waitingForUser(tree) {
+    return tree
+        .list("task")
+        .filter((t) => t.state === "waiting")
+        .map((t) => ({ id: t.id, what: t.what, on: t.waitingOn ?? "" }));
+}
+/**
+ * The lines that tell the user what the research waits for. Images they save by hand come with
+ * the book's link and the folder they go into: facts, while the request itself is in their language.
+ */
+export function waitingLines(tree, where = {}, max = 5) {
+    const w = tree.list("task").filter((t) => t.state === "waiting");
+    if (!w.length)
+        return undefined;
+    const show = where.display ?? ((p) => p);
+    const lang = tree.lang;
+    const images = (t) => {
+        if (!t.awaits)
+            return [];
+        const b = tree.get(t.awaits.recordset);
+        const dir = where.shared ? show(path.join(where.shared, "inbox", t.awaits.folder)) : `inbox/${t.awaits.folder}`;
+        return [
+            `         ${ui(lang, "ui.wait.images", { images: t.awaits.images, book: `${t.awaits.recordset}${b ? ` ${b.title}` : ""}` })}${b?.url ? ` · ${b.url}` : ""}`,
+            `         ${ui(lang, "ui.wait.save", { dir: `${dir}${path.sep}` })}`,
+        ];
+    };
+    return lines(ui(lang, "ui.wait.title", { n: w.length }), ...w.slice(0, max).flatMap((t) => [`  ${t.id}  ${truncate(t.waitingOn || t.what, 150)}`, ...images(t)]), w.length > max ? `  … strom task list --state waiting` : undefined, `  ${ui(lang, "ui.wait.how1")}`, `  ${ui(lang, "ui.wait.how2")}`);
+}
+/** The open tasks of the queue in the order to work on them (see core/queue.ts). */
+export function taskQueue(tree, filter = {}) {
+    return rankedQueue(tree, filter).map((r) => r.task);
+}
+export function rankedQueue(tree, filter = {}) {
+    const tasks = tree
+        .list("task")
+        .filter((t) => !filter.research || !t.research || t.research === filter.research)
+        .filter((t) => !filter.level || t.level === filter.level);
+    return rankTasks(tree, tasks, filter.strategy);
+}
+function taskLine(t) {
+    return [t.id, `p${t.priority}`, t.level, t.state === "open" ? "" : `[${t.state}]`, truncate(t.what, 70)];
+}
+function taskDetail(tree, t) {
+    const where = t.where.map((w) => {
+        const b = /^B\d{4,}$/.test(w) ? tree.get(w) : undefined;
+        return b ? `${b.id} ${b.title}${b.url ? ` · ${b.url}` : ""}` : w;
+    });
+    const searches = tree.list("search").filter((s) => s.task === t.id || s.recordsets.some((b) => t.where.includes(b)));
+    const lessons = tree.list("lesson").filter((l) => l.target && t.where.includes(l.target));
+    return lines(`${t.id} ${t.what}`, `level ${t.level} · priority ${t.priority} · ${t.state}${t.research ? ` · research ${t.research}` : ""}${t.parkedUntil ? ` · parked until ${t.parkedUntil}` : ""}${t.waitingOn ? ` · waiting on ${t.waitingOn}` : ""}`, `where  ${where.join("\n       ")}`, `why    ${t.why}`, `done   ${t.doneWhen}`, t.subject.length ? `about  ${t.subject.join(" ")}` : undefined, t.result ? `result ${t.result}${t.produced?.length ? ` → ${t.produced.join(" ")}` : ""}` : undefined, searches.length ? "\nalready searched there\n" + table(searches.map((s) => [`  ${s.id}`, s.result, truncate(s.question, 60), s.scope.years ?? ""])) : undefined, lessons.length ? "\nlessons for these record sets\n" + lessons.map((l) => `  ${l.id} ${l.rule}`).join("\n") : undefined, ...t.notes.map((n) => `note   ${n.text}`));
+}
+function stateChange(tree, ref, state, fields, reason, verb) {
+    const id = normId(ref, "task");
+    return update(tree, id, "task", (t) => {
+        if (t.state === "done" && state !== "open")
+            throw new UsageError(`${id} is already done`);
+        const next = { ...t, state, ...fields };
+        if (state !== "parked")
+            delete next.parkedUntil;
+        if (state !== "waiting") {
+            delete next.waitingOn;
+            delete next.awaits;
+        }
+        else if (!fields.awaits)
+            delete next.awaits;
+        return next;
+    }, { op: `task.${verb}`, summary: `${id} ${verb}${fields.result ? `: ${truncate(fields.result, 60)}` : ""}`, reason });
+}
+register({
+    path: ["task", "add"],
+    summary: "Add a task: what, where, why, done-when (all required)",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    description: "Levels: intake (process an input), locate (find where records are), link (prove a parent/marriage),\n" +
+        "verify (independent second reading), enrich (details of a placed person), request (ask an archive),\n" +
+        "narrate (write the story). Priority 1 (low) – 5 (urgent), default 3.",
+    args: [{ name: "what", description: 'what to find, one line: "Baptism of Jan Novák (~1905)"', required: true }],
+    options: [
+        { name: "level", type: "string", value: "<level>", description: TASK_LEVELS.join(", ") },
+        { name: "where", type: "string", multiple: true, value: "<B…|text>", description: "record set ID or a precise description (repeatable)" },
+        { name: "why", type: "string", value: "<text>", description: "why it matters for the research" },
+        { name: "done-when", type: "string", value: "<text>", description: "what counts as done (found, or searched completely)" },
+        { name: "priority", type: "string", value: "1-5", description: "default 3" },
+        { name: "about", type: "string", multiple: true, value: "<who>", description: "person/record the task is about, also a conflict X… or hypothesis H… it decides (repeatable)" },
+        { name: "research", type: "string", value: "<G…>", description: "research it belongs to (default: the only active one)" },
+        { name: "note", type: "string", value: "<text>", description: "short note" },
+    ],
+    examples: [
+        'strom task add "Křest Jana Nováka (~1905)" --level link --where B0001 --why "potvrdí otce Josefa" --done-when "zápis nalezen, nebo ročníky 1903–1907 prohledány celé" --about P0001 --priority 4',
+    ],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const missing = [!opts.level && "--level", !listOpt(opts.where).length && "--where", !opts.why && "--why", !opts["done-when"] && "--done-when"].filter(Boolean);
+        if (missing.length)
+            throw new UsageError(`a task needs ${missing.join(", ")}`, { hint: "a task without where is a wish: name the record set (B…) or describe exactly where to look" });
+        if (!TASK_LEVELS.includes(opts.level))
+            throw new UsageError(`invalid --level "${opts.level}"`, { hint: TASK_LEVELS.join(", ") });
+        const priority = opts.priority === undefined ? 3 : Number(opts.priority);
+        if (!Number.isInteger(priority) || priority < 1 || priority > 5)
+            throw new UsageError("--priority must be 1..5");
+        const where = listOpt(opts.where).map((w) => (/^[Bb]\d+$/.test(w) ? requireRecord(tree, w, "recordset").id : w));
+        const t = create(tree, "task", {
+            level: opts.level,
+            priority,
+            what: args[0].trim(),
+            where,
+            why: String(opts.why).trim(),
+            doneWhen: String(opts["done-when"]).trim(),
+            subject: subjects(tree, listOpt(opts.about)),
+            research: defaultResearch(tree, opts.research),
+            state: "open",
+            origin: tree.actor,
+            note: opts.note,
+        }, (id) => `+${id} task "${truncate(args[0], 60)}"`);
+        // the same person, the same kind of work, the same books: most likely the same task
+        const books = new Set(where.filter((w) => /^B\d+$/.test(w)));
+        const similar = tree
+            .list("task")
+            .filter((x) => x.id !== t.id && ["open", "doing", "waiting", "parked"].includes(x.state) && x.level === t.level)
+            .filter((x) => x.subject.some((s) => t.subject.includes(s)) && (books.size === 0 || x.where.some((w) => books.has(w))));
+        // A link without images can only wait for the user: say now what to download, while
+        // it is known — not in a session spent finding out that there is nothing to read.
+        const noImages = lacksImages(tree, t);
+        return {
+            text: lines(written(tree), ...similar.map((x) => `⚠ similar ${x.state} task ${x.id} "${truncate(x.what, 60)}" — if it is the same, keep one: strom task drop ${t.id} --reason "duplicate of ${x.id}" and strom task edit ${x.id} --where … --note "…"`), noImages ? `· no images for it here yet — if the user has to download them, say which now: strom task wait ${t.id} --images B…:<numbers> --on "<the book, its link, which images>"` : undefined),
+            data: { task: t, similar: similar.map((x) => x.id), needsImages: noImages },
+        };
+    },
+}, {
+    path: ["task", "next"],
+    summary: "The task to work on now (never asks — the queue is ordered)",
+    group: "tasks",
+    tree: true,
+    options: [
+        { name: "research", type: "string", value: "<G…>", description: "only this research" },
+        { name: "level", type: "string", value: "<level>", description: "only this level" },
+    ],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        const research = typeof opts.research === "string" ? resolveResearch(tree, opts.research).id : undefined;
+        const strategy = ctx.settings.strategy(tree.config);
+        const queue = rankedQueue(tree, { ...(research ? { research } : {}), ...(opts.level ? { level: String(opts.level) } : {}), strategy });
+        const first = queue[0];
+        if (!first)
+            return { text: 'no open tasks → strom research show <G…> to see what is missing, then strom task add', data: { task: null } };
+        const t = first.task;
+        return {
+            text: lines(taskDetail(tree, t), "", `first because: ${first.why} (queue: ${strategy})`, `start it: strom task start ${t.id}`),
+            data: { task: t, why: first.why, strategy, queueLength: queue.length },
+        };
+    },
+}, {
+    path: ["task", "list"],
+    summary: "The task queue in order (or all tasks with --state)",
+    description: "The order (setting queue.strategy): balanced — work that can be done now before work waiting for a download,\n" +
+        "the nearest ancestors first, a line that just had sessions waits for the others, a task tried again and again\n" +
+        "sinks; depth — stay on the line of the last sessions; priority — strict priority. --json says why for each.",
+    group: "tasks",
+    tree: true,
+    options: [
+        { name: "state", type: "string", value: "<state>", description: "open (default queue), doing, done, parked, waiting, dropped, all" },
+        { name: "research", type: "string", value: "<G…>", description: "only this research" },
+        { name: "level", type: "string", value: "<level>", description: "only this level" },
+        { name: "about", type: "string", value: "<who>", description: "only tasks about this person/record (also X…, H…)" },
+        { name: "full", type: "boolean", description: "--json: whole records instead of one row each" },
+    ],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        const research = typeof opts.research === "string" ? resolveResearch(tree, opts.research).id : undefined;
+        let all;
+        const why = new Map();
+        if (!opts.state) {
+            const ranked = rankedQueue(tree, { ...(research ? { research } : {}), ...(opts.level ? { level: String(opts.level) } : {}), strategy: ctx.settings.strategy(tree.config) });
+            for (const r of ranked)
+                why.set(r.task.id, r.why);
+            all = ranked.map((r) => r.task);
+        }
+        else {
+            all = tree.list("task").filter((t) => opts.state === "all" || t.state === opts.state);
+            if (research)
+                all = all.filter((t) => t.research === research);
+            if (opts.level)
+                all = all.filter((t) => t.level === opts.level);
+        }
+        if (opts.about) {
+            const id = subjects(tree, [String(opts.about)])[0];
+            all = all.filter((t) => t.subject.includes(id));
+        }
+        const page = paginate(all, ctx.limit, ctx.page);
+        return {
+            text: all.length ? lines(table(page.items.map(taskLine)), moreLine(page, "strom task list")) : "no tasks",
+            data: { total: page.total, tasks: opts.full ? page.items : page.items.map((t) => ({ id: t.id, priority: t.priority, level: t.level, state: t.state, what: t.what, subject: t.subject, ...(why.has(t.id) ? { why: why.get(t.id) } : {}) })) },
+        };
+    },
+}, {
+    path: ["task", "show"],
+    summary: "One task with what was already searched there and lessons for those record sets",
+    group: "tasks",
+    tree: true,
+    args: [{ name: "task", description: "task ID (T0001)", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const t = requireRecord(tree, args[0], "task");
+        return { text: taskDetail(tree, t), data: { task: t } };
+    },
+}, {
+    path: ["task", "edit"],
+    summary: "Change a task: point it at record sets, sharpen what/why/done-when, priority, who it is about",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    description: "--where and --about replace the old values (repeat them for several). A task written before its books were\nknown is pointed at them here — that is how a locate task hands over to a link task.",
+    args: [{ name: "task", description: "task ID", required: true }],
+    options: [
+        { name: "what", type: "string", value: "<text>", description: "what to find" },
+        { name: "where", type: "string", multiple: true, value: "<B…|text>", description: "record set ID or a precise description (repeatable; replaces)" },
+        { name: "why", type: "string", value: "<text>", description: "why it matters" },
+        { name: "done-when", type: "string", value: "<text>", description: "what counts as done" },
+        { name: "priority", type: "string", value: "1-5", description: "priority" },
+        { name: "about", type: "string", multiple: true, value: "<who>", description: "person/record the task is about, also a conflict X… or hypothesis H… it decides (repeatable; replaces)" },
+        { name: "note", type: "string", value: "<text>", description: "add a short note (what a later finding means for this task)" },
+    ],
+    examples: ["strom task edit T0001 --where B0001 --priority 4", 'strom task edit T0001 --note "the baptism of the son names the bride\'s father"'],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        const id = normId(args[0], "task");
+        const change = {};
+        if (typeof opts.what === "string" && opts.what.trim())
+            change.what = opts.what.trim();
+        if (listOpt(opts.where).length)
+            change.where = listOpt(opts.where).map((w) => (/^[Bb]\d+$/.test(w) ? requireRecord(tree, w, "recordset").id : w));
+        if (typeof opts.why === "string" && opts.why.trim())
+            change.why = opts.why.trim();
+        if (typeof opts["done-when"] === "string" && opts["done-when"].trim())
+            change.doneWhen = opts["done-when"].trim();
+        if (opts.priority !== undefined) {
+            const priority = Number(opts.priority);
+            if (!Number.isInteger(priority) || priority < 1 || priority > 5)
+                throw new UsageError("--priority must be 1..5");
+            change.priority = priority;
+        }
+        if (listOpt(opts.about).length)
+            change.subject = subjects(tree, listOpt(opts.about));
+        const note = typeof opts.note === "string" ? makeNote(tree, opts.note) : undefined;
+        const fields = [...Object.keys(change), ...(note ? ["note"] : [])];
+        if (!fields.length)
+            throw new UsageError("nothing to change", { hint: `e.g. strom task edit ${id} --where B0001` });
+        const t = update(tree, id, "task", (t) => ({ ...t, ...change, ...(note ? { notes: [...t.notes, note] } : {}) }), {
+            op: "task.edit",
+            summary: `${id} ${fields.map((f) => (f === "doneWhen" ? "done-when" : f === "subject" ? "about" : f)).join(", ")}${change.where ? ` → ${truncate(change.where.join("; "), 50)}` : ""}`,
+            reason: opts.reason,
+        });
+        return { text: written(tree), data: { task: t } };
+    },
+}, {
+    path: ["task", "start"],
+    summary: "Mark a task as being worked on",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    args: [{ name: "task", description: "task ID", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const t = stateChange(tree, args[0], "doing", {}, undefined, "start");
+        return { text: lines(written(tree), `details: strom task show ${t.id}`), data: { task: t } };
+    },
+}, {
+    path: ["task", "done"],
+    summary: "Close a task with its result (also a negative one)",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    args: [{ name: "task", description: "task ID", required: true }],
+    options: [
+        { name: "result", type: "string", value: "<text>", description: "what came out — 'not found in 1903–1907, searched completely' is a result" },
+        { name: "produced", type: "string", multiple: true, value: "<ID>", description: "records created (sources, events, searches…)" },
+    ],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (!opts.result)
+            throw new UsageError("--result is required", { hint: "say what was found — or where it was searched without success" });
+        const t = stateChange(tree, args[0], "done", { result: String(opts.result).trim(), produced: csvOpt(opts.produced).map((x) => normId(x)) }, undefined, "done");
+        // A search that is not recorded will be done again: nudge when a search task records none.
+        const noSearch = ["locate", "link", "verify", "enrich"].includes(t.level) && !tree.list("search").some((s) => s.task === t.id)
+            ? `note: no search is recorded for ${t.id} — record what you looked at, found or not: strom search add "<what>" --task ${t.id} --method web|catalog|index|page-by-page --result found|negative`
+            : undefined;
+        // A locate task hands over: the link tasks that name no record set yet should now name one.
+        const unpointed = t.level === "locate"
+            ? tree.list("task").filter((x) => x.level === "link" && ["open", "doing", "parked"].includes(x.state) && !x.where.some((w) => /^B\d{4,}$/.test(w)))
+            : [];
+        const handover = unpointed.length
+            ? `note: ${unpointed.map((x) => x.id).join(", ")} name no record set yet — point them at the books found: strom task edit ${unpointed[0].id} --where B…`
+            : undefined;
+        // Finishing an intake task finishes its input: nothing is left dangling as "new".
+        if (t.level === "intake")
+            for (const id of new Set([...t.subject, ...t.where]))
+                if (typeOfId(id) === "input" && tree.get(id)?.state === "new")
+                    update(tree, id, "input", (i) => ({ ...i, state: "processed" }), { op: "input.done", summary: `${id} processed (${t.id} done)` });
+        return { text: lines(written(tree), noSearch, handover), data: { task: t } };
+    },
+}, {
+    path: ["task", "park"],
+    summary: "Put a task aside (it stops being offered) — optionally until a date",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    args: [{ name: "task", description: "task ID", required: true }],
+    options: [{ name: "until", type: "string", value: "<YYYY-MM-DD>", description: "offer it again after this date" }],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (!opts.reason)
+            throw new UsageError("--reason is required", { hint: 'e.g. --reason "waiting until the register is digitised"' });
+        const until = opts.until ? String(opts.until) : undefined;
+        if (until && !/^\d{4}-\d{2}-\d{2}$/.test(until))
+            throw new UsageError("--until must be YYYY-MM-DD");
+        const t = stateChange(tree, args[0], "parked", until ? { parkedUntil: until } : {}, String(opts.reason), "park");
+        return { text: written(tree), data: { task: t } };
+    },
+}, {
+    path: ["task", "wake"],
+    summary: "Bring a parked or waiting task back into the queue",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    args: [{ name: "task", description: "task ID", required: true }],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        const t = stateChange(tree, args[0], "open", {}, undefined, "wake");
+        return { text: written(tree), data: { task: t } };
+    },
+}, {
+    path: ["task", "wait"],
+    summary: "The task waits for something outside (an archive's reply, the user) — images the user saves by hand: --images",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    description: "--on says what it waits for, to the user, in their language. When it is images the user downloads by hand\n" +
+        "(no connector may fetch them), name them with --images B…:<numbers>: strom makes the folder of the shared\n" +
+        "inbox they go into and shows it to the user, checks the numbers of what arrives, and the task comes back\n" +
+        "by itself once they are registered.",
+    args: [{ name: "task", description: "task ID", required: true }],
+    options: [
+        { name: "on", type: "string", value: "<text>", description: "what it waits for, for the user: which book, its link, which images" },
+        { name: "images", type: "string", value: "<B…:n-m>", description: "the images the user saves by hand, numbered as the portal's viewer counts them (B0001:40-69, B0001:9,12)" },
+    ],
+    examples: [
+        'strom task wait T0002 --on "reply of the archive to the request of 21 Sep"',
+        'strom task wait T0002 --images B0001:40-45 --on "images 40–45 of the baptisms of Týnec 1784–1820 (https://archive.example.org/book/5359)"',
+    ],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (!opts.on)
+            throw new UsageError("--on is required", { hint: 'e.g. --on "reply of the archive to the request of 21 Sep"' });
+        let awaits;
+        let b;
+        if (opts.images !== undefined) {
+            const m = /^\s*([Bb]\d+)\s*:\s*(.+)$/.exec(String(opts.images));
+            const nums = m ? parseImageList(m[2]) : undefined;
+            if (!m || !nums)
+                throw new UsageError(`--images: a record set and its image numbers, e.g. B0001:40-45 or B0001:9,12 — not "${opts.images}"`);
+            b = requireRecord(tree, m[1], "recordset");
+            awaits = { recordset: b.id, images: runs(nums), folder: inboxFolderFor(b) };
+        }
+        const id = normId(args[0], "task");
+        const task = tree.get(id);
+        const where = b && task && !task.where.includes(b.id) ? { where: [...task.where, b.id] } : {};
+        const t = stateChange(tree, args[0], "waiting", { waitingOn: String(opts.on), ...(awaits ? { awaits } : {}), ...where }, undefined, "wait");
+        if (!awaits)
+            return { text: written(tree), data: { task: t } };
+        // the folder is there before the user looks for it
+        const s = ctx.settings.shared()?.value;
+        const dir = s ? path.join(s, "inbox", awaits.folder) : undefined;
+        if (dir && !tree.dryRun)
+            fs.mkdirSync(dir, { recursive: true });
+        return {
+            text: lines(written(tree), `the user saves images ${awaits.images} of ${b.id} into ${dir ? ctx.display(dir) : `the inbox folder "${awaits.folder}"`}, each named by its number (${parseImageList(awaits.images)[0]}.jpg)`, "they see it in strom's overview; once the images are registered (strom media add --inbox), the task comes back by itself"),
+            data: { task: t, folder: dir },
+        };
+    },
+}, {
+    path: ["task", "drop"],
+    summary: "Give up a task (kept, with the reason)",
+    group: "tasks",
+    tree: true,
+    writes: true,
+    args: [{ name: "task", description: "task ID", required: true }],
+    run(ctx, { args, opts }) {
+        const tree = ctx.tree();
+        if (!opts.reason)
+            throw new UsageError("--reason is required");
+        const t = stateChange(tree, args[0], "dropped", {}, String(opts.reason), "drop");
+        return { text: written(tree), data: { task: t } };
+    },
+});

package/dist/commands/trees.js

@@ -0,0 +1,128 @@
+// init · trees · status · lang — trees (one folder per family tree).
+import fs from "node:fs";
+import path from "node:path";
+import { waitingLines } from "./tasks.js";
+import { register } from "../cli/registry.js";
+import { Context } from "../cli/context.js";
+import { lines, table } from "../cli/format.js";
+import { Tree } from "../core/tree.js";
+import { safeFolderName } from "../core/text.js";
+import { isValidLang, langName } from "../core/lang.js";
+import { UsageError } from "../core/errors.js";
+import { verifyFast } from "../core/integrity.js";
+import * as git from "../core/git.js";
+import { ensureShared, setTreeSetting } from "./setup.js";
+import { syncAgentFiles } from "../agents/files.js";
+register({
+    path: ["init"],
+    summary: "Create a family tree (a folder with its own history) to hold researches",
+    group: "research",
+    description: "The tree goes into the trees folder unless --dir is given. One tree = one family = one tree in the Strom app.",
+    args: [{ name: "name", description: 'tree name, e.g. "Novákovi"', required: true }],
+    options: [{ name: "dir", type: "string", value: "<folder>", description: "create the tree in this folder instead" }],
+    examples: ['strom init "Novákovi"', 'strom init "Novákovi" --lang cs', 'strom init "Dvořákovi" --dir "~/Rodokmeny/Dvořákovi"'],
+    run: async (ctx, { args, opts }) => {
+        const name = args[0].trim();
+        if (!name)
+            throw new UsageError("the tree needs a name");
+        await ctx.requireHome();
+        const treesDir = ctx.settings.trees().value;
+        const root = opts.dir ? ctx.resolvePath(opts.dir) : path.join(treesDir, safeFolderName(name));
+        const langR = ctx.settings.lang();
+        const lang = langR.value;
+        fs.mkdirSync(treesDir, { recursive: true });
+        ensureShared(ctx.settings.shared().value);
+        const tree = Tree.create(root, name, lang, ctx.env);
+        const agentFiles = syncAgentFiles(tree);
+        tree.withTreeLock(() => tree.commit(`Agent instructions: ${agentFiles.join(", ")}`, agentFiles));
+        if (path.dirname(root) !== treesDir) {
+            const extra = new Set(ctx.settings.config.extraTrees ?? []);
+            extra.add(root);
+            ctx.settings.config.extraTrees = [...extra];
+            ctx.settings.save();
+        }
+        ctx.adopt(tree);
+        const text = lines(`Created tree "${name}" in ${ctx.display(root)}`, `research language: ${langName(lang)} (${lang})${langR.source === "detected" ? " — detected from the system; if the user speaks another language: strom lang <code>" : ""}`, "", `next   strom research new "<research name>" --new-person "<Given /Surname/>" --born "<date>" --born-place "<place>"`);
+        return { text, data: { name, root, lang } };
+    },
+});
+register({
+    path: ["trees"],
+    summary: "List the family trees Strom knows",
+    group: "research",
+    run(ctx) {
+        const trees = ctx.knownTrees().map((t) => {
+            const tree = Tree.open(t.root, ctx.env);
+            return {
+                ...t,
+                persons: tree.count("person"),
+                researches: tree.list("research").length,
+            };
+        });
+        if (trees.length === 0)
+            return { text: 'no trees yet → strom init "<tree name>"', data: { trees } };
+        const text = table(trees.map((t) => [t.name, t.lang, `${t.persons} persons`, `${t.researches} researches`, ctx.display(t.root)]));
+        return { text, data: { trees } };
+    },
+});
+register({
+    path: ["trees", "use"],
+    summary: "Work on this tree from now on, wherever you are (remembered for you)",
+    group: "research",
+    description: "Commands find the tree by --tree, STROM_TREE, the folder you are in, this choice, or the only tree there is.",
+    args: [{ name: "tree", description: "tree name or folder", required: true }],
+    examples: ['strom trees use "Novákovi"'],
+    run(ctx, { args }) {
+        const probe = Context.fromOptions({ env: ctx.env, cwd: ctx.cwd, io: ctx.io, json: ctx.json, values: { tree: args[0] } });
+        const root = probe.locateTree();
+        ctx.settings.config.currentTree = root;
+        ctx.settings.save();
+        const tree = Tree.open(root, ctx.env);
+        return { text: `now working on "${tree.config.name}" (${ctx.display(root)})`, data: { name: tree.config.name, root } };
+    },
+});
+register({
+    path: ["status"],
+    summary: "State of the current tree: researches, data, checks, recent changes",
+    group: "start",
+    tree: true,
+    run(ctx) {
+        const tree = ctx.tree();
+        const researches = tree.list("research");
+        const findings = verifyFast(tree).findings;
+        const errors = findings.filter((f) => f.level === "error");
+        const recent = git.log(tree.root, 5);
+        const text = lines(`${tree.config.name} — ${langName(tree.config.lang)} (${tree.config.lang}) — ${ctx.display(tree.root)}`, `data   ${tree.count("person")} persons · ${tree.count("family")} families · ${researches.length} researches`, `check  ${errors.length === 0 ? "ok" : `${errors.length} errors → strom check`}${findings.length - errors.length ? ` · ${findings.length - errors.length} warnings` : ""}`, researches.length ? "research\n" + table(researches.map((r) => [`  ${r.id}`, r.name, `[${r.state}]`])) : undefined, waitingLines(tree, { shared: ctx.settings.shared()?.value, display: (p) => ctx.display(p) }), recent.length ? "recent\n" + table(recent.map((c) => [`  ${c.at.slice(0, 16).replace("T", " ")}`, c.subject])) : undefined);
+        return {
+            text,
+            data: {
+                tree: { name: tree.config.name, root: tree.root, lang: tree.config.lang },
+                counts: { persons: tree.count("person"), families: tree.count("family"), researches: researches.length },
+                researches: researches.map((r) => ({ id: r.id, name: r.name, state: r.state })),
+                findings,
+                recent,
+            },
+        };
+    },
+});
+register({
+    path: ["lang"],
+    summary: "Show or change the research language of the current tree",
+    group: "research",
+    tree: true,
+    description: "The agent talks to the user and writes research texts in this language. CLI output stays English.",
+    args: [{ name: "code", description: "new language code, e.g. cs, en, de" }],
+    examples: ["strom lang", "strom lang de"],
+    run(ctx, { args }) {
+        const tree = ctx.tree();
+        if (args[0]) {
+            const code = args[0].toLowerCase();
+            if (!isValidLang(code))
+                throw new UsageError(`invalid language code "${args[0]}"`, { hint: "use a code like cs, en, de" });
+            // Same as `strom config set lang <code> --for-tree`: logged, committed, agent files follow.
+            setTreeSetting(ctx, "lang", code);
+        }
+        const lang = tree.config.lang;
+        return { text: `${langName(lang)} (${lang})`, data: { lang, name: langName(lang) } };
+    },
+});