strom-research 1.0.0

package/dist/core/tree.js

@@ -0,0 +1,507 @@
+// A tree = one folder = one git repository holding the evidence of one
+// family (it matches one tree in the Strom app). Researches live inside it.
+//
+// Layout:
+//   strom.json            tree config (name, research language, schema)
+//   data/<dir>/<ID>.json  one record per file (canonical JSON)
+//   data/_counters.json   ID counters (never reused)
+//   data/ops/*.jsonl      append-only operation log
+//   output/               generated files (tree.ged, ...)
+//   notes/ inputs/        free prose, material from the family
+//   .strom/               local state: locks, cache (git-ignored)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, readJsonIfExists, writeJson, appendJsonLine, writeFileAtomic } from "./json.js";
+import { acquireLock, withLock } from "./lock.js";
+/** How long a writer waits for the tree while another one works (a long intake, a batch). */
+const LOCK_WAIT_MS = 120_000;
+import { RECORD_TYPES, ALL_PREFIXES, SCHEMA_VERSION } from "./model.js";
+import { validateRecord } from "./validate.js";
+import { NeedsConsentError, StromError, UsageError } from "./errors.js";
+import * as git from "./git.js";
+import { commitSeal, createKey, fingerprint, loadKey, sha256, signOp } from "./seal.js";
+import { stringifyCanonical } from "./json.js";
+export const TREE_FILE = "strom.json";
+export const VERSION = "1.0.0";
+const GITIGNORE = `# Strom Research — local state and large files are not versioned
+.strom/
+/media/
+node_modules/
+*.tmp
+.DS_Store
+`;
+export function isTreeDir(dir) {
+    return fs.existsSync(path.join(dir, TREE_FILE));
+}
+/** Walk up from `start` to the first folder containing strom.json. */
+export function findTreeUpwards(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (isTreeDir(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+export function now() {
+    return new Date().toISOString();
+}
+export function formatId(prefix, n) {
+    return prefix + String(n).padStart(4, "0");
+}
+export function prefixOf(id) {
+    return /^([A-Z])\d+$/.exec(id)?.[1];
+}
+export function typeOfId(id) {
+    const p = prefixOf(id);
+    return p ? typeOfPrefix(p) : undefined;
+}
+export function typeOfPrefix(prefix) {
+    for (const [type, def] of Object.entries(RECORD_TYPES))
+        if (def.prefix === prefix)
+            return type;
+    return undefined;
+}
+export class Tree {
+    root;
+    config;
+    /** Who writes: a session ID, "agent" (an agent outside a session) or "user". */
+    actor = "user";
+    dryRun = false;
+    cache = new Map();
+    /** Records read one by one before their whole type was loaded. */
+    single = new Map();
+    /** Last signature per operation log, so appending does not re-read the log. */
+    lastSigs = new Map();
+    /** Operation logs this process appended to (to commit them). */
+    touchedOps = new Set();
+    /** Original content of every file this command changed (null = did not exist): the undo log. */
+    undo = new Map();
+    /** Ops written during this process (for the automatic commit message). */
+    written = [];
+    env;
+    /** Bumped on every write; lets derived indexes know they are stale. */
+    version = 0;
+    keyCache;
+    constructor(root, config, env) {
+        this.root = root;
+        this.config = config;
+        this.env = env;
+    }
+    static open(root, env) {
+        const file = path.join(root, TREE_FILE);
+        if (!fs.existsSync(file))
+            throw new StromError(`not a Strom tree: ${root}`, { hint: "strom trees" });
+        const config = readJson(file);
+        if (!config.id)
+            throw new StromError(`tree config has no id: ${file}`);
+        git.resetCache(root); // other processes (an agent) may have committed since
+        if (config.schema > SCHEMA_VERSION)
+            throw new StromError(`tree was written by a newer Strom (schema ${config.schema})`, { hint: "update strom" });
+        return new Tree(root, config, env);
+    }
+    /** Create a new tree folder with a git repository and a first commit. */
+    static create(root, name, lang, env) {
+        if (fs.existsSync(root) && fs.readdirSync(root).length > 0)
+            throw new UsageError(`folder is not empty: ${root}`, { hint: "choose a new folder name" });
+        if (!git.gitVersion())
+            throw git.gitMissingError();
+        fs.mkdirSync(root, { recursive: true });
+        const config = { schema: SCHEMA_VERSION, id: crypto.randomUUID(), name, lang, created: now(), createdWith: VERSION };
+        writeJson(path.join(root, TREE_FILE), config);
+        for (const d of ["data", "output", "notes", "inputs"])
+            fs.mkdirSync(path.join(root, d), { recursive: true });
+        writeJson(path.join(root, "data", "_counters.json"), {});
+        writeFileAtomic(path.join(root, ".gitignore"), GITIGNORE);
+        for (const d of ["output", "notes", "inputs"])
+            writeFileAtomic(path.join(root, d, ".gitkeep"), "");
+        git.initRepo(root);
+        const tree = new Tree(root, config, env);
+        createKey(env, config.id);
+        tree.commit(`Create tree "${name}"`);
+        return tree;
+    }
+    get dataDir() {
+        return path.join(this.root, "data");
+    }
+    lockFile() {
+        return path.join(this.root, ".strom", "tree.lock");
+    }
+    lockDepth = 0;
+    counters;
+    /**
+     * Run under the tree lock (re-entrant). ID counters are flushed on the way out.
+     * Several strom processes write to one tree side by side (agents in their
+     * conversations, a run on its own): whoever takes the lock reads the records
+     * afresh, so nobody writes over what another one wrote meanwhile.
+     */
+    withTreeLock(fn) {
+        if (this.lockDepth > 0) {
+            this.lockDepth++;
+            try {
+                return fn();
+            }
+            finally {
+                this.lockDepth--;
+                // Back at a whole command's hold (holdTreeLock): its IDs are on disk before it commits.
+                if (this.lockDepth === 1)
+                    this.flushCounters();
+            }
+        }
+        return withLock(this.lockFile(), { owner: `strom ${this.actor}`, waitMs: LOCK_WAIT_MS, staleMs: 60_000 }, () => {
+            this.lockDepth = 1;
+            this.fresh();
+            try {
+                return fn();
+            }
+            finally {
+                this.lockDepth = 0;
+                this.flushCounters();
+            }
+        });
+    }
+    /**
+     * Hold the tree lock over a whole command — what it reads, what it writes and
+     * its commit — so another process never slips in between (the usual way for
+     * a writing command; long ones lock only while they write).
+     */
+    async holdTreeLock(fn) {
+        if (this.lockDepth > 0)
+            return fn();
+        const release = acquireLock(this.lockFile(), { owner: `strom ${this.actor}`, waitMs: LOCK_WAIT_MS, staleMs: 60_000 });
+        this.lockDepth = 1;
+        this.fresh();
+        try {
+            return await fn();
+        }
+        finally {
+            this.lockDepth = 0;
+            this.flushCounters();
+            release();
+        }
+    }
+    /** Forget what was read before the lock: another process may have written since. */
+    fresh() {
+        git.resetCache(this.root); // and what git said: another process may have committed while this one waited
+        if (this.dryRun)
+            return; // a dry run's own writes live only in memory
+        this.cache.clear();
+        this.single.clear();
+        this.lastSigs.clear();
+        this.version++;
+    }
+    flushCounters() {
+        // A dry run keeps its counters in memory, so later steps get fresh IDs too.
+        if (this.dryRun)
+            return;
+        if (this.counters) {
+            this.remember(this.countersFile());
+            writeJson(this.countersFile(), this.counters);
+        }
+        this.counters = undefined;
+    }
+    /** Record a file's current content before this command changes it. */
+    remember(file) {
+        if (this.undo.has(file))
+            return;
+        try {
+            this.undo.set(file, fs.readFileSync(file));
+        }
+        catch {
+            this.undo.set(file, null);
+        }
+    }
+    /** Undo every change this command made — a failed command leaves nothing behind. */
+    rollback() {
+        const restored = [];
+        for (const [file, content] of this.undo) {
+            if (content === null)
+                fs.rmSync(file, { force: true });
+            else
+                fs.writeFileSync(file, content);
+            restored.push(this.relative(file));
+        }
+        this.undo.clear();
+        this.cache.clear();
+        this.single.clear();
+        this.lastSigs.clear();
+        this.touchedOps.clear();
+        this.counters = undefined;
+        this.written.length = 0;
+        this.version++;
+        return restored;
+    }
+    /** Forget the undo log once the changes are committed. */
+    settle() {
+        this.undo.clear();
+    }
+    recordPath(type, id) {
+        return path.join(this.dataDir, RECORD_TYPES[type].dir, `${id}.json`);
+    }
+    relative(p) {
+        return path.relative(this.root, p).split(path.sep).join("/");
+    }
+    // ── reading ────────────────────────────────────────────────────────────
+    list(type) {
+        let map = this.cache.get(type);
+        if (!map) {
+            map = new Map();
+            const dir = path.join(this.dataDir, RECORD_TYPES[type].dir);
+            if (fs.existsSync(dir)) {
+                for (const f of fs.readdirSync(dir).sort()) {
+                    if (!f.endsWith(".json"))
+                        continue;
+                    let rec;
+                    try {
+                        rec = readJson(path.join(dir, f));
+                    }
+                    catch {
+                        continue; // unreadable record: reported by `strom check`
+                    }
+                    map.set(rec.id, rec);
+                }
+            }
+            // Records this process already holds win: after a dry-run write they exist only here.
+            for (const [id, rec] of this.single)
+                if (rec && rec.type === type)
+                    map.set(id, rec);
+            this.cache.set(type, map);
+        }
+        return [...map.values()];
+    }
+    /** One record. Reads just its file unless the whole type is already loaded. */
+    get(id) {
+        const type = typeOfId(id);
+        if (!type)
+            return undefined;
+        const loaded = this.cache.get(type);
+        if (loaded)
+            return loaded.get(id);
+        let one = this.single.get(id);
+        if (one === undefined) {
+            try {
+                one = readJson(this.recordPath(type, id));
+            }
+            catch {
+                one = null;
+            }
+            this.single.set(id, one);
+        }
+        return (one ?? undefined);
+    }
+    /** Number of records of a type without reading them. */
+    count(type) {
+        const loaded = this.cache.get(type);
+        if (loaded)
+            return loaded.size;
+        const dir = path.join(this.dataDir, RECORD_TYPES[type].dir);
+        if (!fs.existsSync(dir))
+            return 0;
+        let n = 0;
+        for (const f of fs.readdirSync(dir))
+            if (f.endsWith(".json"))
+                n++;
+        return n;
+    }
+    // ── IDs ────────────────────────────────────────────────────────────────
+    countersFile() {
+        return path.join(this.dataDir, "_counters.json");
+    }
+    /** Highest ID number present on disk for a record type (guards counter drift). */
+    maxOnDisk(prefix) {
+        const type = Object.entries(RECORD_TYPES).find(([, d]) => d.prefix === prefix)?.[0];
+        let max = 0;
+        const ids = [];
+        if (type)
+            ids.push(...this.list(type).map((r) => r.id));
+        else if (prefix === "E")
+            for (const t of ["person", "family"])
+                for (const r of this.list(t))
+                    for (const e of r.events ?? [])
+                        ids.push(e.id);
+        for (const id of ids) {
+            const n = Number(id.slice(1));
+            if (id.startsWith(prefix) && n > max)
+                max = n;
+        }
+        return max;
+    }
+    /** Allocate the next ID for a prefix. Call inside withTreeLock. */
+    allocate(prefix) {
+        if (!Object.values(ALL_PREFIXES).includes(prefix))
+            throw new StromError(`unknown ID prefix ${prefix}`);
+        if (this.lockDepth === 0)
+            throw new StromError("internal: allocate() outside withTreeLock()");
+        // Read once per lock, kept in memory, written when the lock is released.
+        this.counters ??= readJsonIfExists(this.countersFile()) ?? {};
+        // Counters are authoritative; the disk is scanned only when one is missing.
+        let next = (this.counters[prefix] ?? this.maxOnDisk(prefix)) + 1;
+        // A counter edited by hand must never hand out an ID that is taken.
+        const type = typeOfPrefix(prefix);
+        if (type)
+            while (fs.existsSync(this.recordPath(type, formatId(prefix, next))))
+                next++;
+        this.counters[prefix] = next;
+        return formatId(prefix, next);
+    }
+    /** Preview the next ID without allocating it. */
+    peekId(prefix) {
+        const counters = this.counters ?? readJsonIfExists(this.countersFile()) ?? {};
+        return formatId(prefix, (counters[prefix] ?? this.maxOnDisk(prefix)) + 1);
+    }
+    // ── writing ────────────────────────────────────────────────────────────
+    opsFile() {
+        const month = now().slice(0, 7);
+        const name = this.actor === "user" || this.actor === "agent" ? `${this.actor}-${month}` : this.actor;
+        return path.join(this.dataDir, "ops", `${name}.jsonl`);
+    }
+    lastSig(file) {
+        const known = this.lastSigs.get(file);
+        if (known !== undefined)
+            return known;
+        if (!fs.existsSync(file))
+            return "";
+        const text = fs.readFileSync(file, "utf8").trimEnd();
+        const last = text.slice(text.lastIndexOf("\n") + 1);
+        if (!last)
+            return "";
+        try {
+            return JSON.parse(last).sig ?? "";
+        }
+        catch {
+            return "";
+        }
+    }
+    /** The tree's seal key on this computer, or undefined (tree moved here). */
+    get key() {
+        if (this.keyCache === undefined)
+            this.keyCache = loadKey(this.env, this.config.id) ?? null;
+        return this.keyCache ?? undefined;
+    }
+    lastStamp = 0;
+    /** Strictly increasing timestamps: operations are ordered by time across logs. */
+    stamp() {
+        this.lastStamp = Math.max(Date.now(), this.lastStamp + 1);
+        return new Date(this.lastStamp).toISOString();
+    }
+    /** Operation logs appended to by this process (tree-relative). */
+    opsFilesTouched() {
+        return [...this.touchedOps].map((f) => this.relative(f));
+    }
+    /** Forget the cached key (after one was created on this computer). */
+    reloadKey() {
+        this.keyCache = undefined;
+    }
+    requireKey() {
+        const key = this.key;
+        if (key)
+            return key;
+        throw new NeedsConsentError([
+            {
+                key: "seal",
+                kind: "consent",
+                question: "This tree was sealed on another computer. Take it over on this one?",
+                set: "strom seal adopt",
+            },
+        ]);
+    }
+    /** Sealed commit of everything under pathspec. */
+    commit(message, pathspec = ["."]) {
+        const key = this.requireKey();
+        git.resetCache(this.root); // another process may have committed since this one last looked
+        return git.commitAll(this.root, message, pathspec, (treeHash) => commitSeal(key, treeHash));
+    }
+    /** Append a signed operation to the current log (inside withTreeLock). */
+    appendOp(op) {
+        const key = this.requireKey();
+        const opsFile = this.opsFile();
+        const entry = { at: this.stamp(), by: this.actor, ...op, prev: this.lastSig(opsFile), k: fingerprint(key), sig: "" };
+        entry.sig = signOp(entry, key);
+        this.written.push(entry);
+        if (!this.dryRun) {
+            this.remember(opsFile);
+            appendJsonLine(opsFile, entry);
+            this.lastSigs.set(opsFile, entry.sig);
+            this.touchedOps.add(opsFile);
+        }
+        return entry;
+    }
+    /** Validate and write a record, then log the sealed operation. Call inside withTreeLock. */
+    put(input, op) {
+        const record = composed(input);
+        const problems = validateRecord(record);
+        if (problems.length > 0) {
+            throw new UsageError(`invalid ${record.type} ${record.id}: ${problems.map((p) => `${p.path} ${p.message}`).join("; ")}`, {
+                details: problems,
+            });
+        }
+        const file = this.recordPath(record.type, record.id);
+        const content = stringifyCanonical(record);
+        this.appendOp({ ...op, summary: op.summary.normalize("NFC"), ...(op.reason ? { reason: op.reason.normalize("NFC") } : {}), files: [{ path: this.relative(file), sha: sha256(content) }] });
+        // A dry run keeps the change in memory only, so the next step of the same
+        // command (a research on a person it just created) still sees it.
+        if (!this.dryRun) {
+            this.remember(file);
+            writeFileAtomic(file, content);
+        }
+        this.version++;
+        this.single.set(record.id, record);
+        this.cache.get(record.type)?.set(record.id, record);
+    }
+    readOps() {
+        const dir = path.join(this.dataDir, "ops");
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const f of fs.readdirSync(dir).sort()) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            for (const line of fs.readFileSync(path.join(dir, f), "utf8").split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    out.push(JSON.parse(line));
+                }
+                catch {
+                    // a damaged line is reported by `strom verify`
+                }
+            }
+        }
+        return out;
+    }
+    /** Research language for this invocation: an override from outside (--lang, STROM_LANG) or the tree's own. */
+    langOverride;
+    get lang() {
+        return this.langOverride ?? this.config.lang;
+    }
+    /** Change strom.json as a logged, sealed operation. */
+    updateConfig(change, op) {
+        this.withTreeLock(() => {
+            change(this.config);
+            const file = path.join(this.root, TREE_FILE);
+            const content = stringifyCanonical(this.config);
+            this.appendOp({ op: op.op, targets: [], summary: op.summary, files: [{ path: TREE_FILE, sha: sha256(content) }] });
+            if (this.dryRun)
+                return;
+            this.remember(file);
+            writeFileAtomic(file, content);
+        });
+    }
+}
+/**
+ * Every text of a record in composed form (NFC): "č" is one letter whether it
+ * came typed, copied or from a macOS file name. File paths stay as they are —
+ * on Linux a decomposed name is another file.
+ */
+function composed(value, key = "") {
+    if (typeof value === "string")
+        return key === "file" ? value : value.normalize("NFC");
+    if (Array.isArray(value))
+        return value.map((v) => composed(v));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, composed(v, k)]));
+    return value;
+}

