strom-research 1.0.0

package/dist/cli/context.js

@@ -0,0 +1,311 @@
+// Per-invocation context: environment, settings, IO, and lazy access to the
+// tree. Asking the user happens only here, and only on a terminal.
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { Writable } from "node:stream";
+import { Settings } from "../core/config.js";
+import { displayPath, expandHome } from "../core/paths.js";
+import { NeedsConsentError, NeedsInputError, StromError, UsageError } from "../core/errors.js";
+import { Tree, findTreeUpwards, isTreeDir } from "../core/tree.js";
+import { readJsonIfExists } from "../core/json.js";
+import { foldText } from "../core/text.js";
+import { currentSession } from "../core/session.js";
+import { isAgent } from "../core/which.js";
+import { systemDialog } from "../core/dialog.js";
+import { ui } from "./ui.js";
+export class Context {
+    env;
+    cwd;
+    io;
+    settings;
+    json;
+    yes;
+    treeFlag;
+    limit;
+    page;
+    dryRun = false;
+    opened;
+    constructor(opts) {
+        this.env = opts.env;
+        this.cwd = opts.cwd;
+        this.io = opts.io;
+        this.settings = new Settings(opts.env, opts.flags);
+        this.json = opts.json;
+        this.yes = opts.yes;
+        this.treeFlag = opts.tree;
+        this.limit = opts.limit ?? 50;
+        this.page = opts.page ?? 1;
+    }
+    /** A context from parsed command-line values (global options and settings flags). */
+    static fromOptions(o) {
+        const v = o.values;
+        const str = (k) => (typeof v[k] === "string" ? v[k] : undefined);
+        const positive = (k) => {
+            const raw = str(k);
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n < 1)
+                throw new UsageError(`--${k} must be a positive number`);
+            return n;
+        };
+        return new Context({
+            env: o.env,
+            cwd: o.cwd,
+            io: o.io,
+            flags: {
+                home: str("home"),
+                shared: str("shared"),
+                trees: str("trees"),
+                lang: str("lang"),
+                agent: str("agent"),
+                model: str("model"),
+                budget: str("budget"),
+                minutes: str("minutes"),
+            },
+            json: o.json,
+            yes: Boolean(v.yes),
+            tree: str("tree"),
+            limit: positive("limit"),
+            page: positive("page"),
+        });
+    }
+    /** Can we ask the user a question right now? */
+    get interactive() {
+        return (this.io.tty || this.io.answers !== undefined) && !this.yes && !this.json && this.env.STROM_NONINTERACTIVE !== "1";
+    }
+    async ask(question, suggested) {
+        const prompt = suggested ? `${question} [${suggested}] ` : `${question} `;
+        let answer;
+        if (this.io.answers) {
+            this.io.stdout(prompt + "\n");
+            answer = this.io.answers.shift() ?? "";
+        }
+        else {
+            const rl = readline.createInterface({ input: this.io.stdin ?? process.stdin, output: process.stdout });
+            try {
+                answer = await rl.question(prompt);
+            }
+            finally {
+                rl.close();
+            }
+        }
+        answer = answer.trim();
+        return answer === "" ? (suggested ?? "") : answer;
+    }
+    /** A question whose answer is not shown as it is typed (a password): kept as typed, spaces too. */
+    async askSecret(question) {
+        if (this.io.answers) {
+            this.io.stdout(`${question} \n`);
+            return this.io.answers.shift() ?? "";
+        }
+        let muted = false;
+        const quiet = new Writable({
+            write(chunk, encoding, done) {
+                if (!muted)
+                    process.stdout.write(chunk, encoding);
+                done();
+            },
+        });
+        const rl = readline.createInterface({ input: this.io.stdin ?? process.stdin, output: quiet, terminal: true });
+        try {
+            const answer = rl.question(`${question} `);
+            muted = true;
+            return (await answer).replace(/[\r\n]+$/, "");
+        }
+        finally {
+            rl.close();
+            process.stdout.write("\n");
+        }
+    }
+    /** The language of the person using strom: the tree's (research language), else theirs. */
+    uiLang() {
+        let tree;
+        try {
+            const root = this.locateTree();
+            if (root)
+                tree = readJsonIfExists(path.join(root, "strom.json"));
+        }
+        catch {
+            // no tree to say
+        }
+        return this.settings.lang(tree).value;
+    }
+    /**
+     * A consent is the user's. In their own terminal they gave it by running the
+     * command. Anywhere else — an agent's session, the app — the person at the
+     * screen is asked in a window of the system, which the agent can neither see
+     * nor click. Without a window (no desktop, a run nobody watches) it fails:
+     * the user runs the command themselves. `says` is the question in the
+     * user's language — all the window shows, so it holds any warning too.
+     * `window: false` for what needs the user's terminal (typing a password).
+     */
+    requireHuman(question, set, key, says, opts = {}) {
+        const agent = isAgent(this.env);
+        if (this.interactive && !agent)
+            return "terminal";
+        if (this.env.STROM_NONINTERACTIVE !== "1" && opts.window !== false) {
+            const lang = this.uiLang();
+            const text = { title: ui(lang, "ui.dialog.title"), question: says ?? question, yes: ui(lang, "ui.dialog.yes"), no: ui(lang, "ui.dialog.no") };
+            const answer = this.io.dialog ? this.io.dialog(text) : systemDialog(text, this.env);
+            if (answer === true)
+                return "window";
+            if (answer === false)
+                throw new StromError(ui(lang, "ui.dialog.refused"), { hint: `the user said no to: ${question} — do not ask again unless they want to` });
+        }
+        throw new NeedsConsentError([{ key, kind: "consent", question: `${question}${agent ? " (an agent cannot answer this)" : ""}`, set }]);
+    }
+    /**
+     * One of numbered options (1…n, or keys of their own like "0"); Enter takes
+     * the suggested one. Asks again on anything else. Undefined when a test ran
+     * out of answers.
+     */
+    async choose(question, options, suggested) {
+        const keys = options.map((o, i) => o.key ?? String(i + 1));
+        for (;;) {
+            this.io.stdout(`\n${question ? `${question}\n` : ""}${options.map((o, i) => `  ${keys[i].padStart(2)}  ${o.label}`).join("\n")}\n`);
+            if (this.io.answers && this.io.answers.length === 0)
+                return undefined;
+            const a = await this.ask(`${ui(this.uiLang(), "ui.choose")}`, keys[suggested]);
+            const i = keys.indexOf(a.trim());
+            if (i >= 0)
+                return i;
+            this.io.stdout(ui(this.uiLang(), "ui.bad.choice") + "\n");
+        }
+    }
+    async confirm(question, suggested = true) {
+        const lang = this.uiLang();
+        const [yes, no] = [ui(lang, "ui.yes"), ui(lang, "ui.no")];
+        const a = (await this.ask(`${question} (${yes}/${no})`, suggested ? yes : no)).toLowerCase();
+        return [yes, "y", "yes", "a", "ano", "j", "ja", "t", "tak", "o", "oui", "s", "si"].includes(a);
+    }
+    display(p) {
+        return displayPath(p, this.env);
+    }
+    resolvePath(p) {
+        return path.resolve(this.cwd, expandHome(p, this.env));
+    }
+    /** The Strom home; asks (TTY) or fails with needs-input. */
+    async requireHome() {
+        const home = this.settings.home();
+        if (home)
+            return home.value;
+        const suggested = this.settings.suggestedHome();
+        if (this.yes)
+            return this.saveHome(suggested);
+        if (!this.interactive)
+            throw new NeedsInputError([
+                {
+                    key: "home",
+                    kind: "config",
+                    question: "Where should Strom keep the research (trees and shared data)?",
+                    default: this.display(suggested),
+                    scopes: ["user"],
+                    set: `strom setup --home "${this.display(suggested)}" --yes`,
+                },
+            ]);
+        const answer = await this.ask("Where should Strom keep your research?", this.display(suggested));
+        return this.saveHome(this.resolvePath(answer));
+    }
+    saveHome(dir) {
+        this.settings.config.home = dir;
+        this.settings.save();
+        return dir;
+    }
+    treesDir() {
+        return this.settings.trees()?.value;
+    }
+    /** All trees Strom knows about: folders in the trees dir plus remembered ones. */
+    knownTrees() {
+        const roots = new Set();
+        const dir = this.treesDir();
+        if (dir && fs.existsSync(dir))
+            for (const name of fs.readdirSync(dir)) {
+                const root = path.join(dir, name);
+                if (isTreeDir(root))
+                    roots.add(root);
+            }
+        for (const extra of this.settings.config.extraTrees ?? [])
+            if (isTreeDir(extra))
+                roots.add(extra);
+        const out = [];
+        for (const root of [...roots].sort()) {
+            const cfg = readJsonIfExists(path.join(root, "strom.json"));
+            if (cfg)
+                out.push({ name: cfg.name, root, lang: cfg.lang });
+        }
+        return out;
+    }
+    /** Locate the tree: --tree > STROM_TREE > current folder upwards > `strom trees use` > the only known tree. */
+    locateTree() {
+        const ref = this.treeFlag ?? this.env.STROM_TREE;
+        if (ref) {
+            const asPath = this.resolvePath(ref);
+            if (isTreeDir(asPath))
+                return asPath;
+            const key = foldText(ref);
+            const hits = this.knownTrees().filter((t) => foldText(t.name) === key || foldText(path.basename(t.root)) === key);
+            if (hits.length === 1)
+                return hits[0].root;
+            if (hits.length > 1)
+                throw new UsageError(`tree name "${ref}" is ambiguous`, { hint: "pass the folder path: --tree <dir>" });
+            throw new UsageError(`no tree "${ref}"`, { hint: "strom trees" });
+        }
+        const up = findTreeUpwards(this.cwd);
+        if (up)
+            return up;
+        const current = this.settings.config.currentTree;
+        if (current && isTreeDir(current))
+            return current;
+        const known = this.knownTrees();
+        if (known.length === 1)
+            return known[0].root;
+        return undefined;
+    }
+    tree() {
+        if (this.opened)
+            return this.opened;
+        const root = this.locateTree();
+        if (!root) {
+            const known = this.knownTrees();
+            if (known.length === 0)
+                throw new StromError("no tree yet", { hint: 'create one: strom init "<tree name>"' });
+            throw new UsageError("which tree? there are several", {
+                hint: `pass --tree <name>: ${known.map((t) => `"${t.name}"`).join(", ")}`,
+            });
+        }
+        this.opened = Tree.open(root, this.env);
+        this.opened.dryRun = this.dryRun;
+        // A language passed from outside (--lang, STROM_LANG — e.g. by the Strom
+        // app) applies to this invocation; the tree keeps its own.
+        const lang = this.settings.lang(this.opened.config);
+        if (lang.source === "flag" || lang.source === "env")
+            this.opened.langOverride = lang.value;
+        // Inside an open session every write is logged under the session's ID;
+        // an agent writing outside a session is logged as "agent", never as the user.
+        const session = currentSession(this.opened, this.env);
+        if (session)
+            this.opened.actor = session.id;
+        else if (isAgent(this.env))
+            this.opened.actor = "agent";
+        return this.opened;
+    }
+    /** The tree if a command already opened it. */
+    current() {
+        return this.opened;
+    }
+    /** Use a tree created during this command (e.g. by `init`). */
+    adopt(tree) {
+        tree.dryRun = this.dryRun;
+        this.opened = tree;
+    }
+    hasTree() {
+        try {
+            return this.locateTree() !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/cli/execute.js

@@ -0,0 +1,154 @@
+// Finding a command, parsing its options and checking its arguments — shared
+// by the CLI entry and `strom batch`. Mistakes get a short error with a
+// suggestion, never a wall of help: every extra line costs an agent tokens.
+import { parseArgs } from "node:util";
+import { UsageError } from "../core/errors.js";
+import { GLOBAL_OPTIONS, commands, match, optionsOf, subcommandsOf } from "./registry.js";
+const VALUE_GLOBALS = new Set(GLOBAL_OPTIONS.filter((o) => o.type === "string").map((o) => `--${o.name}`));
+/** Split argv into the command words and the remaining arguments. */
+export function splitCommand(argv) {
+    const words = [];
+    const rest = [];
+    let collecting = true;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--") {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        if (tok.startsWith("-")) {
+            rest.push(tok);
+            if (VALUE_GLOBALS.has(tok) && i + 1 < argv.length)
+                rest.push(argv[++i]);
+            continue;
+        }
+        if (collecting) {
+            const candidate = [...words, tok];
+            const extends_ = match(candidate)?.used === candidate.length || subcommandsOf(candidate).length > 0;
+            if (extends_) {
+                words.push(tok);
+                continue;
+            }
+            collecting = false;
+        }
+        rest.push(tok);
+    }
+    return { words, rest };
+}
+/** Edit distance where swapping two neighbouring letters is one typo ("bron" → "born"). */
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    return d[a.length][b.length];
+}
+/** The closest candidates to `input` (a prefix, or a few typos), best first — only the best ones. */
+export function suggest(input, candidates) {
+    const q = input.toLowerCase();
+    const scored = candidates
+        .map((c) => ({ c, d: c.startsWith(q) || q.startsWith(c) ? 0.5 : distance(q, c.toLowerCase()) }))
+        .filter((x) => x.d <= Math.max(2, Math.floor(q.length / 3)))
+        .sort((a, b) => a.d - b.d || a.c.length - b.c.length);
+    const best = scored[0]?.d;
+    return [...new Set(scored.filter((x) => x.d <= (best ?? 0) + 0.5).map((x) => x.c))].slice(0, 3);
+}
+/** The command named by argv, or a short error with suggestions. */
+export function resolveCommand(argv) {
+    const { words, rest } = splitCommand(argv);
+    const found = match(words);
+    const leftover = found ? words.slice(found.used) : words;
+    // Words that are not options — the values of global options (--lang en) are no stray words.
+    const extra = rest.filter((r, i) => !r.startsWith("-") && !VALUE_GLOBALS.has(rest[i - 1] ?? ""));
+    if (found && leftover.length === 0) {
+        if (found.def.path.length === 0 && extra.length && rest[0] !== "--")
+            throw unknownCommand(extra.slice(0, 2));
+        return { def: found.def, rest };
+    }
+    // A group ("person") with a wrong or missing subcommand.
+    const group = found ? [...found.def.path, ...leftover] : words;
+    if (group.length && subcommandsOf(group).length) {
+        if (!extra.length)
+            throw new GroupOnly(group);
+        throw unknownCommand([...group, extra[0]]);
+    }
+    throw unknownCommand([...words, ...extra].slice(0, Math.max(words.length + 1, 2)));
+}
+/** Signal: a group name alone — the caller prints the group's short help. */
+export class GroupOnly extends Error {
+    group;
+    constructor(group) {
+        super(`strom ${group.join(" ")} <command>`);
+        this.group = group;
+    }
+}
+function unknownCommand(words) {
+    const typed = words.join(" ");
+    const all = commands().filter((c) => c.path.length > 0).map((c) => c.path.join(" "));
+    // A known group narrows the choice ("person ad" → "person add", not "lesson add").
+    const inGroup = all.filter((c) => c.startsWith(`${words[0]} `));
+    const same = (inGroup.length ? inGroup : all).filter((c) => c.split(" ").length === words.length);
+    const hits = suggest(typed, same.length ? same : all);
+    const more = hits.length ? hits : suggest(words[0] ?? "", [...new Set(all.map((c) => c.split(" ")[0]))]);
+    return new UsageError(`unknown command "strom ${typed}"`, {
+        hint: more.length ? `did you mean: ${more.map((c) => `strom ${c}`).join(" · ")}` : "strom help   (all commands)",
+    });
+}
+/** Parse options strictly; Node's messages are replaced by short ones with suggestions. */
+export function parseOptions(def, rest) {
+    const defs = optionsOf(def);
+    const options = {};
+    for (const o of defs) {
+        options[o.name] = { type: o.type };
+        if (o.short)
+            options[o.name].short = o.short;
+        if (o.multiple)
+            options[o.name].multiple = true;
+    }
+    const cmd = `strom ${def.path.join(" ")}`.trim();
+    try {
+        const r = parseArgs({ args: rest, options, allowPositionals: true, strict: true });
+        return { values: r.values, positionals: r.positionals };
+    }
+    catch (err) {
+        const e = err;
+        const opt = /'(-{1,2}[^' =]+)/.exec(e.message)?.[1] ?? "";
+        const own = [...(def.options ?? []), ...(def.writes ? optionsOf(def).filter((o) => o.name === "dry-run" || o.name === "reason") : [])].map((o) => `--${o.name}`);
+        if (e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            // "strom brief --task T0003": the task is an argument there, not an option
+            const arg = def.args?.find((a) => `--${a.name}` === opt);
+            if (arg)
+                throw new UsageError(`${opt.slice(2)} is an argument of ${cmd}, not an option`, { hint: `strom ${def.path.join(" ")} <${arg.name}>` });
+            const near = suggest(opt, optionsOf(def).map((o) => `--${o.name}`));
+            throw new UsageError(`unknown option ${opt} for ${cmd}`, {
+                hint: near.length ? `did you mean ${near.join(" or ")}?` : `${own.length ? `options: ${own.join(" ")} · ` : ""}strom help ${def.path.join(" ")}`,
+            });
+        }
+        if (e.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+            const o = defs.find((d) => `--${d.name}` === opt);
+            throw new UsageError(o?.type === "boolean" ? `${opt} takes no value` : `${opt} needs a value${o?.value ? ` ${o.value}` : ""}`, { hint: `strom help ${def.path.join(" ")}` });
+        }
+        throw new UsageError(e.message.split("\n")[0] ?? "invalid arguments", { hint: `strom help ${def.path.join(" ")}` });
+    }
+}
+/** Required and surplus positional arguments. */
+export function checkArgs(def, args) {
+    const declared = def.args ?? [];
+    const required = declared.filter((a) => a.required);
+    if (args.length < required.length) {
+        const missing = required[args.length];
+        throw new UsageError(`missing <${missing.name}>: ${missing.description}`, { hint: `strom help ${def.path.join(" ")}` });
+    }
+    if (!declared.some((a) => a.variadic) && args.length > declared.length)
+        throw new UsageError(`unexpected argument "${args[declared.length]}"`, { hint: `strom help ${def.path.join(" ")} — quote values with spaces` });
+}
+/** Split off everything after a bare "--" (passed through to another program). */
+export function splitPassthrough(rest) {
+    const i = rest.indexOf("--");
+    return i < 0 ? { rest, passthrough: [] } : { rest: rest.slice(0, i), passthrough: rest.slice(i + 1) };
+}

