strom-research 1.0.0

package/dist/cli/main.js

@@ -0,0 +1,152 @@
+// CLI entry: find the command, parse options, run it, print the result,
+// and commit what a writing command changed. Returns the exit code.
+import { EXIT, StromError, UsageError } from "../core/errors.js";
+import { Context } from "./context.js";
+import { groupHelp, helpFor } from "./help.js";
+import { autoCommit } from "./commit.js";
+import { assertIntact } from "../core/integrity.js";
+import { resetCache } from "../core/git.js";
+import { VERSION } from "../core/tree.js";
+import { isAgent } from "../core/which.js";
+import { noticeStromApp } from "../core/stromapp.js";
+import { checkArgs, GroupOnly, parseOptions, resolveCommand, splitPassthrough } from "./execute.js";
+import "../commands/index.js";
+export { splitCommand } from "./execute.js";
+/** Compact JSON: indentation costs an agent tokens and adds nothing for a parser. */
+function toJson(value) {
+    return JSON.stringify(value) + "\n";
+}
+function print(io, ctx, result) {
+    if (ctx?.json)
+        io.stdout(toJson(result.data ?? { text: result.text }));
+    else if (result.text)
+        io.stdout(result.text.endsWith("\n") ? result.text : result.text + "\n");
+}
+/** File-system errors in plain words (a missing @file, a folder without rights). */
+function systemError(e) {
+    const where = e.path ? `: ${e.path}` : "";
+    switch (e.code) {
+        case "ENOENT":
+            return new UsageError(`no such file or folder${where}`, { hint: "check the path (relative paths start in the current folder)" });
+        case "EACCES":
+        case "EPERM":
+            return new UsageError(`no permission to use${where}`, { hint: "choose a folder you can write to" });
+        case "EISDIR":
+            return new UsageError(`a folder was given where a file is expected${where}`);
+        case "ENOTDIR":
+            return new UsageError(`a file was given where a folder is expected${where}`);
+        case "ENOSPC":
+            return new StromError(`the disk is full${where}`);
+    }
+    return undefined;
+}
+function printError(io, json, err, debug) {
+    const e = err instanceof StromError ? err : (systemError(err) ?? err);
+    if (e instanceof StromError) {
+        if (json)
+            io.stdout(toJson(e.toJSON()));
+        else {
+            io.stderr(`error: ${e.message}\n`);
+            const cands = e.details?.candidates;
+            if (cands)
+                for (const c of cands)
+                    io.stderr(`  ${c.label}\n`);
+            if (e.hint)
+                for (const h of e.hint.split("\n"))
+                    io.stderr(`→ ${h}\n`);
+            if (debug && err.stack)
+                io.stderr(err.stack + "\n");
+        }
+        return e.exitCode;
+    }
+    const x = e;
+    if (json)
+        io.stdout(toJson({ status: "error", message: x.message }));
+    else {
+        io.stderr(`error: ${x.message}\n`);
+        io.stderr(debug ? `${x.stack}\n` : "→ run again with --debug for details\n");
+    }
+    return EXIT.error;
+}
+export async function main(argv, io, env, cwd) {
+    const json = argv.includes("--json");
+    const debug = argv.includes("--debug");
+    resetCache();
+    try {
+        // "strom 'person list'" (one quoted word) means the same as strom person list.
+        if (argv[0] && !argv[0].startsWith("-") && /\s/.test(argv[0].trim()))
+            argv = [...argv[0].trim().split(/\s+/), ...argv.slice(1)];
+        // A person at a terminal gets the guided menu; an agent, a script or the app the orientation.
+        if (argv.length === 0 && io.tty && !isAgent(env) && env.STROM_NONINTERACTIVE !== "1")
+            argv = ["menu"];
+        if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
+            io.stdout(json ? toJson({ version: VERSION }) : `strom ${VERSION}\n`);
+            return EXIT.ok;
+        }
+        let resolved;
+        try {
+            resolved = resolveCommand(argv);
+        }
+        catch (err) {
+            if (err instanceof GroupOnly) {
+                io.stdout(groupHelp(err.group) + "\n");
+                return EXIT.ok;
+            }
+            throw err;
+        }
+        const { def } = resolved;
+        const { rest, passthrough } = def.passthrough ? splitPassthrough(resolved.rest) : { rest: resolved.rest, passthrough: [] };
+        const parsed = parseOptions(def, rest);
+        const v = parsed.values;
+        if (v.help) {
+            io.stdout(helpFor(def.path) + "\n");
+            return EXIT.ok;
+        }
+        if (v.version) {
+            io.stdout(json ? toJson({ version: VERSION }) : `strom ${VERSION}\n`);
+            return EXIT.ok;
+        }
+        const ctx = Context.fromOptions({ env, cwd, io, json, values: v });
+        // Started by the Strom app: remembered quietly (it is where the results go).
+        if (env.STROM_APP)
+            noticeStromApp(ctx.settings, env);
+        const args = parsed.positionals;
+        checkArgs(def, args);
+        if (def.writes && v["dry-run"])
+            ctx.dryRun = true;
+        const work = async () => {
+            // Never write on top of data that was changed outside strom.
+            if (def.writes && def.tree)
+                assertIntact(ctx.tree());
+            let result;
+            try {
+                result = await def.run(ctx, { args, opts: v, ...(passthrough.length ? { extra: passthrough } : {}) });
+            }
+            catch (err) {
+                // A writing command is a transaction: on failure nothing it wrote remains.
+                const t = def.writes ? ctx.current() : undefined;
+                if (t)
+                    t.withTreeLock(() => t.rollback());
+                throw err;
+            }
+            if (def.writes) {
+                const blocked = autoCommit(ctx, def);
+                if (blocked) {
+                    // The agent must notice: an uncommitted write is not part of the research yet.
+                    result.text = result.text ? `${result.text}\n${blocked.message}` : blocked.message;
+                    result.data = { ...(result.data ?? {}), status: "not-committed", problems: blocked.problems, hint: "strom check" };
+                    result.exitCode = EXIT.error;
+                }
+            }
+            return result;
+        };
+        // Other strom processes may write to the same tree (other agents, a run): a writing
+        // command has the tree to itself from its first read to its commit.
+        const result = def.writes && def.tree && def.lock !== "sections" ? await ctx.tree().holdTreeLock(work) : await work();
+        print(io, ctx, result);
+        return result.exitCode ?? EXIT.ok;
+    }
+    catch (err) {
+        return printError(io, json, err, debug);
+    }
+}

