strom-research 1.0.0

package/dist/commands/batch.js

@@ -0,0 +1,181 @@
+// strom batch — several writing commands as one change.
+//
+// Recording one register entry takes half a dozen commands (the source, the
+// child, the parents, the family, the baptism with its godparents). As single
+// calls that is half a dozen agent turns, each paying for its tool call and
+// for git. A batch runs them in one process: one integrity check, one
+// commit, all or nothing. A line may end in "#name" to label the record it
+// creates; later lines use it as "@name".
+import fs from "node:fs";
+import { register } from "../cli/registry.js";
+import { lines, table } from "../cli/format.js";
+import { AmbiguousError, StromError, UsageError } from "../core/errors.js";
+/** A label: a word in any script ("anna", "šimon", "otec_2"), its accents composed or not. */
+const LABEL = "[\\p{L}_][\\p{L}\\p{M}\\p{N}_-]*";
+import { checkArgs, parseOptions, resolveCommand } from "../cli/execute.js";
+/** Shell-like words: "double" (with \" \\ escapes), 'single', backslash escapes, # comments. */
+function tokenize(line) {
+    const out = [];
+    let cur = "";
+    let quoted = false;
+    let started = false;
+    let q = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (q === "'") {
+            if (ch === "'")
+                q = null;
+            else
+                cur += ch;
+            continue;
+        }
+        if (q === '"') {
+            if (ch === "\\" && i + 1 < line.length && '"\\$`'.includes(line[i + 1]))
+                cur += line[++i];
+            else if (ch === '"')
+                q = null;
+            else
+                cur += ch;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            q = ch;
+            quoted = true;
+            started = true;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < line.length) {
+            cur += line[++i];
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (started)
+                out.push({ text: cur, quoted });
+            cur = "";
+            quoted = false;
+            started = false;
+            continue;
+        }
+        if (ch === "#" && !started && out.length === 0)
+            return out; // a comment line
+        cur += ch;
+        started = true;
+    }
+    if (q)
+        throw new UsageError(`unclosed ${q === '"' ? "double" : "single"} quote`);
+    if (started)
+        out.push({ text: cur, quoted });
+    return out;
+}
+/** Lines of a batch: blank lines and # comments skipped, "\" at the end continues a line. */
+export function parseBatch(text) {
+    const out = [];
+    const raw = text.replace(/\r\n?/g, "\n").split("\n");
+    for (let i = 0; i < raw.length; i++) {
+        const n = i + 1;
+        // "\" at the end continues the line — also with spaces after it, and at the very end of the file
+        let line = raw[i].trimEnd();
+        while (line.endsWith("\\"))
+            line = line.slice(0, -1) + (i + 1 < raw.length ? " " + raw[++i].trimEnd() : "");
+        let tokens;
+        try {
+            tokens = tokenize(line);
+        }
+        catch (err) {
+            throw new UsageError(`line ${n}: ${err.message}`);
+        }
+        if (tokens.length === 0)
+            continue;
+        if (tokens[0].text === "strom" && !tokens[0].quoted)
+            tokens.shift();
+        const last = tokens.at(-1);
+        let label;
+        if (last && !last.quoted && last.text.startsWith("#")) {
+            if (!new RegExp(`^#${LABEL}$`, "u").test(last.text))
+                throw new UsageError(`line ${n}: invalid label "${last.text}"`, { hint: "a label is a word: #anna, #šimon, #otec_2" });
+            label = last.text.slice(1).normalize("NFC");
+            tokens.pop();
+        }
+        if (tokens.length)
+            out.push({ n, argv: tokens.map((t) => t.text), ...(label ? { label } : {}) });
+    }
+    return out;
+}
+/** Commands that make no sense inside a batch. */
+const NOT_IN_BATCH = new Set(["batch", "run", "session start", "session close", "init", "setup"]);
+function lineError(l, err) {
+    const where = `line ${l.n} (${l.argv.slice(0, 2).join(" ")})`;
+    if (err instanceof AmbiguousError)
+        return new UsageError(`${where}: ${err.message}`, { hint: err.hint ?? "", details: { candidates: err.candidates } });
+    if (err instanceof StromError)
+        return new StromError(`${where}: ${err.message}`, { exitCode: err.exitCode, ...(err.hint ? { hint: err.hint } : {}), ...(err.details !== undefined ? { details: err.details } : {}) });
+    return new StromError(`${where}: ${err.message}`);
+}
+register({
+    path: ["batch"],
+    summary: "Run several writing commands as one change: one call, one commit, all or nothing",
+    group: "people",
+    tree: true,
+    writes: true,
+    description: "Each argument is one command line (without \"strom\"); or give --file, or pipe the lines in.\n" +
+        "End a line with #name to label the record it creates (P…, F…, S…, E…); use it later as @name.\n" +
+        "If any line fails, nothing is written. Lines starting with # are comments.",
+    args: [{ name: "commands", description: "command lines, e.g. 'person add \"Anna /Svobodová/\" --sex F #anna'", variadic: true }],
+    options: [{ name: "file", type: "string", value: "<file>", description: "read the command lines from this file" }],
+    examples: [
+        `strom batch 'person add "Anna /Svobodová/" --sex F #anna' 'family add --partner P0001 --partner @anna --married 1910'`,
+        "strom batch --file krest-1885.txt",
+    ],
+    run: async (ctx, { args, opts }) => {
+        const source = args.length
+            ? args.join("\n")
+            : typeof opts.file === "string"
+                ? fs.readFileSync(ctx.resolvePath(opts.file), "utf8")
+                : (ctx.io.stdinText?.() ?? "");
+        const batch = parseBatch(source);
+        if (batch.length === 0)
+            throw new UsageError("no commands in the batch", { hint: "strom help batch" });
+        const tree = ctx.tree();
+        const labels = new Map();
+        const report = [];
+        for (const l of batch) {
+            const argv = l.argv.map((t) => t.replace(new RegExp(`@(${LABEL})`, "gu"), (m, name) => {
+                if (labels.has(name.normalize("NFC")))
+                    return labels.get(name.normalize("NFC"));
+                return m;
+            }));
+            // "@anna" or "godparent:@anna" left over = a label no earlier line defined.
+            const unknown = argv.map((t) => new RegExp(`(?:^|[:=])@(${LABEL})$`, "u").exec(t)?.[1]).find(Boolean);
+            if (unknown)
+                throw lineError(l, new UsageError(`@${unknown} is not defined`, { hint: `end the line that creates it with #${unknown}` }));
+            try {
+                const { def, rest } = resolveCommand(argv);
+                const name = def.path.join(" ");
+                if (!def.writes || !def.tree || NOT_IN_BATCH.has(name))
+                    throw new UsageError(`strom ${name || "(orientation)"} cannot run in a batch`, { hint: "a batch runs commands that write to the tree: person/family/event/source/cite/task/search …" });
+                const parsed = parseOptions(def, rest);
+                if (parsed.values.tree)
+                    throw new UsageError("--tree applies to the whole batch: strom batch --tree <name> …");
+                checkArgs(def, parsed.positionals);
+                const before = tree.written.length;
+                const r = await def.run(ctx, { args: parsed.positionals, opts: parsed.values });
+                if (r.exitCode)
+                    throw new StromError(r.text.split("\n")[0] ?? "failed");
+                const ops = tree.written.slice(before);
+                const created = ops.map((o) => /^\+([A-Z]\d{4,})/.exec(o.summary)?.[1]).find(Boolean);
+                if (l.label) {
+                    if (!created)
+                        throw new UsageError(`#${l.label}: this line creates no record to label`);
+                    labels.set(l.label, created);
+                }
+                report.push({ line: l.n, command: name, ...(created ? { created } : {}), ...(l.label ? { label: l.label } : {}), summaries: ops.map((o) => o.summary) });
+            }
+            catch (err) {
+                throw lineError(l, err);
+            }
+        }
+        const text = lines(table(report.flatMap((r) => r.summaries.map((s, i) => [i === 0 ? `${r.line}` : "", s, i === 0 && r.label ? `#${r.label}` : ""]))), `${report.length} command(s) as one change${tree.dryRun ? " (dry run — nothing written)" : ""}`);
+        return { text, data: { lines: report, labels: Object.fromEntries(labels) } };
+    },
+});