package/dist/cli/fixes.js

@@ -0,0 +1,78 @@
+// Getting what strom needs, with the user's yes — shared by the setup wizard
+// and strom doctor --fix. A person in their own terminal is asked there; the
+// user of an agent is asked in a window of the system (the agent can neither
+// see nor click it); no window: the user runs strom doctor --fix themselves.
+import { ui } from "./ui.js";
+import { isAgent } from "../core/which.js";
+import { gitVersion, resetCache } from "../core/git.js";
+import { gitWay, installOwnGit, linuxGitCommand, MINGIT } from "../core/deps.js";
+import { claudeInstaller, runInstaller } from "../core/install.js";
+import { agentsHere } from "../core/apps.js";
+import { researchUrl } from "../core/stromapp.js";
+import { openForUser } from "../core/open.js";
+import { NeedsConsentError, StromError } from "../core/errors.js";
+/** Is the person answering here, in this terminal? */
+function personHere(ctx) {
+    return ctx.interactive && !isAgent(ctx.env);
+}
+/** The user's yes to installing something: here, or in a window. False when they say no. */
+async function yes(ctx, question, key) {
+    if (personHere(ctx))
+        return ctx.confirm(question, true);
+    try {
+        ctx.requireHuman(`install ${key}`, "strom doctor --fix", `install.${key}`, question);
+        return true;
+    }
+    catch (e) {
+        if (e instanceof StromError && !(e instanceof NeedsConsentError))
+            return false; // they said no
+        throw e;
+    }
+}
+/** Git: strom's own on Windows, Apple's tools on macOS, the package manager's on Linux. True when git works after it. */
+export async function fixGit(ctx, out) {
+    const lang = ctx.uiLang();
+    const way = gitWay();
+    if (way === "command") {
+        out(ui(lang, "ui.setup.git.manual", { command: linuxGitCommand() }));
+        return false;
+    }
+    if (!(await yes(ctx, ui(lang, way === "download" ? "ui.fix.git.download" : "ui.fix.git.window", { mb: MINGIT.mb }), "git")))
+        return false;
+    if (way === "download") {
+        out(ui(lang, "ui.fix.git.downloading"));
+        const ok = await installOwnGit(ctx.env, (why) => out(ui(lang, "ui.fix.failed", { detail: why })));
+        if (ok)
+            out(ui(lang, "ui.setup.git.ok", { version: gitVersion(ctx.env) ?? "" }));
+        return ok;
+    }
+    // macOS: Apple's window installs the command line tools; it takes a few minutes.
+    runInstaller({ command: "xcode-select", args: ["--install"] }, ctx.env);
+    if (!personHere(ctx)) {
+        out(ui(lang, "ui.fix.git.inwindow"));
+        return false;
+    }
+    await ctx.ask(ui(lang, "ui.setup.git.wait"));
+    resetCache();
+    const v = gitVersion(ctx.env);
+    if (v)
+        out(ui(lang, "ui.setup.git.ok", { version: v }));
+    return Boolean(v);
+}
+/** No agent on this computer: install Claude Code, show the page about agents, or later. Only a person here decides. */
+export async function offerAgent(ctx, out) {
+    const lang = ctx.uiLang();
+    out(ui(lang, "ui.setup.agent.none"));
+    if (!personHere(ctx)) {
+        out(ui(lang, "ui.setup.agent.manual", { url: researchUrl(lang, "agents") }));
+        return;
+    }
+    const how = await ctx.choose(ui(lang, "ui.choose"), [{ label: ui(lang, "ui.setup.agent.install") }, { label: ui(lang, "ui.setup.agent.guide") }, { label: ui(lang, "ui.setup.agent.later") }], 0);
+    if (how === 0) {
+        runInstaller(claudeInstaller(), ctx.env);
+        if (agentsHere(ctx.env).some((a) => a.id === "claude"))
+            out(ui(lang, "ui.setup.agent.login"));
+    }
+    else if (how === 1)
+        openForUser(researchUrl(lang, "agents"), ctx.env);
+}