package/dist/cli/menu.js

@@ -0,0 +1,212 @@
+// The guided menu: what a person gets from `strom` at a terminal (or the
+// shortcut on the desktop). In their language, numbered, Enter takes the
+// first choice — continuing the research in a conversation with the agent,
+// which is how the research is done. Every item runs an ordinary command, so
+// nothing here is a second way of doing things.
+//
+// First time: the setup wizard, a name for the family tree, and straight into
+// the first conversation with the agent.
+import fs from "node:fs";
+import path from "node:path";
+import { ui } from "./ui.js";
+import { Tree, VERSION } from "../core/tree.js";
+import { liveHolder } from "../core/lock.js";
+import { newerVersion } from "../core/update.js";
+import { waitingForUser } from "../commands/tasks.js";
+import { noticeStromApp, stromAppState } from "../core/stromapp.js";
+import { openForUser } from "../core/open.js";
+import { AGENTS, findAgent } from "../core/which.js";
+import { agentsHere } from "../core/apps.js";
+import { PROFILES } from "../agents/profiles.js";
+/** Create a family tree and say so in the user's words (init itself talks to agents). */
+async function createTree(ctx, run, lang, name) {
+    const before = new Set(ctx.knownTrees().map((k) => k.root));
+    if ((await run(["init", name], true)) !== 0)
+        return undefined;
+    const made = ctx.knownTrees().find((k) => !before.has(k.root));
+    if (made)
+        ctx.io.stdout(ui(lang, "ui.tree.created", { name: made.name, dir: ctx.display(made.root) }) + "\n");
+    return made?.root;
+}
+export async function runMenu(ctx, run) {
+    const out = (line = "") => ctx.io.stdout(line + "\n");
+    const outOfAnswers = () => ctx.io.answers !== undefined && ctx.io.answers.length === 0;
+    const reload = () => ctx.settings.reload();
+    const pause = async (lang) => {
+        if (!outOfAnswers())
+            await ctx.ask(ui(lang, "ui.enter"));
+    };
+    // First time on this computer: the wizard.
+    if (!ctx.settings.home()) {
+        await run(["setup"]);
+        reload();
+        if (!ctx.settings.home())
+            return;
+    }
+    noticeStromApp(ctx.settings, ctx.env, { look: true });
+    for (;;) {
+        reload();
+        const lang = ctx.uiLang();
+        const t = (key, values = {}) => ui(lang, key, values);
+        const known = ctx.knownTrees();
+        let root;
+        try {
+            root = ctx.locateTree();
+        }
+        catch {
+            root = undefined;
+        }
+        // No family tree yet: name it, create it, and start the research.
+        if (!root && known.length === 0) {
+            if (outOfAnswers())
+                return;
+            const name = await ctx.ask(t("ui.tree.name"), t("ui.tree.default"));
+            if (!(await createTree(ctx, run, lang, name)))
+                return;
+            reload();
+            await run(["chat"]);
+            if (outOfAnswers())
+                return;
+            continue;
+        }
+        const items = [];
+        out();
+        out(t("ui.menu.title", { version: VERSION }));
+        const newer = await newerVersion(ctx.settings, ctx.env);
+        if (newer)
+            out(t("ui.menu.update.line", { version: newer }));
+        if (root) {
+            const tree = Tree.open(root, ctx.env);
+            const waiting = waitingForUser(tree).length;
+            const started = tree.list("research").length > 0;
+            out(t("ui.menu.tree", { name: tree.config.name, persons: tree.count("person") }));
+            if (waiting)
+                out(t("ui.menu.waiting", { count: waiting }));
+            if (liveHolder(path.join(root, ".strom", "run.lock")))
+                out(t("ui.menu.working"));
+            items.push({ key: "1", label: t(started ? "ui.menu.chat" : "ui.menu.start"), act: async () => void (await run(["chat"])) }, {
+                key: "2",
+                label: t("ui.menu.run"),
+                act: async () => {
+                    // Working alone is the agent's CLI; with only its app on this computer, strom says so.
+                    const who = PROFILES[ctx.settings.agent(tree.config).value];
+                    if (who && !findAgent(who.command, ctx.env)) {
+                        out(t("ui.run.needscli", { agent: who.name }));
+                        await pause(lang);
+                        return;
+                    }
+                    let n = 0;
+                    while (!(Number.isInteger(n) && n > 0 && n <= 100)) {
+                        if (outOfAnswers())
+                            return;
+                        n = Number(await ctx.ask(t("ui.run.how"), "3"));
+                    }
+                    out(t("ui.run.start"));
+                    await run(["run", "--max", String(n)]);
+                    await pause(lang);
+                },
+            }, {
+                key: "3",
+                label: `${t("ui.menu.waitlist")}${waiting ? ` (${waiting})` : ""}`,
+                act: async () => {
+                    if (!waiting)
+                        out(t("ui.waiting.none"));
+                    else {
+                        await run(["task", "list", "--state", "waiting"]);
+                        const inbox = ctx.settings.shared() ? path.join(ctx.settings.shared().value, "inbox") : undefined;
+                        if (inbox && (await ctx.confirm(t("ui.waiting.open"), false)))
+                            openForUser(inbox, ctx.env);
+                    }
+                    await pause(lang);
+                },
+            }, {
+                key: "4",
+                label: t("ui.menu.results"),
+                act: async () => {
+                    const outDir = path.join(root, "output");
+                    const geds = ["tree.ged", "tree-strom.ged"].map((f) => path.join(outDir, f)).filter((f) => fs.existsSync(f));
+                    if (!geds.length)
+                        out(t("ui.results.none"));
+                    else {
+                        out(t("ui.results.files"));
+                        for (const g of geds)
+                            out(`  ${ctx.display(g)}`);
+                        const strom = geds.find((g) => g.endsWith("tree-strom.ged"));
+                        const app = stromAppState(ctx.settings);
+                        if (strom && (app === "yes" || app === "seen"))
+                            out(t("ui.results.app", { file: ctx.display(strom) }));
+                        else if (strom && app === "unknown")
+                            out(t("ui.results.app.maybe", { file: ctx.display(strom) }));
+                        if (await ctx.confirm(t("ui.results.open"), false))
+                            openForUser(outDir, ctx.env);
+                    }
+                    await pause(lang);
+                },
+            });
+            // Several agents on this computer: this conversation with another one (the default stays).
+            const current = ctx.settings.agent(tree.config).value;
+            const others = agentsHere(ctx.env)
+                .filter((a) => a.id !== current)
+                .map((a) => AGENTS.find((x) => x.id === a.id));
+            if (others.length)
+                items.push({
+                    key: "9",
+                    label: t("ui.menu.otheragent"),
+                    act: async () => {
+                        const i = others.length === 1 ? 0 : await ctx.choose(t("ui.setup.agent.pick"), others.map((a) => ({ label: a.name })), 0);
+                        if (i !== undefined)
+                            await run(["chat", "--agent", others[i].id]);
+                    },
+                });
+            if (stromAppState(ctx.settings) !== "no")
+                items.push({ key: "5", label: t("ui.menu.app"), act: async () => void (await run(["app"])) });
+        }
+        else {
+            // Several trees and none chosen: pick one first.
+            items.push({ key: "1", label: t("ui.menu.trees"), act: async () => pickTree(ctx, run, lang) });
+        }
+        items.push({ key: "6", label: t("ui.menu.settings"), act: async () => void (await run(["setup"])) }, {
+            key: "7",
+            label: t("ui.menu.doctor"),
+            act: async () => {
+                const code = await run(["doctor"]);
+                if (code !== 0 && (await ctx.confirm(t("ui.menu.fix"), true)))
+                    await run(["doctor", "--fix"]);
+                await pause(lang);
+            },
+        });
+        if (newer)
+            items.push({ key: "9", label: t("ui.menu.update", { version: newer }), act: async () => void (await run(["update"])) });
+        if (root)
+            items.push({ key: "8", label: known.length > 1 ? t("ui.menu.trees") : t("ui.menu.newtree"), act: async () => pickTree(ctx, run, lang) });
+        items.push({ key: "0", label: t("ui.menu.quit"), act: async () => true });
+        // Numbered in the order shown; 0 always quits.
+        let n = 0;
+        const i = await ctx.choose("", items.map((it) => ({ key: it.key === "0" ? "0" : String(++n), label: it.label })), 0);
+        if (i === undefined)
+            return;
+        const quit = await items[i].act();
+        if (quit === true) {
+            out(t("ui.menu.bye"));
+            return;
+        }
+    }
+}
+/** Choose another family tree, or create a new one (and start its research). */
+async function pickTree(ctx, run, lang) {
+    const known = ctx.knownTrees();
+    const options = [...known.map((k) => ({ label: `${k.name}  (${ctx.display(k.root)})` })), { label: ui(lang, "ui.trees.new") }];
+    const i = await ctx.choose(ui(lang, "ui.trees.pick"), options, 0);
+    if (i === undefined)
+        return;
+    if (i < known.length) {
+        await run(["trees", "use", known[i].root], true);
+        return;
+    }
+    const name = await ctx.ask(ui(lang, "ui.tree.name"), ui(lang, "ui.tree.default"));
+    const made = await createTree(ctx, run, lang, name);
+    if (!made)
+        return;
+    await run(["trees", "use", made], true);
+    await run(["chat"]);
+}

