@tiagojct/subsub 0.5.0

package/dist/cli.js

@@ -0,0 +1,209 @@
+/**
+ * The `subsub` command: pi, set up as Sub-Sub.
+ *
+ * - Own pi folder (~/.subsub/agent, or SUBSUB_AGENT_DIR): settings, sessions
+ *   and packages are separate from plain pi.
+ * - The Sub-Sub package is declared in that folder's settings.json, so pi
+ *   loads the extension and the prompt templates in the normal way.
+ * - Credentials: if pi already has an auth.json and Sub-Sub has none, Sub-Sub
+ *   links to it, so one /login serves both.
+ * - Folder: started from the home folder, Sub-Sub moves to the vault.
+ *   `--here` keeps the current folder.
+ * - `subsub review preview|apply NOTE...` runs zotero-review (tag review notes,
+ *   several at a time) with Sub-Sub's server folder and settings.
+ * - `subsub init` sets Sub-Sub up; `subsub doctor` checks the setup.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { expand, loadConfig, serverCommand } from "./config.js";
+export const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export function packageVersion(dir = PACKAGE_DIR) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function agentDirFor(env, home = homedir()) {
+    return env.SUBSUB_AGENT_DIR ? expand(env.SUBSUB_AGENT_DIR) : join(home, ".subsub", "agent");
+}
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+function sourceOf(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry && typeof entry === "object" && typeof entry.source === "string") {
+        return entry.source;
+    }
+    return undefined;
+}
+/**
+ * Make sure settings.json in the agent folder declares the Sub-Sub package.
+ * Other settings are kept. Returns what happened, for tests and messages.
+ */
+export function ensureSettings(agentDir, packageDir = PACKAGE_DIR) {
+    mkdirSync(agentDir, { recursive: true });
+    const file = join(agentDir, "settings.json");
+    let settings = {};
+    let existed = false;
+    if (existsSync(file)) {
+        existed = true;
+        try {
+            settings = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            return "unreadable";
+        }
+    }
+    const packages = Array.isArray(settings.packages) ? [...settings.packages] : [];
+    const want = real(packageDir);
+    const has = packages.some((p) => {
+        const src = sourceOf(p);
+        return src !== undefined && real(resolve(agentDir, expand(src))) === want;
+    });
+    // Sub-Sub draws its own header; pi's list of loaded resources is noise here. Set once, so it can be changed.
+    const quiet = settings.quietStartup === undefined;
+    if (has && !quiet)
+        return "present";
+    if (!has)
+        packages.push(want);
+    settings.packages = packages;
+    if (quiet)
+        settings.quietStartup = true;
+    writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+    return existed ? "added" : "created";
+}
+function isEmptyAuth(file) {
+    try {
+        const data = JSON.parse(readFileSync(file, "utf8"));
+        return data && typeof data === "object" && Object.keys(data).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Link Sub-Sub's auth.json to pi's, when pi has one and Sub-Sub has none. */
+export function shareAuth(agentDir, piAgentDir) {
+    const mine = join(agentDir, "auth.json");
+    const theirs = join(piAgentDir, "auth.json");
+    if (!existsSync(theirs))
+        return false;
+    try {
+        const st = lstatSync(mine);
+        // pi writes an empty "{}" on first start; that one may be replaced.
+        if (st.isSymbolicLink() || !isEmptyAuth(mine))
+            return false;
+        renameSync(mine, `${mine}.empty`);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    mkdirSync(agentDir, { recursive: true });
+    symlinkSync(theirs, mine);
+    return true;
+}
+/** Folder to start in: the vault when started from the home folder, unless --here. */
+export function chooseCwd(cwd, home, vault, here) {
+    if (here || !vault || !existsSync(vault))
+        return cwd;
+    return real(cwd) === real(home) ? vault : cwd;
+}
+/** `pi update` with no package source updates pi itself; here that must not happen. */
+export function isSelfUpdate(args) {
+    if (args[0] !== "update")
+        return false;
+    const rest = args.slice(1).filter((a) => a !== "--force" && a !== "-a" && a !== "--approve");
+    return rest.length === 0 || rest.some((a) => ["--self", "self", "pi", "--all"].includes(a));
+}
+/** The command line for `subsub review ...`: zotero-review in the server folder, with the same settings file. */
+export function reviewCommand(args, cfg, env = process.env) {
+    return {
+        ...serverCommand(cfg, "zotero-review", args, env),
+        env: { ...env, ...(cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {}) },
+    };
+}
+export async function run(argv = process.argv.slice(2)) {
+    const env = process.env;
+    const home = homedir();
+    const here = argv.includes("--here");
+    const args = argv.filter((a) => a !== "--here");
+    if (args[0] === "--version" || args[0] === "-v") {
+        const piPkg = join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..");
+        console.log(`subsub ${packageVersion()} (pi ${packageVersion(piPkg)})`);
+        return;
+    }
+    if (args[0] === "init") {
+        const { initMain } = await import("./init.js");
+        process.exitCode = await initMain(args.slice(1), env);
+        return;
+    }
+    if (args[0] === "doctor") {
+        const { doctorMain } = await import("./doctor.js");
+        process.exitCode = await doctorMain(env);
+        return;
+    }
+    if (args[0] === "review") {
+        const r = reviewCommand(args.slice(1), loadConfig(env), env);
+        const res = spawnSync(r.command, r.args, { env: r.env, stdio: "inherit" });
+        if (res.error)
+            console.error(`Sub-Sub: cannot run ${r.command}: ${res.error.message}`);
+        process.exitCode = res.status ?? 1;
+        return;
+    }
+    if (isSelfUpdate(args)) {
+        console.log(`Sub-Sub is not updated with "update". Its code is in ${PACKAGE_DIR}; after new code arrives, run "npm install" there.`);
+        console.log('To update packages added to Sub-Sub, use "subsub update --extensions".');
+        process.exitCode = 1;
+        return;
+    }
+    const agentDir = agentDirFor(env, home);
+    const piAgentDir = env.PI_CODING_AGENT_DIR ? expand(env.PI_CODING_AGENT_DIR) : join(home, ".pi", "agent");
+    const settings = ensureSettings(agentDir);
+    if (settings === "unreadable") {
+        console.error(`Sub-Sub: ${join(agentDir, "settings.json")} is not valid JSON. Fix it, or move it away and start again.`);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        shareAuth(agentDir, piAgentDir);
+    }
+    catch {
+        /* not important: /login in Sub-Sub also works */
+    }
+    let vault;
+    try {
+        vault = loadConfig(env).vault;
+    }
+    catch {
+        vault = undefined; // the extension reports config errors when it starts
+    }
+    const cwd = chooseCwd(process.cwd(), home, vault, here);
+    if (cwd !== process.cwd())
+        process.chdir(cwd);
+    env.PI_CODING_AGENT_DIR = agentDir;
+    env.SUBSUB_CLI = "1";
+    // pi's update notice would point to the global pi, not to this copy.
+    env.PI_SKIP_VERSION_CHECK ??= "1";
+    process.argv = [process.argv[0], process.argv[1], ...args];
+    const index = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+    await import(__rewriteRelativeImportExtension(pathToFileURL(join(dirname(index), "bundle", "cli.js")).href));
+}

package/dist/config.js

@@ -0,0 +1,144 @@
+/**
+ * Settings for Sub-Sub. Everything has a default; an optional JSON file
+ * (~/.config/subsub/config.json, or SUBSUB_CONFIG) overrides it.
+ *
+ * {
+ *   "profile": "scholar",
+ *   "userName": "Ana", "about": "a master's student in health informatics", "language": "English",
+ *   "vault": "~/Notes",
+ *   "models": { "librarian": "opencode-go/glm-5.3-flash", "researcher": "opencode-go/mimo-v2.6-pro" },
+ *   "defaultMode": "researcher"
+ * }
+ *
+ * `subsub init` writes this file. Without "serverDir" (or when that folder does
+ * not exist), the Zotero servers run from PyPI with uv.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+export const PROFILES = ["reader", "scholar", "author", "editor"];
+/** The Zotero server release that this Sub-Sub version runs when there is no local server folder. */
+export const SERVER_VERSION = "0.4.1";
+export function expand(p) {
+    return resolve(p.replace(/^~(?=$|\/)/, homedir()));
+}
+export function parseEnvFile(path) {
+    const out = {};
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#") || !line.includes("="))
+            continue;
+        const i = line.indexOf("=");
+        out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^['"]|['"]$/g, "");
+    }
+    return out;
+}
+export function configPath(env = process.env) {
+    return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json");
+}
+export function readConfigFile(file) {
+    if (!existsSync(file))
+        return {};
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`Sub-Sub: cannot read ${file}: ${err.message}`);
+    }
+}
+/** Merge settings into the settings file; other settings stay. */
+export function saveConfig(patch, env = process.env) {
+    const file = configPath(env);
+    const merged = { ...readConfigFile(file), ...patch };
+    for (const [k, v] of Object.entries(merged))
+        if (v === undefined)
+            delete merged[k];
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(merged, null, 2)}\n`);
+    return file;
+}
+export function isProfile(x) {
+    return typeof x === "string" && PROFILES.includes(x);
+}
+export function loadConfig(env = process.env) {
+    const file = configPath(env);
+    let user = {};
+    if (existsSync(file)) {
+        try {
+            user = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Sub-Sub: cannot read ${file}: ${err.message}`);
+        }
+    }
+    const envCandidates = [
+        user.envFile,
+        env.ZOTERO_MCP_ENV,
+        "~/.config/zotero-local-mcp/env",
+        "~/.config/opencode/zotero.env",
+    ].filter((x) => Boolean(x));
+    const envFile = envCandidates.map(expand).find((p) => existsSync(p));
+    const envValues = envFile ? parseEnvFile(envFile) : {};
+    const vaultRaw = user.vault ?? env.ZOTERO_VAULT ?? envValues.ZOTERO_VAULT;
+    const vault = vaultRaw ? expand(vaultRaw) : undefined;
+    const mode = user.defaultMode === "librarian" ? "librarian" : "researcher";
+    return {
+        configFile: file,
+        profile: isProfile(user.profile) ? user.profile : "scholar",
+        userName: typeof user.userName === "string" && user.userName.trim() ? user.userName.trim() : undefined,
+        about: typeof user.about === "string" && user.about.trim() ? user.about.trim() : undefined,
+        language: typeof user.language === "string" && user.language.trim() ? user.language.trim() : "English",
+        setup: user.setup,
+        serverDir: expand(user.serverDir ?? "~/Projects/zotero-local-mcp"),
+        envFile,
+        vault,
+        models: user.models ?? {
+            librarian: "opencode-go/glm-5.3-flash",
+            researcher: "opencode-go/mimo-v2.6-pro",
+        },
+        defaultMode: mode,
+        vaultContext: (user.vaultContext ?? (vault ? [join(vault, ".claude", "CLAUDE.md")] : [])).map(expand),
+        sharedRules: user.sharedRules
+            ? expand(user.sharedRules)
+            : vault
+                ? join(vault, "Systems", "Zotero agent.md")
+                : undefined,
+        startTimeout: user.startTimeout ?? 45,
+        uvPath: user.uvPath ? expand(user.uvPath) : undefined,
+        look: user.look,
+        quotes: user.quotes,
+        themes: user.themes,
+    };
+}
+/** uv is often missing from PATH when pi is started outside a login shell. */
+export function findUv(cfg, env = process.env, platform = process.platform) {
+    const unix = ["~/.local/bin/uv", "/opt/homebrew/bin/uv", "/usr/local/bin/uv", "~/.cargo/bin/uv"];
+    const windows = ["~/.local/bin/uv.exe", "~/.cargo/bin/uv.exe", env.LOCALAPPDATA ? join(env.LOCALAPPDATA, "uv", "uv.exe") : ""];
+    const candidates = [cfg.uvPath, env.SUBSUB_UV, ...(platform === "win32" ? windows : unix)]
+        .filter((x) => Boolean(x))
+        .map(expand);
+    return candidates.find((p) => existsSync(p)) ?? "uv";
+}
+/**
+ * How to start one of the Python programs (zotero-local-mcp, zotero-scholar-mcp,
+ * zotero-review): from the local server folder when it exists, otherwise the
+ * pinned release from PyPI through `uv tool run`.
+ */
+export function serverCommand(cfg, program, args = [], env = process.env) {
+    const uv = findUv(cfg, env);
+    if (existsSync(join(cfg.serverDir, "pyproject.toml"))) {
+        return { command: uv, args: ["run", "--quiet", "--directory", cfg.serverDir, program, ...args] };
+    }
+    return { command: uv, args: ["tool", "run", "--quiet", "--from", `zotero-local-mcp==${SERVER_VERSION}`, program, ...args] };
+}
+/** How prompts name the user. */
+export function who(cfg) {
+    return cfg.userName ?? "the user";
+}

