@tiagojct/subsub 0.5.0

package/dist/init.js

@@ -0,0 +1,215 @@
+/**
+ * `subsub init`: set Sub-Sub up for a new user, or change the settings of an
+ * existing one. Press Enter to keep the value in brackets.
+ *
+ * Writes:
+ * - the settings file (~/.config/subsub/config.json): profile, name, language,
+ *   notes folder, models;
+ * - the server settings file (~/.config/zotero-local-mcp/env, or the one that
+ *   already exists): notes folder, tag list, contact email. Other lines stay;
+ * - in the notes folder: Inbox/, Systems/Zotero tags.md (a starter list) and
+ *   Systems/Zotero agent.md (note formats). Existing files are never replaced.
+ *
+ * Flags (for scripts and tests): --yes (take every default), --setup
+ * standard|fmup, --name, --about, --language, --notes, --profile, --tags
+ * health-sciences|health-informatics|any-field, --email, --models keep|later|opencode-go.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { configPath, expand, isProfile, loadConfig, parseEnvFile, PROFILES, readConfigFile, saveConfig } from "./config.js";
+import { PROFILE_SPECS } from "./profiles.js";
+const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+export const STARTER_TAGS = {
+    "health-sciences": "Health sciences: clinical areas, public health, methods and study designs",
+    "health-informatics": "Health informatics: information systems, data, AI, digital health",
+    "any-field": "Any field: methods and document types only; the librarian proposes topics from your library",
+};
+export const TESTED_MODELS = { librarian: "opencode-go/glm-5.3-flash", researcher: "opencode-go/mimo-v2.6-pro" };
+/** Set KEY=VALUE lines in an env file text; other lines and comments stay. */
+export function upsertEnv(text, values) {
+    const lines = text ? text.replace(/\n$/, "").split("\n") : [];
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined || value === "")
+            continue;
+        const i = lines.findIndex((l) => l.trim().startsWith(`${key}=`));
+        const line = `${key}=${value}`;
+        if (i >= 0)
+            lines[i] = line;
+        else
+            lines.push(line);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** True when pi's credentials (auth.json in the agent folder) name a provider that starts with prefix. */
+export function hasProvider(agentDir, prefix) {
+    try {
+        const data = JSON.parse(readFileSync(join(agentDir, "auth.json"), "utf8"));
+        return Object.keys(data ?? {}).some((k) => k.startsWith(prefix));
+    }
+    catch {
+        return false;
+    }
+}
+export async function zoteroReachable(fetchFn = fetch) {
+    try {
+        const res = await fetchFn("http://127.0.0.1:23119/api/", { signal: AbortSignal.timeout(2000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runInit(io, flags, env = process.env, deps = {}) {
+    const home = deps.home ?? homedir();
+    const configFile = configPath(env);
+    const existing = readConfigFile(configFile);
+    const current = loadConfig(env);
+    const envFile = current.envFile ?? expand(env.ZOTERO_MCP_ENV ?? join(home, ".config", "zotero-local-mcp", "env"));
+    const envValues = existsSync(envFile) ? parseEnvFile(envFile) : {};
+    const created = [];
+    io.say(existsSync(configFile) ? `Sub-Sub settings (${configFile}). Press Enter to keep the value in brackets.` : "Sub-Sub setup. Press Enter to take the value in brackets.");
+    const setup = await io.choose("Setup", [
+        { value: "standard", label: "Standard" },
+        { value: "fmup", label: "FMUP / U.Porto: health-sciences tags, Reader profile (the FMUP model service is coming soon)" },
+    ], flags.setup ?? existing.setup ?? "standard");
+    const fmup = setup === "fmup";
+    const userName = (await io.ask("Your name, for Sub-Sub's replies (Enter for none)", flags.name ?? existing.userName ?? "")).trim();
+    const about = (await io.ask('One line about you, e.g. "a master\'s student in health informatics" (optional)', flags.about ?? existing.about ?? "")).trim();
+    const language = (await io.ask("Language for replies and notes (a language, or auto for the language you write in)", flags.language ?? existing.language ?? "English")).trim() || "English";
+    const notes = expand((await io.ask("Notes folder (Markdown files; an Obsidian vault works)", flags.notes ?? current.vault ?? envValues.ZOTERO_VAULT ?? join(home, "Documents", "Sub-Sub"))).trim());
+    const profileDefault = flags.profile ?? existing.profile ?? (fmup ? "reader" : "scholar");
+    const profile = await io.choose("Profile (change it later with /profile)", PROFILES.map((p) => ({ value: p, label: `${PROFILE_SPECS[p].label}: ${PROFILE_SPECS[p].summary}` })), isProfile(profileDefault) ? profileDefault : "scholar");
+    const vocab = envValues.ZOTERO_VOCAB ? expand(envValues.ZOTERO_VOCAB) : join(notes, "Systems", "Zotero tags.md");
+    let tags = "keep";
+    if (existsSync(vocab)) {
+        io.say(`Tag list: keeping ${vocab}.`);
+    }
+    else {
+        tags = await io.choose("Starter tag list (edit it later in the notes folder)", Object.entries(STARTER_TAGS).map(([value, label]) => ({ value, label })), flags.tags ?? (fmup ? "health-sciences" : "any-field"));
+    }
+    const email = (await io.ask("Email for Unpaywall and Crossref, to find open-access PDFs (optional)", flags.email ?? envValues.ZOTERO_CONTACT_EMAIL ?? "")).trim();
+    const modelOptions = [
+        ...(existing.models ? [{ value: "keep", label: `Keep: ${JSON.stringify(existing.models)}` }] : []),
+        { value: "later", label: "Choose later in Sub-Sub (/login, then /model)" },
+        { value: "opencode-go", label: `OpenCode Go, tested: ${TESTED_MODELS.librarian} for the librarian, ${TESTED_MODELS.researcher} for the researcher` },
+    ];
+    const agentDir = env.SUBSUB_AGENT_DIR ? expand(env.SUBSUB_AGENT_DIR) : join(home, ".subsub", "agent");
+    const modelDefault = existing.models ? "keep" : hasProvider(agentDir, "opencode") ? "opencode-go" : "later";
+    const models = await io.choose("Models", modelOptions, flags.models ?? modelDefault);
+    // ---- write
+    for (const dir of [notes, join(notes, "Inbox"), join(notes, "Systems")]) {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+            created.push(dir);
+        }
+    }
+    if (tags !== "keep" && STARTER_TAGS[tags] && !existsSync(vocab)) {
+        mkdirSync(dirname(vocab), { recursive: true });
+        copyFileSync(join(TEMPLATES, "vocabularies", `${tags}.md`), vocab);
+        created.push(vocab);
+    }
+    const rules = join(notes, "Systems", "Zotero agent.md");
+    if (!existsSync(rules)) {
+        copyFileSync(join(TEMPLATES, "Zotero agent.md"), rules);
+        created.push(rules);
+    }
+    mkdirSync(dirname(envFile), { recursive: true });
+    const before = existsSync(envFile) ? readFileSync(envFile, "utf8") : "# Settings for the Sub-Sub Zotero servers (zotero-local-mcp). Written by subsub init.\n";
+    writeFileSync(envFile, upsertEnv(before, { ZOTERO_VAULT: notes, ZOTERO_VOCAB: vocab, ZOTERO_CONTACT_EMAIL: email || undefined }));
+    const patch = {
+        profile,
+        userName: userName || undefined,
+        about: about || undefined,
+        language,
+        setup: fmup ? "fmup" : undefined,
+        vault: notes,
+        envFile,
+    };
+    if (models === "later")
+        patch.models = {};
+    if (models === "opencode-go")
+        patch.models = TESTED_MODELS;
+    saveConfig(patch, env);
+    const zotero = await zoteroReachable(deps.fetch);
+    io.say("");
+    io.say(`Saved: ${configFile}`);
+    io.say(`Saved: ${envFile}`);
+    for (const c of created)
+        io.say(`Created: ${c}`);
+    io.say(zotero
+        ? "Zotero: reachable."
+        : "Zotero: not reachable. Start Zotero 10, then in Zotero open Settings > Advanced and turn on \"Allow other applications on this computer to communicate with Zotero\".");
+    if (fmup)
+        io.say("FMUP / U.Porto: the FMUP model service will come in a later version. Until then, choose a model provider with /login.");
+    io.say("Next: type subsub. In Sub-Sub, type /login to connect a model provider. To check the setup, type subsub doctor.");
+    return { configFile, envFile, notes, created, zotero };
+}
+export function parseFlags(args) {
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("--"))
+            continue;
+        const key = a.slice(2);
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            out[key] = next;
+            i++;
+        }
+        else
+            out[key] = "true";
+    }
+    return out;
+}
+function defaultsIO(say) {
+    return {
+        ask: async (_q, def) => def,
+        choose: async (_q, _o, def) => def,
+        say,
+    };
+}
+function terminalIO() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return {
+        async ask(q, def) {
+            const a = await rl.question(`${q}${def ? ` [${def}]` : ""}: `);
+            return a.trim() === "" ? def : a.trim();
+        },
+        async choose(q, options, def) {
+            console.log(`\n${q}`);
+            options.forEach((o, i) => console.log(`  ${i + 1}. ${o.label}${o.value === def ? "  (default)" : ""}`));
+            for (;;) {
+                const a = (await rl.question(`Number [${options.findIndex((o) => o.value === def) + 1}]: `)).trim();
+                if (a === "")
+                    return def;
+                const n = Number(a);
+                if (Number.isInteger(n) && n >= 1 && n <= options.length)
+                    return options[n - 1].value;
+                const byName = options.find((o) => o.value === a.toLowerCase());
+                if (byName)
+                    return byName.value;
+                console.log(`Type a number from 1 to ${options.length}.`);
+            }
+        },
+        say: (l) => console.log(l),
+        close: () => rl.close(),
+    };
+}
+export async function initMain(args, env = process.env) {
+    const flags = parseFlags(args);
+    const io = flags.yes || !process.stdin.isTTY ? defaultsIO((l) => console.log(l)) : terminalIO();
+    try {
+        await runInit(io, flags, env);
+        return 0;
+    }
+    catch (err) {
+        console.error(`Sub-Sub init: ${err.message}`);
+        return 1;
+    }
+    finally {
+        io.close?.();
+    }
+}