package/dist/cli/format.js

@@ -0,0 +1,53 @@
+// Compact, token-efficient text output: aligned columns, one row per record,
+// no box drawing, IDs first.
+export function table(rows, opts = {}) {
+    const all = opts.header ? [opts.header, ...rows] : rows;
+    if (all.length === 0)
+        return "";
+    const gap = " ".repeat(opts.gap ?? 2);
+    const widths = [];
+    for (const row of all)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, [...cell].length)));
+    return all
+        .map((row) => row
+        .map((cell, i) => (i === row.length - 1 ? cell : cell + " ".repeat((widths[i] ?? 0) - [...cell].length)))
+        .join(gap)
+        .trimEnd())
+        .join("\n");
+}
+export function paginate(items, limit, page) {
+    const pages = Math.max(1, Math.ceil(items.length / limit));
+    const p = Math.min(Math.max(1, page), pages);
+    return { items: items.slice((p - 1) * limit, p * limit), total: items.length, page: p, pages, limit };
+}
+/** Footer telling the caller how to see more. */
+export function moreLine(page, command) {
+    if (page.page >= page.pages)
+        return "";
+    const left = page.total - page.page * page.limit;
+    return `… ${left} more: ${command} --page ${page.page + 1}`;
+}
+export function truncate(text, max) {
+    const one = text.replace(/\s+/g, " ").trim();
+    return [...one].length <= max ? one : [...one].slice(0, max - 1).join("") + "…";
+}
+export function lines(...parts) {
+    return parts.filter((p) => typeof p === "string").join("\n");
+}
+/** Runs of numbers as ranges: [1, 2, 3, 7] → "1–3, 7". */
+export function runs(nums) {
+    const s = [...new Set(nums)].sort((a, b) => a - b);
+    const out = [];
+    for (let i = 0; i < s.length;) {
+        let j = i;
+        while (j + 1 < s.length && s[j + 1] === s[j] + 1)
+            j++;
+        out.push(i === j ? `${s[i]}` : `${s[i]}–${s[j]}`);
+        i = j + 1;
+    }
+    return out.join(", ");
+}
+/** An argument as it is typed in a shell: quoted when it holds spaces or special characters. */
+export function shellArg(arg) {
+    return /^[\p{L}\p{M}\p{N}._\/:@+-]+$/u.test(arg) ? arg : `"${arg.replace(/["\\$`]/g, "\\$&")}"`;
+}

