@tiagojct/subsub 0.5.0

package/src/bridge.ts

@@ -0,0 +1,134 @@
+/**
+ * Bridge to the Python MCP servers of zotero-local-mcp (librarian "zotero" and
+ * researcher "scholar"). Starts them over stdio, lists their tools, and calls them.
+ * All safety logic (dry runs, version checks, journal, vocabulary, the researcher's
+ * note-only client) stays in the Python servers.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+export interface ServerSpec {
+	name: string; // tool prefix: "zotero" or "scholar"
+	command: string;
+	args: string[];
+	cwd?: string;
+	env?: Record<string, string>;
+}
+
+export interface BridgeTool {
+	server: string;
+	name: string; // MCP tool name
+	fullName: string; // prefixed name used in pi, e.g. zotero_find_items
+	description: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export interface CallResult {
+	isError: boolean;
+	text: string;
+	data?: unknown;
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, what: string): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const t = setTimeout(() => reject(new Error(`${what} did not answer within ${Math.round(ms / 1000)} s`)), ms);
+		p.then(
+			(v) => {
+				clearTimeout(t);
+				resolve(v);
+			},
+			(e) => {
+				clearTimeout(t);
+				reject(e);
+			},
+		);
+	});
+}
+
+export class Bridge {
+	private clients = new Map<string, Client>();
+	private owner = new Map<string, { server: string; name: string }>();
+	tools: BridgeTool[] = [];
+	errors: Record<string, string> = {};
+
+	async start(specs: ServerSpec[], timeoutMs = 45_000): Promise<void> {
+		await Promise.all(specs.map((s) => this.startOne(s, timeoutMs)));
+	}
+
+	private async startOne(spec: ServerSpec, timeoutMs: number): Promise<void> {
+		const transport = new StdioClientTransport({
+			command: spec.command,
+			args: spec.args,
+			cwd: spec.cwd,
+			env: { ...(process.env as Record<string, string>), ...(spec.env ?? {}) },
+			stderr: "pipe",
+		});
+		const client = new Client({ name: "subsub", version: "0.1.0" });
+		let stderr = "";
+		transport.stderr?.on("data", (chunk: Buffer) => {
+			stderr = (stderr + chunk.toString()).slice(-2000);
+		});
+		try {
+			await withTimeout(client.connect(transport), timeoutMs, `The ${spec.name} server`);
+			const listed = await withTimeout(client.listTools(), timeoutMs, `The ${spec.name} server`);
+			this.clients.set(spec.name, client);
+			for (const t of listed.tools) {
+				const fullName = `${spec.name}_${t.name}`;
+				this.owner.set(fullName, { server: spec.name, name: t.name });
+				this.tools.push({
+					server: spec.name,
+					name: t.name,
+					fullName,
+					description: t.description ?? "",
+					inputSchema: (t.inputSchema as Record<string, unknown>) ?? { type: "object", properties: {} },
+				});
+			}
+		} catch (err) {
+			this.errors[spec.name] = `${(err as Error).message}${stderr ? `\n${stderr.trim()}` : ""}`;
+			try {
+				await client.close();
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+
+	has(fullName: string): boolean {
+		return this.owner.has(fullName);
+	}
+
+	async call(fullName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<CallResult> {
+		const own = this.owner.get(fullName);
+		if (!own) return { isError: true, text: `Unknown tool ${fullName}` };
+		const client = this.clients.get(own.server);
+		if (!client) return { isError: true, text: `The ${own.server} server is not running.` };
+		const res = await client.callTool({ name: own.name, arguments: args }, undefined, {
+			signal,
+			timeout: 15 * 60_000, // authorization dialogs and PDF downloads can take minutes
+			resetTimeoutOnProgress: true,
+		});
+		const blocks = (res.content as Array<{ type: string; text?: string }>) ?? [];
+		const text = blocks
+			.filter((b) => b.type === "text")
+			.map((b) => b.text ?? "")
+			.join("\n");
+		let data: unknown = undefined;
+		const sc = res.structuredContent as Record<string, unknown> | undefined;
+		if (sc && typeof sc === "object") {
+			data = Object.keys(sc).length === 1 && "result" in sc ? sc.result : sc;
+		} else {
+			try {
+				data = JSON.parse(text);
+			} catch {
+				/* plain text */
+			}
+		}
+		return { isError: Boolean(res.isError), text: text || JSON.stringify(data ?? ""), data };
+	}
+
+	async close(): Promise<void> {
+		await Promise.all([...this.clients.values()].map((c) => c.close().catch(() => undefined)));
+		this.clients.clear();
+	}
+}