package/dist/look.js

@@ -0,0 +1,107 @@
+/**
+ * The look of the `subsub` command: banner, status line, quote, and the theme
+ * per mode (try-works for the librarian, Glauca for the researcher).
+ * Only used when Sub-Sub runs as its own command in the terminal UI.
+ */
+export const BANNER = [
+    "╔═╗╦ ╦╔╗    ╔═╗╦ ╦╔╗",
+    "╚═╗║ ║╠╩╗───╚═╗║ ║╠╩╗",
+    "╚═╝╚═╝╚═╝   ╚═╝╚═╝╚═╝",
+];
+/** Short public-domain lines from Moby-Dick and its Extracts. */
+export const QUOTES = [
+    ["And God created great whales.", "Genesis, in the Extracts"],
+    ["Leviathan maketh a path to shine after him; One would think the deep to be hoary.", "Job, in the Extracts"],
+    ["There go the ships; there is that Leviathan whom thou hast made to play therein.", "Psalms, in the Extracts"],
+    ["Now the Lord had prepared a great fish to swallow up Jonah.", "Jonah, in the Extracts"],
+    ["Very like a whale.", "Hamlet, in the Extracts"],
+    ["So fare thee well, poor devil of a Sub-Sub, whose commentator I am.", "Moby-Dick, Extracts"],
+    ["Give it up, Sub-Subs!", "Moby-Dick, Extracts"],
+    ["God keep me from ever completing anything.", "Moby-Dick, ch. 32"],
+    ["Call me Ishmael.", "Moby-Dick, ch. 1"],
+];
+export const MODE_THEMES = { librarian: "subsub-try-works", researcher: "subsub-glauca" };
+/** Light or dark terminal, judged from the text colour of the current theme (dark text means a light background). */
+export function schemeFromAnsi(fgAnsi, themeName) {
+    if (themeName?.endsWith("-light") || themeName === "light")
+        return "light";
+    if (themeName?.endsWith("-dark") || themeName === "dark")
+        return "dark";
+    const rgb = fgAnsi.match(/38;2;(\d+);(\d+);(\d+)/);
+    if (rgb) {
+        const [r, g, b] = rgb.slice(1).map(Number);
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b < 128 ? "light" : "dark";
+    }
+    const idx = fgAnsi.match(/38;5;(\d+)/);
+    if (idx) {
+        const n = Number(idx[1]);
+        // 232-255 grey ramp, 0/16 black: dark text on a light terminal
+        if (n === 0 || n === 16 || (n >= 232 && n <= 243))
+            return "light";
+    }
+    return "dark";
+}
+export function themeName(mode, scheme, map = MODE_THEMES) {
+    const base = map[mode];
+    return base ? `${base}-${scheme}` : undefined;
+}
+const plain = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, warn: (s) => s };
+function cut(s, width) {
+    return [...s].length > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;
+}
+export function libraryLine(st) {
+    if (st.zotero === "checking")
+        return { text: "Zotero: checking...", warn: false };
+    if (st.zotero === "down")
+        return { text: "Zotero is not running. Start it, then type /subsub.", warn: true };
+    const parts = [`${st.items ?? "?"} items`];
+    if (st.toReview)
+        parts.push(`${st.toReview} to review`);
+    return { text: `Zotero: ${parts.join(", ")}`, warn: false };
+}
+/** Header lines. Each line is cut to the width before it is coloured. */
+export function headerLines(opts) {
+    const p = opts.paint ?? plain;
+    const w = Math.max(10, opts.width);
+    const modeLabel = (opts.mode === "librarian" ? "Librarian" : "Researcher") + (opts.profile ? `, ${opts.profile}` : "");
+    const lib = libraryLine(opts.library);
+    if (w < BANNER[0].length + 2) {
+        return [p.mark(cut(`Sub-Sub ${opts.version}`, w)), p.text(cut(`${modeLabel} | ${opts.model}`, w)), (lib.warn ? p.warn : p.muted)(cut(lib.text, w))];
+    }
+    const out = ["", ...BANNER.map((l, i) => p.mark(l) + (i === 2 ? p.dim(cut(`  ${opts.version}`, w - l.length)) : "")), ""];
+    const status = `${modeLabel}  ${opts.model}`;
+    out.push(p.text(cut(status, w)) + (lib.warn ? p.warn : p.muted)(cut(`  |  ${lib.text}`, Math.max(0, w - status.length))));
+    if (opts.quote) {
+        const one = `"${opts.quote[0]}" (${opts.quote[1]})`;
+        if ([...one].length <= w)
+            out.push(p.dim(one));
+        else
+            out.push(p.dim(cut(`"${opts.quote[0]}"`, w)), p.dim(cut(`  (${opts.quote[1]})`, w)));
+    }
+    out.push(p.dim(cut("/researcher  /librarian  /profile  /history  /undo  |  / for all commands", w)), "");
+    return out;
+}
+/**
+ * Colour the "+ added" and "- removed" parts of a preview; the rest gets the
+ * base colour (pi draws dialog text in the accent colour otherwise).
+ */
+export function paintPreview(text, add, remove, base = (x) => x) {
+    const seg = /(^|: |; )([+-] [^;]+)/g;
+    return text
+        .split("\n")
+        .map((line) => {
+        let out = "";
+        let last = 0;
+        for (const m of line.matchAll(seg)) {
+            const start = (m.index ?? 0) + m[1].length;
+            if (start > last)
+                out += base(line.slice(last, start));
+            out += (m[2].startsWith("+") ? add : remove)(m[2]);
+            last = start + m[2].length;
+        }
+        if (last < line.length)
+            out += base(line.slice(last));
+        return out;
+    })
+        .join("\n");
+}