package/dist/cli/help.js

@@ -0,0 +1,59 @@
+// Help text generated from the registry. Short by design: examples first,
+// then arguments and options.
+import { GROUPS, GLOBAL_OPTIONS, WRITE_OPTIONS, commands, match, subcommandsOf, usageLine } from "./registry.js";
+import { table } from "./format.js";
+import { suggest } from "./execute.js";
+function optionRows(opts) {
+    return opts.map((o) => [`--${o.name}${o.value ? ` ${o.value}` : ""}${o.multiple ? " (repeatable)" : ""}`, o.description]);
+}
+export function commandHelp(def) {
+    const out = [usageLine(def), "", def.summary];
+    if (def.description)
+        out.push("", def.description);
+    if (def.examples?.length)
+        out.push("", "Examples:", ...def.examples.map((e) => `  ${e}`));
+    if (def.args?.length)
+        out.push("", "Arguments:", table(def.args.map((a) => [`  ${a.name}`, a.description])));
+    const own = [...(def.options ?? []), ...(def.writes ? WRITE_OPTIONS : [])];
+    if (own.length)
+        out.push("", "Options:", table(optionRows(own).map(([a, b]) => [`  ${a}`, b ?? ""])));
+    out.push("", "Global options: --tree --json --limit --page --lang --yes --debug   (all: strom help)");
+    return out.join("\n");
+}
+export function groupHelp(prefix) {
+    const subs = subcommandsOf(prefix);
+    return [
+        `strom ${prefix.join(" ")} <command>`,
+        "",
+        table(subs.map((c) => [`  ${c.path.join(" ")}`, c.summary])),
+        "",
+        `Details: strom help ${prefix.join(" ")} <command>`,
+    ].join("\n");
+}
+/** Overview of all commands, grouped. */
+export function overview() {
+    const out = ["strom <command> [options]      (strom guide — how to do research with strom)", ""];
+    for (const [group, title] of Object.entries(GROUPS)) {
+        const defs = commands().filter((c) => c.group === group && c.path.length > 0);
+        if (defs.length === 0)
+            continue;
+        out.push(`${title}:`, table(defs.map((c) => [`  ${c.path.join(" ")}`, c.summary])), "");
+    }
+    out.push("Global options:", table(optionRows(GLOBAL_OPTIONS).map(([a, b]) => [`  ${a}`, b ?? ""])));
+    out.push("", "Help for one command: strom help <command>   ·   machine-readable catalog: strom commands --json");
+    return out.join("\n");
+}
+export function helpFor(input) {
+    // "strom help 'research new'" — one quoted argument with several words.
+    const words = input.flatMap((w) => w.trim().split(/\s+/)).filter(Boolean);
+    if (words.length === 0)
+        return overview();
+    const found = match(words);
+    if (found && found.used === words.length)
+        return commandHelp(found.def);
+    if (subcommandsOf(words).length > 0)
+        return groupHelp(words);
+    const all = commands().filter((c) => c.path.length > 0).map((c) => c.path.join(" "));
+    const near = suggest(words.join(" "), all.filter((c) => c.split(" ").length === words.length));
+    return `unknown command "${words.join(" ")}"${near.length ? ` — did you mean: ${near.map((c) => `strom help ${c}`).join(" · ")}` : ""}\nall commands: strom help`;
+}