package/dist/cli/registry.js

@@ -0,0 +1,96 @@
+// The command registry: the single source of truth for every command.
+// Help, `strom commands --json`, `strom guide` and argument parsing are all
+// derived from these declarations.
+export const GROUPS = {
+    start: "Orientation",
+    research: "Trees and researches",
+    inputs: "Inputs (what the research starts from)",
+    tasks: "Tasks",
+    people: "People, families, facts",
+    sources: "Sources, archives, record sets, places",
+    analysis: "Searches, conflicts, hypotheses, lessons",
+    output: "Output (GEDCOM)",
+    history: "Checks and history",
+    setup: "Setup and environment",
+};
+export const GLOBAL_OPTIONS = [
+    { name: "tree", type: "string", value: "<dir|name>", description: "tree to work on (default: STROM_TREE, the tree you are in, or the only tree)" },
+    { name: "json", type: "boolean", description: "machine-readable output" },
+    { name: "limit", type: "string", value: "<n>", description: "max rows in listings (default 50)" },
+    { name: "page", type: "string", value: "<n>", description: "page of a listing" },
+    { name: "lang", type: "string", value: "<code>", description: "research language, e.g. cs, en, de" },
+    { name: "home", type: "string", value: "<dir>", description: "Strom home folder (default from config)" },
+    { name: "shared", type: "string", value: "<dir>", description: "shared data folder (media, catalog, tools)" },
+    { name: "trees", type: "string", value: "<dir>", description: "folder holding the trees" },
+    { name: "agent", type: "string", value: "<agent>", description: "AI agent: claude, codex, antigravity, opencode (default from config)" },
+    { name: "yes", type: "boolean", description: "accept suggested defaults, never ask" },
+    { name: "debug", type: "boolean", description: "show technical details on errors" },
+    { name: "version", type: "boolean", description: "print the version of strom" },
+    { name: "help", type: "boolean", short: "h", description: "help for a command" },
+];
+export const WRITE_OPTIONS = [
+    { name: "dry-run", type: "boolean", description: "show what would change, change nothing" },
+    { name: "reason", type: "string", value: "<text>", description: "why (required when changing or retracting facts)" },
+];
+const registry = [];
+export function register(...defs) {
+    for (const def of defs) {
+        if (registry.some((c) => c.path.join(" ") === def.path.join(" ")))
+            throw new Error(`duplicate command ${def.path.join(" ")}`);
+        registry.push(def);
+    }
+}
+export function commands() {
+    return registry;
+}
+export function optionsOf(def) {
+    return [...(def.options ?? []), ...(def.writes ? WRITE_OPTIONS : []), ...GLOBAL_OPTIONS];
+}
+/** Longest registered command path matching the leading words. */
+export function match(words) {
+    let best;
+    for (const def of registry) {
+        const n = def.path.length;
+        if (n > words.length)
+            continue;
+        if (n === 0 && words.length > 0)
+            continue; // the root command only matches no words
+        if (def.path.every((w, i) => words[i] === w) && (!best || n > best.used))
+            best = { def, used: n };
+    }
+    return best;
+}
+/** Command groups ("person") that have subcommands but no command of their own. */
+export function subcommandsOf(prefix) {
+    return registry.filter((c) => c.path.length > prefix.length && prefix.every((w, i) => c.path[i] === w));
+}
+export function usageLine(def) {
+    const args = (def.args ?? []).map((a) => {
+        const name = a.variadic ? `${a.name}...` : a.name;
+        return a.required ? `<${name}>` : `[${name}]`;
+    });
+    return ["strom", ...def.path, ...args, (def.options?.length || def.writes) ? "[options]" : ""].filter(Boolean).join(" ");
+}
+/** Catalog entry for `strom commands --json`: only what is there (empty fields are left out). */
+export function describe(def) {
+    const out = { command: def.path.join(" "), usage: usageLine(def), summary: def.summary, group: def.group };
+    if (def.description)
+        out.description = def.description;
+    if (def.writes)
+        out.writes = true;
+    if (def.tree)
+        out.needsTree = true;
+    if (def.args?.length)
+        out.args = def.args;
+    const opts = [...(def.options ?? []), ...(def.writes ? WRITE_OPTIONS : [])];
+    if (opts.length)
+        out.options = opts.map((o) => ({
+            name: `--${o.name}`,
+            ...(o.type === "boolean" ? { flag: true } : { value: o.value ?? "<value>" }),
+            ...(o.multiple ? { repeatable: true } : {}),
+            description: o.description,
+        }));
+    if (def.examples?.length)
+        out.examples = def.examples;
+    return out;
+}