package/dist/paths.js

@@ -0,0 +1,86 @@
+/**
+ * Path gate for pi's write and edit tools.
+ *
+ * Paths are normalised the way pi's file tools read them (leading "@", "~/",
+ * file:// URLs), and symlinks are resolved through the nearest existing parent,
+ * so a link inside the vault that points elsewhere is judged by its target.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export function normalizeToolPath(raw, cwd) {
+    let p = String(raw ?? "").trim();
+    if (p.startsWith("@"))
+        p = p.slice(1);
+    if (p.startsWith("file://")) {
+        try {
+            p = fileURLToPath(p);
+        }
+        catch {
+            /* keep as is */
+        }
+    }
+    if (p === "~" || p.startsWith("~/"))
+        p = join(homedir(), p.slice(1));
+    return realish(resolve(cwd, p));
+}
+/** realpath of the nearest existing ancestor, plus the part that does not exist yet. */
+export function realish(abs) {
+    let head = abs;
+    const tail = [];
+    while (!existsSync(head)) {
+        const parent = dirname(head);
+        if (parent === head)
+            break;
+        tail.unshift(basename(head));
+        head = parent;
+    }
+    let real = head;
+    try {
+        real = realpathSync(head);
+    }
+    catch {
+        /* keep */
+    }
+    return tail.length ? join(real, ...tail) : real;
+}
+export function within(child, parent) {
+    if (!parent)
+        return false;
+    const rel = relative(parent, child);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+export function buildPolicy(opts) {
+    const home = realish(homedir());
+    const cwd = realish(opts.cwd);
+    const allowed = [];
+    if (opts.vault)
+        allowed.push(realish(opts.vault));
+    // The working folder counts only if it is a specific folder, not the home folder or above it.
+    if (cwd !== home && within(cwd, home) && !within(home, cwd))
+        allowed.push(cwd);
+    const protectedPaths = [
+        join(home, ".pi"),
+        join(home, ".subsub"),
+        join(home, ".config"),
+        join(home, ".ssh"),
+        join(home, ".zshrc"),
+        join(home, ".bashrc"),
+        realish(opts.serverDir),
+        realish(opts.packageDir),
+    ];
+    if (opts.vault) {
+        const v = realish(opts.vault);
+        protectedPaths.push(join(v, ".claude"), join(v, ".opencode"), join(v, ".obsidian"), join(v, "Systems", "Zotero agent.md"), join(v, "Systems", "Zotero tags.md"), join(v, "Systems", "Zotero librarian.md"), join(v, "Systems", "Zotero researcher.md"), join(v, "Systems", "Literature alerts.md"));
+    }
+    return { allowed, protectedPaths };
+}
+export function judgePath(target, policy) {
+    const hit = policy.protectedPaths.find((p) => within(target, p));
+    if (hit)
+        return { ok: false, why: `it changes a protected file or folder (${hit})` };
+    if (policy.allowed.some((a) => within(target, a)))
+        return { ok: true };
+    return { ok: false, why: "it is outside the vault and the working folder" };
+}

package/dist/preview.js

@@ -0,0 +1,94 @@
+/**
+ * Turn a dry-run result from the Zotero servers into a short text that the user
+ * reads in the approval dialog. Plain ASCII, at most about 20 lines.
+ */
+const MAX_LINES = 14;
+function s(v, n = 90) {
+    const t = typeof v === "string" ? v : JSON.stringify(v);
+    return t.length > n ? `${t.slice(0, n - 3)}...` : t;
+}
+function list(rows, total) {
+    const out = rows.slice(0, MAX_LINES);
+    const rest = (total ?? rows.length) - out.length;
+    if (rest > 0)
+        out.push(`... and ${rest} more`);
+    return out;
+}
+function describeChange(c) {
+    const parts = [];
+    if (Array.isArray(c.added) && c.added.length)
+        parts.push(`+ ${c.added.join(", ")}`);
+    if (Array.isArray(c.removed) && c.removed.length)
+        parts.push(`- ${c.removed.join(", ")}`);
+    for (const [k, v] of Object.entries(c)) {
+        if (["key", "item", "added", "removed", "tags_after"].includes(k))
+            continue;
+        if (v && typeof v === "object" && "after" in v) {
+            const b = v.before;
+            parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${s(v.after, 60)}`);
+        }
+    }
+    return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || "(change)"}`;
+}
+export function formatPreview(tool, preview) {
+    if (!preview || typeof preview !== "object")
+        return s(preview, 1500);
+    const p = preview;
+    const lines = [];
+    if (p.undoing && typeof p.undoing === "object") {
+        const u = p.undoing;
+        lines.push(`Undo ${u.op}: ${s(u.summary, 80)}`);
+    }
+    if (Array.isArray(p.already_applied) && p.already_applied.length) {
+        lines.push(`ALREADY APPLIED: ${p.already_applied.join(", ")}`);
+    }
+    const drift = p.changed_since_note;
+    if (drift && typeof drift === "object" && typeof drift.count === "number") {
+        lines.push(`${drift.count} item(s) changed after the note was written; the note overwrites them:`);
+        const items = Object.entries(drift.items ?? {}).map(([k, v]) => `  ${k} now: ${v.now?.join(", ") || "(none)"}`);
+        lines.push(...items.slice(0, 4));
+    }
+    if (typeof p.would_change === "number") {
+        lines.push(`${p.would_change} item(s) would change.`);
+        const changes = p.changes ?? [];
+        lines.push(...list(changes.map(describeChange), p.would_change));
+    }
+    if (Array.isArray(p.would_import)) {
+        lines.push(`${p.would_import.length} item(s) would be imported:`);
+        lines.push(...list(p.would_import.map((r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : "  (no abstract)"}`)));
+    }
+    if (Array.isArray(p.would_attach)) {
+        lines.push(`${p.would_attach.length} PDF(s) would be attached:`);
+        lines.push(...list(p.would_attach.map((r) => `${s(r.item, 60)}  [${r.host_type ?? "?"}, ${r.version ?? "?"}${r.license ? `, ${r.license}` : ""}]`)));
+    }
+    if (p.would_create && typeof p.would_create === "object") {
+        const w = p.would_create;
+        lines.push(`New collection: ${w.name}${w.parent ? ` (inside ${w.parent})` : ""}`);
+    }
+    if (tool.endsWith("attach_note") || tool.endsWith("create_note")) {
+        if (p.item || p.parent)
+            lines.push(`Note on: ${s(p.item ?? p.parent, 90)}`);
+        if (p.summary || p.note_preview)
+            lines.push(s(p.summary ?? p.note_preview, 600));
+        if (p.link)
+            lines.push(`Link: ${p.link}`);
+    }
+    const skipped = p.skipped;
+    if (skipped && typeof skipped === "object" && Object.keys(skipped).length) {
+        lines.push(`Skipped: ${Object.keys(skipped).length}`);
+        lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`)).slice(0, 5));
+    }
+    const errors = p.errors;
+    if (errors && typeof errors === "object" && Object.keys(errors).length) {
+        lines.push(`Errors: ${Object.keys(errors).length}`);
+        lines.push(...Object.entries(errors).slice(0, 5).map(([k, v]) => `  ${k}: ${s(v, 70)}`));
+    }
+    if (!lines.length)
+        lines.push(s(p, 1500));
+    return lines.join("\n");
+}
+export function describeArgs(input) {
+    return Object.entries(input)
+        .map(([k, v]) => `${k}: ${s(v, 120)}`)
+        .join("\n");
+}

package/dist/profiles.js

@@ -0,0 +1,79 @@
+/**
+ * Profiles: how much Sub-Sub does for the user. Named after the work, not the
+ * person: a professor new to a field can choose Reader, a student can choose
+ * Scholar. A profile is the user's own choice (/profile changes it), not a lock.
+ *
+ * - reader:  explains each step; reading notes are quotes with page numbers and
+ *            questions; no summaries or syntheses; no bulk library changes.
+ * - scholar: literature notes, syntheses, searches, alerts; the full librarian.
+ * - author:  scholar plus manuscript work: citation check, bibliography, comments
+ *            on the argument. Does not write the manuscript's paragraphs.
+ * - editor:  everything, including drafting text for a manuscript on request.
+ */
+const BULK_LIBRARY = ["rename_tags", "remove_tags", "remove_automatic_tags", "trash_items", "update_fields", "repair_metadata"].map((n) => `zotero_${n}`);
+const MANUSCRIPT = ["scholar_check_manuscript", "scholar_export_bibliography"];
+export const PROFILE_SPECS = {
+    reader: {
+        name: "reader",
+        label: "Reader",
+        summary: "explains each step; reading notes are quotes and questions; no summaries; no bulk library changes",
+        without: [...BULK_LIBRARY, ...MANUSCRIPT],
+        batch: 10,
+        rules: [
+            "Profile: Reader. {{User}} is learning to work with the literature and wants to do the reading and the writing.",
+            "- Before each step, say in one or two lines what you will do and why.",
+            "- A literature note is a reading note: the full reference, then direct quotes with page numbers (or section names), and under each quote one question for {{user}} to answer. Do not write summaries, syntheses, conclusions or paragraphs that {{user}} could hand in as their own text. When a prompt or the shared rules ask for a literature note or a synthesis, make a reading note instead and say so.",
+            "- For searches, list works with one line each on what they study, not on what they conclude.",
+            "- If {{user}} asks for a summary, a synthesis or text for an assignment, say that the Reader profile does not write these, and offer quotes and questions. {{User}} can change the profile with /profile.",
+            "- Librarian: at most 10 items per review note. Explain each proposed tag in the Reason column.",
+        ].join("\n"),
+    },
+    scholar: {
+        name: "scholar",
+        label: "Scholar",
+        summary: "literature notes, syntheses, searches and alerts; the full librarian",
+        without: MANUSCRIPT,
+        batch: 25,
+        rules: [
+            "Profile: Scholar.",
+            "- Write literature notes and syntheses from what you read, with a source for every claim.",
+            "- Do not draft text for {{user}}'s manuscripts, theses or assignments. If asked, say that the Author and Editor profiles help with manuscripts (/profile).",
+            "- Librarian: 25 items per review note.",
+        ].join("\n"),
+    },
+    author: {
+        name: "author",
+        label: "Author",
+        summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
+        without: [],
+        batch: 25,
+        rules: [
+            "Profile: Author.",
+            "- Write literature notes and syntheses from what you read, with a source for every claim.",
+            "- Help with {{user}}'s manuscripts: check citations against the library, export the bibliography, and comment on the argument, the structure and the evidence that is missing, with the sources that could support each point.",
+            "- Do not write the manuscript's paragraphs. Say what is missing and where the support is; {{user}} writes the text. The Editor profile drafts text (/profile).",
+            "- Librarian: 25 items per review note.",
+        ].join("\n"),
+    },
+    editor: {
+        name: "editor",
+        label: "Editor",
+        summary: "everything, including drafting manuscript text on request",
+        without: [],
+        batch: 25,
+        rules: [
+            "Profile: Editor. All tools.",
+            "- Write literature notes and syntheses from what you read, with a source for every claim.",
+            "- When {{user}} asks, draft text for a manuscript: cite library items as [@citekey], use only claims from sources you read, and mark drafted text clearly so that {{user}} can check it.",
+            "- Librarian: 25 items per review note unless {{user}} asks for more.",
+        ].join("\n"),
+    },
+};
+export function profileSpec(p) {
+    return PROFILE_SPECS[p];
+}
+export function profileList(current) {
+    return Object.values(PROFILE_SPECS)
+        .map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)
+        .join("\n");
+}

package/dist/prompt.js

@@ -0,0 +1,72 @@
+/**
+ * The Sub-Sub part of the system prompt: role text for the current mode, the
+ * profile rules, the shared Zotero rules from the notes folder, the vault
+ * conventions when pi runs inside the notes folder, and the language rule.
+ *
+ * Role and profile texts use placeholders: {{user}} / {{User}} (the user's name,
+ * or "the user"), {{about}} (one line about the user) and {{batch}}.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { who } from "./config.js";
+import { profileSpec } from "./profiles.js";
+const ROLE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "roles");
+function readIf(path) {
+    if (!path || !existsSync(path))
+        return undefined;
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function languageRule(language, user = "the user") {
+    if (language.toLowerCase() === "auto") {
+        return `Reply in the language ${user} writes in. Write notes in the language of ${user}'s other notes; if unsure, ask once. Keep quotations, titles of works and proper names in their original language.`;
+    }
+    return `Always reply in ${language}, even when ${user} writes in another language and even when the sources or notes you read are in another language. Write the notes you create in ${language} too, including their titles. Keep quotations, titles of works and proper names in their original language.`;
+}
+export function inside(child, parent) {
+    if (!parent)
+        return false;
+    const rel = relative(resolve(parent), resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function capital(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+export function fill(text, cfg) {
+    const user = who(cfg);
+    const about = cfg.about ? `${capital(user)} is ${cfg.about}.` : "";
+    return text
+        .replaceAll("{{User}}", capital(user))
+        .replaceAll("{{user}}", user)
+        .replaceAll("{{about}}", about)
+        .replaceAll("{{batch}}", String(profileSpec(cfg.profile).batch))
+        .replace(/[ \t]+\n/g, "\n");
+}
+export function roleText(mode, cfg) {
+    const raw = readIf(join(ROLE_DIR, `${mode}.md`)) ?? `You are the ${mode}.`;
+    return cfg ? fill(raw, cfg) : raw;
+}
+export function systemAddition(mode, cfg, cwd) {
+    const user = who(cfg);
+    const parts = [`# Sub-Sub: ${mode} mode`, roleText(mode, cfg)];
+    const shared = readIf(cfg.sharedRules);
+    if (shared) {
+        parts.push("# Shared Zotero rules (from the notes folder)", shared, `Sub-Sub note: in Sub-Sub you do not need a separate dry run before a change. Call the write tool with dry_run=false; Sub-Sub shows ${user} the server's preview and applies it only on approval. This replaces the dry-run steps above.`);
+    }
+    if (inside(cwd, cfg.vault)) {
+        for (const f of cfg.vaultContext) {
+            const t = readIf(f);
+            if (t)
+                parts.push(`# Vault conventions (${f})`, t);
+        }
+    }
+    // The profile and the language rule come last, so they win over the shared rules and the vault conventions.
+    parts.push("# Profile", fill(profileSpec(cfg.profile).rules, cfg));
+    parts.push("# Language", languageRule(cfg.language, user));
+    return parts.join("\n\n");
+}