package/dist/core/uninstall.js

@@ -0,0 +1,128 @@
+// What strom put on this computer outside the research, and taking it away
+// again (strom uninstall): what the agents were taught, the shortcut, strom's
+// own git, the PATH lines of the installer and the program itself. The
+// research stays, and so do the settings with the keys that seal it — they
+// are the user's; strom says where they are.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { desktopDir, userHome } from "./paths.js";
+import { ownGitDir } from "./git.js";
+import { globalTargets, isInstalled, uninstallGlobal } from "../agents/global.js";
+import { PROFILES } from "../agents/profiles.js";
+import { installation } from "./self.js";
+/** The mark the installer (install/install.sh) puts on the PATH line it adds. */
+const MARK = "# strom research";
+function exists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A shortcut strom made: its name in any language strom speaks, and it starts strom. */
+function shortcuts(env, platform, names) {
+    const desktop = desktopDir(env, platform);
+    const files = platform === "darwin"
+        ? names.map((n) => path.join(desktop, `${n}.command`))
+        : platform === "win32"
+            ? names.map((n) => path.join(desktop, `${n}.cmd`))
+            : [path.join(env.XDG_DATA_HOME ?? path.join(userHome(env), ".local", "share"), "applications", "strom-research.desktop"), path.join(desktop, "strom-research.desktop")];
+    return [...new Set(files)].filter((f) => {
+        try {
+            return /strom/i.test(fs.readFileSync(f, "utf8"));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Shell files with the installer's PATH line. */
+function pathLines(env) {
+    const home = userHome(env);
+    return [".zshrc", ".bashrc", ".bash_profile", ".profile"].map((f) => path.join(home, f)).filter((f) => {
+        try {
+            return fs.readFileSync(f, "utf8").includes(MARK);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function dropLines(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const kept = text.split("\n").filter((l) => !l.includes(MARK));
+    // the installer put a blank line before its own
+    const out = kept.join("\n").replace(/\n\n+$/, "\n");
+    fs.writeFileSync(file, out);
+    return true;
+}
+/** The user's PATH on Windows without this folder. */
+function dropWindowsPath(dir) {
+    const ps = `$d='${dir.replace(/'/g, "''")}'; $p=[Environment]::GetEnvironmentVariable('Path','User'); if ($p) { [Environment]::SetEnvironmentVariable('Path', (($p -split ';') | Where-Object { $_ -and $_ -ne $d }) -join ';', 'User') }`;
+    return spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps], { stdio: "ignore", windowsHide: true }).status === 0;
+}
+function onWindowsPath(dir) {
+    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "[Environment]::GetEnvironmentVariable('Path','User')"], { encoding: "utf8", windowsHide: true });
+    return r.status === 0 && r.stdout.split(";").map((s) => s.trim()).includes(dir);
+}
+/**
+ * strom as the installer put it: its folder (Node, strom's code, strom's own
+ * git) and the commands on PATH. A running program can be deleted on macOS and
+ * Linux; on Windows the folder is deleted by a small command a moment after
+ * strom ends.
+ */
+function removeInstallation(root, launchers, platform) {
+    const outside = launchers.filter((l) => path.dirname(l) !== root);
+    for (const l of outside)
+        fs.rmSync(l, { force: true });
+    if (platform !== "win32") {
+        fs.rmSync(root, { recursive: true, force: true });
+        return true;
+    }
+    const child = spawn(process.env.ComSpec ?? "cmd.exe", ["/d", "/c", `ping 127.0.0.1 -n 3 >nul & rmdir /s /q "${root}"`], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+    return true;
+}
+/** What strom uninstall takes away here. `names` are the shortcut's names in the languages strom speaks. */
+export function uninstallPlan(env, names, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const remove = [];
+    for (const t of globalTargets(env).filter((t) => isInstalled(t)))
+        remove.push({ kind: "agent", agent: PROFILES[t.agent]?.name ?? t.agent, path: t.file, remove: () => uninstallGlobal(t) });
+    for (const f of shortcuts(env, platform, names))
+        remove.push({ kind: "shortcut", path: f, remove: () => (fs.rmSync(f, { force: true }), true) });
+    const inst = opts.install ?? installation();
+    const git = ownGitDir(env);
+    // strom's own git lives in the installation's folder on Windows; alone, it goes by itself.
+    if (platform === "win32" && exists(git) && !(inst.root && git.startsWith(inst.root + path.sep)))
+        remove.push({ kind: "git", path: git, remove: () => (fs.rmSync(git, { recursive: true, force: true }), true) });
+    if (platform !== "win32") {
+        for (const f of pathLines(env))
+            remove.push({ kind: "path", path: f, remove: () => dropLines(f) });
+        const fish = path.join(env.XDG_CONFIG_HOME ?? path.join(userHome(env), ".config"), "fish", "conf.d", "strom.fish");
+        try {
+            if (fs.readFileSync(fish, "utf8").includes(MARK))
+                remove.push({ kind: "path", path: fish, remove: () => (fs.rmSync(fish, { force: true }), true) });
+        }
+        catch {
+            // none
+        }
+    }
+    const program = inst.kind === "installed" ? inst.root : undefined;
+    if (program) {
+        const launchers = inst.launchers ?? [];
+        const dirs = [...new Set([program, ...launchers.map((l) => path.dirname(l))])];
+        if (platform === "win32")
+            for (const d of dirs.filter((d) => onWindowsPath(d)))
+                remove.push({ kind: "path", path: d, remove: () => dropWindowsPath(d) });
+        remove.push({ kind: "program", path: program, remove: () => removeInstallation(program, launchers, platform) });
+    }
+    return { remove, npm: inst.kind === "npm", ...(program ? { program } : {}) };
+}