package/dist/doctor.js

@@ -0,0 +1,131 @@
+/**
+ * `subsub doctor`: check the setup and say how to fix each problem.
+ *
+ * Checks Node, the settings file, uv, the Zotero server (it runs
+ * `zotero-local-mcp --check`), Zotero itself, the tag list, the notes folder,
+ * the contact email and the model login. Exit code 1 when something needs a fix.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { findUv, loadConfig, SERVER_VERSION, serverCommand } from "./config.js";
+import { profileSpec } from "./profiles.js";
+export const defaultRunner = (command, args, env) => {
+    const r = spawnSync(command, args, { env, encoding: "utf8", timeout: 120_000 });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error?.message };
+};
+const ZOTERO_SETTING = 'In Zotero, open Settings > Advanced and turn on "Allow other applications on this computer to communicate with Zotero".';
+function nodeOk(version) {
+    const [major, minor] = version.split(".").map(Number);
+    return major > 22 || (major === 22 && minor >= 19);
+}
+function hasLogin(agentDir) {
+    try {
+        const data = JSON.parse(readFileSync(join(agentDir, "auth.json"), "utf8"));
+        return Boolean(data) && typeof data === "object" && Object.keys(data).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function runChecks(cfg, env, deps = {}) {
+    const run = deps.run ?? defaultRunner;
+    const out = [];
+    const node = deps.nodeVersion ?? process.versions.node;
+    out.push(nodeOk(node)
+        ? { name: "Node", ok: true, detail: node }
+        : { name: "Node", ok: false, detail: node, fix: "Install Node.js 22.19 or later (https://nodejs.org), or run the Sub-Sub installer again." });
+    out.push(existsSync(cfg.configFile)
+        ? { name: "Settings", ok: true, detail: `${cfg.configFile}, profile ${profileSpec(cfg.profile).label}, replies in ${cfg.language}` }
+        : { name: "Settings", ok: false, detail: `no ${cfg.configFile}`, fix: "Type subsub init." });
+    const uv = findUv(cfg, env);
+    const uvRun = run(uv, ["--version"], env);
+    if (uvRun.status !== 0) {
+        out.push({ name: "uv", ok: false, detail: uvRun.error ?? uvRun.stderr.trim(), fix: "Install uv (https://docs.astral.sh/uv/), or add \"uvPath\" to the settings file." });
+        return out;
+    }
+    out.push({ name: "uv", ok: true, detail: uvRun.stdout.trim() });
+    const cmd = serverCommand(cfg, "zotero-local-mcp", ["--check"], env);
+    const local = cmd.args.includes("--directory");
+    const res = run(cmd.command, cmd.args, { ...env, ...(cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {}) });
+    let st;
+    try {
+        st = JSON.parse(res.stdout);
+    }
+    catch {
+        st = undefined;
+    }
+    if (res.status !== 0 || !st) {
+        const text = (res.error ?? res.stderr).replace(/[^\x20-\x7e\n]/g, " ");
+        const first = text.trim().split("\n").slice(-3).join(" ").replace(/\s+/g, " ").trim();
+        const notPublished = /not found in the package registry/.test(text);
+        out.push({
+            name: "Zotero server",
+            ok: false,
+            detail: notPublished ? `zotero-local-mcp ${SERVER_VERSION} is not on PyPI` : first || "no answer",
+            fix: local
+                ? `Type: cd "${cfg.serverDir}" && uv sync`
+                : notPublished
+                    ? 'Set "serverDir" in the settings file to a copy of the zotero-local-mcp repository.'
+                    : `uv could not run zotero-local-mcp ${SERVER_VERSION} from PyPI. Check the internet connection and try again.`,
+        });
+        return out;
+    }
+    out.push({ name: "Zotero server", ok: true, detail: local ? `from ${cfg.serverDir}` : `zotero-local-mcp ${SERVER_VERSION}` });
+    out.push(st.zotero === "reachable"
+        ? { name: "Zotero", ok: true, detail: `reachable, write permission ${st.write_key_remembered ? "remembered" : "asked at the first change"}` }
+        : { name: "Zotero", ok: false, detail: String(st.error ?? "not reachable"), fix: `Start Zotero 10 or later. ${ZOTERO_SETTING}` });
+    const v = st.vocabulary ?? {};
+    if (v.loaded === false || !v.tags) {
+        out.push({ name: "Tag list", ok: false, detail: v.path ? `cannot read ${v.path}` : "not set", fix: "Type subsub init: it creates a starter tag list." });
+    }
+    else {
+        const noTopics = Array.isArray(v.facets) && !v.facets.includes("topic");
+        out.push({
+            name: "Tag list",
+            ok: !(v.problems?.length),
+            warn: noTopics,
+            detail: `${v.tags} tags in ${v.path}${noTopics ? "; no topic/ tags yet" : ""}`,
+            fix: v.problems?.length
+                ? `Fix these lines in the tag list: ${v.problems.slice(0, 3).join("; ")}`
+                : noTopics
+                    ? "In Sub-Sub (librarian), ask: propose topics for my tag list."
+                    : undefined,
+        });
+    }
+    out.push(cfg.vault && existsSync(cfg.vault)
+        ? { name: "Notes folder", ok: true, detail: cfg.vault }
+        : { name: "Notes folder", ok: false, detail: cfg.vault ? `${cfg.vault} does not exist` : "not set", fix: "Type subsub init." });
+    out.push(st.contact_email_set
+        ? { name: "Contact email", ok: true, detail: "set" }
+        : { name: "Contact email", ok: true, warn: true, detail: "not set: open-access PDFs cannot be found", fix: "Type subsub init and give an email address." });
+    const agentDir = deps.agentDir ?? (env.SUBSUB_AGENT_DIR ? env.SUBSUB_AGENT_DIR : join(homedir(), ".subsub", "agent"));
+    out.push(hasLogin(agentDir)
+        ? { name: "Model login", ok: true, detail: Object.keys(cfg.models).length ? Object.values(cfg.models).join(", ") : "pi's default model" }
+        : { name: "Model login", ok: false, detail: "no model provider yet", fix: "Type subsub, then /login." });
+    return out;
+}
+export function formatChecks(checks) {
+    return checks
+        .map((c) => {
+        const tag = !c.ok ? "FIX " : c.warn ? "NOTE" : "ok  ";
+        return `${tag}  ${c.name.padEnd(14)} ${c.detail}${c.fix && (!c.ok || c.warn) ? `\n      ${" ".repeat(14)} ${c.fix}` : ""}`;
+    })
+        .join("\n");
+}
+export async function doctorMain(env = process.env) {
+    let cfg;
+    try {
+        cfg = loadConfig(env);
+    }
+    catch (err) {
+        console.log(`FIX   Settings       ${err.message}\n                     Fix the JSON, or move the file away and type subsub init.`);
+        return 1;
+    }
+    const checks = runChecks(cfg, env);
+    console.log(formatChecks(checks));
+    const bad = checks.filter((c) => !c.ok).length;
+    console.log(bad ? `\n${bad} problem(s) to fix.` : "\nEverything needed is in place.");
+    return bad ? 1 : 0;
+}