package/dist/commands/checks.js

@@ -0,0 +1,153 @@
+// check · verify · guard · repair · seal adopt · history
+import fs from "node:fs";
+import path from "node:path";
+import { register } from "../cli/registry.js";
+import { lines, table } from "../cli/format.js";
+import { check } from "../core/check.js";
+import { guard } from "../core/guard.js";
+import { verifyFast, verifyFull } from "../core/integrity.js";
+import { createKey, verifyCommitSeal } from "../core/seal.js";
+import { NeedsConsentError, StromError } from "../core/errors.js";
+import * as git from "../core/git.js";
+export function report(findings, okText) {
+    const errors = findings.filter((f) => f.level === "error");
+    const text = findings.length === 0
+        ? okText
+        : lines(table(findings.map((f) => [f.level === "error" ? "ERROR" : "warn", f.code, f.id ?? f.file ?? "", f.message, f.hint ? `→ ${f.hint}` : ""])), "", `${errors.length} error(s), ${findings.length - errors.length} warning(s)`);
+    return { text, data: { ok: errors.length === 0, findings }, exitCode: errors.length ? 1 : 0 };
+}
+register({
+    path: ["check"],
+    summary: "Is the evidence consistent and untouched? (schema, references, seals, losses)",
+    group: "history",
+    tree: true,
+    run(ctx) {
+        const tree = ctx.tree();
+        return report([...verifyFull(tree).findings, ...check(tree), ...guard(tree)], "ok — data consistent, sealed, nothing lost");
+    },
+}, {
+    path: ["verify"],
+    summary: "Was anything changed outside strom? (seal check of every record and commit)",
+    group: "history",
+    tree: true,
+    options: [{ name: "fast", type: "boolean", description: "only what changed since the last commit (what runs before every write)" }],
+    run(ctx, { opts }) {
+        const tree = ctx.tree();
+        return report((opts.fast ? verifyFast(tree) : verifyFull(tree)).findings, "ok — every record matches its seal");
+    },
+}, {
+    path: ["guard"],
+    summary: "Did anything get lost since the last commit?",
+    group: "history",
+    tree: true,
+    run(ctx) {
+        return report(guard(ctx.tree()), "ok — nothing lost since the last commit");
+    },
+});
+function quarantine(tree, rel, stamp) {
+    const abs = path.join(tree.root, rel);
+    if (!fs.existsSync(abs))
+        return;
+    const dest = path.join(tree.root, ".strom", "quarantine", stamp, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(abs, dest);
+}
+/** Return data/ and strom.json to the newest sealed commit. */
+function repair(tree) {
+    const key = tree.requireKey();
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const head = git.headInfo(tree.root);
+    const sealed = git.findCommit(tree.root, (t, m) => verifyCommitSeal(key, t, m));
+    if (!sealed)
+        throw new StromError("no sealed commit found — nothing to restore from", { hint: "ask the user; the history may have been rewritten" });
+    const headSealed = head !== undefined && verifyCommitSeal(key, head.tree, head.message);
+    // Paths to compare: whatever differs between the sealed commit and the working tree.
+    const candidates = new Set();
+    for (const c of git.changes(tree.root, ["data", "strom.json"]))
+        candidates.add(c.path);
+    if (!headSealed) {
+        const r = git.runGit(tree.root, ["diff", "--name-only", "-z", sealed, "HEAD", "--", "data", "strom.json"]);
+        for (const p of r.stdout.split("\0").filter(Boolean))
+            candidates.add(p);
+    }
+    const sealedContent = git.showFiles(tree.root, sealed, [...candidates]);
+    const restored = [];
+    const quarantined = [];
+    for (const rel of [...candidates].sort()) {
+        const abs = path.join(tree.root, rel);
+        const want = sealedContent.get(rel);
+        const have = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : undefined;
+        if (want === have)
+            continue;
+        quarantine(tree, rel, stamp);
+        if (want === undefined) {
+            fs.rmSync(abs);
+            quarantined.push(rel);
+        }
+        else {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, want);
+            restored.push(rel);
+        }
+    }
+    if (!headSealed)
+        tree.commit(`Repair: restore the sealed state of ${sealed.slice(0, 8)}\n\nCommits made outside strom were undone for data/ and strom.json.`, ["data", "strom.json"]);
+    return { restored, quarantined, from: sealed };
+}
+register({
+    path: ["repair"],
+    summary: "Undo changes made outside strom: restore the last sealed state",
+    group: "history",
+    tree: true,
+    description: "Edited records are restored, records created outside strom are removed; copies of everything\n" +
+        "that was replaced are kept in .strom/quarantine/. Commits made with git directly are undone for data/.",
+    run(ctx) {
+        const tree = ctx.tree();
+        const r = tree.withTreeLock(() => repair(tree));
+        const after = verifyFast(tree).findings.filter((f) => f.level === "error");
+        const text = r.restored.length + r.quarantined.length === 0
+            ? "nothing to repair — every record matches its seal"
+            : lines(...r.restored.map((f) => `restored  ${f}`), ...r.quarantined.map((f) => `removed   ${f}`), `sealed state: ${r.from.slice(0, 8)} · copies of replaced files: .strom/quarantine/`, after.length ? `still ${after.length} problem(s) → strom verify` : undefined);
+        return { text, data: { ...r, ok: after.length === 0 }, exitCode: after.length ? 1 : 0 };
+    },
+}, {
+    path: ["seal", "adopt"],
+    summary: "Take over a tree sealed on another computer (the user runs this in a terminal)",
+    group: "history",
+    tree: true,
+    description: "Checks the chain and every record hash, then creates this computer's seal key for the tree.\nAgents must not run this — it needs the user's confirmation.",
+    run: async (ctx) => {
+        const tree = ctx.tree();
+        if (tree.key)
+            return { text: "this tree is already sealed on this computer", data: { adopted: false } };
+        if (!ctx.interactive)
+            throw new NeedsConsentError([
+                { key: "seal", kind: "consent", question: "Take over this tree on this computer?", set: "strom seal adopt" },
+            ]);
+        const problems = verifyFull(tree).findings.filter((f) => f.level === "error");
+        if (problems.length)
+            return report(problems, "");
+        if (!(await ctx.confirm(`Take over "${tree.config.name}" on this computer?`, true)))
+            return { text: "cancelled", data: { adopted: false } };
+        tree.withTreeLock(() => {
+            createKey(tree.env, tree.config.id);
+            tree.reloadKey();
+            tree.appendOp({ op: "seal.adopt", targets: [], files: [], summary: "Tree adopted on this computer" });
+            tree.commit("Seal: tree adopted on this computer");
+        });
+        return { text: `"${tree.config.name}" is now sealed on this computer`, data: { adopted: true } };
+    },
+}, {
+    path: ["history"],
+    summary: "What changed recently (one line per change)",
+    group: "history",
+    tree: true,
+    run(ctx) {
+        const tree = ctx.tree();
+        const commits = git.log(tree.root, ctx.limit);
+        const text = commits.length
+            ? table(commits.map((c) => [c.hash.slice(0, 8), c.at.slice(0, 16).replace("T", " "), c.subject]))
+            : "no history yet";
+        return { text, data: { commits } };
+    },
+});