package/src/cli.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+
+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, type SubsubConfig } from "./config.ts";
+
+export const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function packageVersion(dir: string = PACKAGE_DIR): string {
+	try {
+		return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+
+export function agentDirFor(env: NodeJS.ProcessEnv, home: string = homedir()): string {
+	return env.SUBSUB_AGENT_DIR ? expand(env.SUBSUB_AGENT_DIR) : join(home, ".subsub", "agent");
+}
+
+function real(p: string): string {
+	try {
+		return realpathSync(p);
+	} catch {
+		return resolve(p);
+	}
+}
+
+function sourceOf(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	if (entry && typeof entry === "object" && typeof (entry as { source?: unknown }).source === "string") {
+		return (entry as { source: string }).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: string, packageDir: string = PACKAGE_DIR): "created" | "added" | "present" | "unreadable" {
+	mkdirSync(agentDir, { recursive: true });
+	const file = join(agentDir, "settings.json");
+	let settings: Record<string, unknown> = {};
+	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: string): boolean {
+	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: string, piAgentDir: string): boolean {
+	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 as NodeJS.ErrnoException).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: string, home: string, vault: string | undefined, here: boolean): string {
+	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: string[]): boolean {
+	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: string[], cfg: SubsubConfig, env: NodeJS.ProcessEnv = process.env): { command: string; args: string[]; env: NodeJS.ProcessEnv } {
+	return {
+		...serverCommand(cfg, "zotero-review", args, env),
+		env: { ...env, ...(cfg.envFile ? { ZOTERO_MCP_ENV: cfg.envFile } : {}) },
+	};
+}
+
+export async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
+	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.ts");
+		process.exitCode = await initMain(args.slice(1), env);
+		return;
+	}
+	if (args[0] === "doctor") {
+		const { doctorMain } = await import("./doctor.ts");
+		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: string | undefined;
+	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(pathToFileURL(join(dirname(index), "bundle", "cli.js")).href);
+}

package/src/config.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 type Mode = "librarian" | "researcher";
+export type Profile = "reader" | "scholar" | "author" | "editor";
+export const PROFILES: Profile[] = ["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 interface SubsubConfig {
+	/** The settings file (written by `subsub init` and `/profile`). */
+	configFile: string;
+	/** How much Sub-Sub does for the user: reader, scholar, author or editor. */
+	profile: Profile;
+	/** How the prompts name the user ("the user" when not set). */
+	userName?: string;
+	/** One line about the user, e.g. "a master's student in health informatics". */
+	about?: string;
+	/** Language of replies and notes. "auto": the language the user writes in. */
+	language: string;
+	/** "fmup" when set up with the FMUP / U.Porto option. */
+	setup?: string;
+	serverDir: string;
+	envFile?: string;
+	vault?: string;
+	models: Partial<Record<Mode, string>>;
+	defaultMode: Mode;
+	/** Extra context files added to the system prompt when pi runs inside the vault. */
+	vaultContext: string[];
+	/** Shared rules file (tag system, citekeys, note formats). */
+	sharedRules?: string;
+	/** Seconds to wait for the Python servers to start. */
+	startTimeout: number;
+	/** Path to uv when it is not on PATH (for example when pi starts from a GUI). */
+	uvPath?: string;
+	/** Banner, status line and themes when Sub-Sub runs as its own command (default true). */
+	look?: boolean;
+	/** A line from Moby-Dick under the banner (default true). */
+	quotes?: boolean;
+	/** Theme per mode, without -dark/-light; false keeps your pi theme. */
+	themes?: Partial<Record<Mode, string>> | false;
+}
+
+export function expand(p: string): string {
+	return resolve(p.replace(/^~(?=$|\/)/, homedir()));
+}
+
+export function parseEnvFile(path: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	let text: string;
+	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: NodeJS.ProcessEnv = process.env): string {
+	return expand(env.SUBSUB_CONFIG ?? "~/.config/subsub/config.json");
+}
+
+export function readConfigFile(file: string): Record<string, unknown> {
+	if (!existsSync(file)) return {};
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new Error(`Sub-Sub: cannot read ${file}: ${(err as Error).message}`);
+	}
+}
+
+/** Merge settings into the settings file; other settings stay. */
+export function saveConfig(patch: Record<string, unknown>, env: NodeJS.ProcessEnv = process.env): string {
+	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: unknown): x is Profile {
+	return typeof x === "string" && (PROFILES as string[]).includes(x);
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): SubsubConfig {
+	const file = configPath(env);
+	let user: Partial<SubsubConfig> = {};
+	if (existsSync(file)) {
+		try {
+			user = JSON.parse(readFileSync(file, "utf8"));
+		} catch (err) {
+			throw new Error(`Sub-Sub: cannot read ${file}: ${(err as Error).message}`);
+		}
+	}
+	const envCandidates = [
+		user.envFile,
+		env.ZOTERO_MCP_ENV,
+		"~/.config/zotero-local-mcp/env",
+		"~/.config/opencode/zotero.env",
+	].filter((x): x is string => 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: Pick<SubsubConfig, "uvPath">, env: NodeJS.ProcessEnv = process.env, platform: string = process.platform): string {
+	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): x is string => 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: Pick<SubsubConfig, "serverDir" | "uvPath">,
+	program: string,
+	args: string[] = [],
+	env: NodeJS.ProcessEnv = process.env,
+): { command: string; args: string[] } {
+	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: Pick<SubsubConfig, "userName">): string {
+	return cfg.userName ?? "the user";
+}