@tiagojct/subsub 0.5.0

package/src/doctor.ts

@@ -0,0 +1,171 @@
+/**
+ * `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, type SubsubConfig } from "./config.ts";
+import { profileSpec } from "./profiles.ts";
+
+export interface Check {
+	name: string;
+	ok: boolean;
+	detail: string;
+	fix?: string;
+	/** A warning: works, but something is missing. */
+	warn?: boolean;
+}
+
+export interface RunResult {
+	status: number | null;
+	stdout: string;
+	stderr: string;
+	error?: string;
+}
+
+export type Runner = (command: string, args: string[], env: NodeJS.ProcessEnv) => RunResult;
+
+export const defaultRunner: Runner = (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: string): boolean {
+	const [major, minor] = version.split(".").map(Number);
+	return major > 22 || (major === 22 && minor >= 19);
+}
+
+function hasLogin(agentDir: string): boolean {
+	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: SubsubConfig,
+	env: NodeJS.ProcessEnv,
+	deps: { run?: Runner; nodeVersion?: string; agentDir?: string } = {},
+): Check[] {
+	const run = deps.run ?? defaultRunner;
+	const out: Check[] = [];
+	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: Record<string, any> | undefined;
+	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: Check[]): string {
+	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: NodeJS.ProcessEnv = process.env): Promise<number> {
+	let cfg: SubsubConfig;
+	try {
+		cfg = loadConfig(env);
+	} catch (err) {
+		console.log(`FIX   Settings       ${(err as Error).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;
+}

package/src/init.ts

@@ -0,0 +1,252 @@
+/**
+ * `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.ts";
+import { PROFILE_SPECS } from "./profiles.ts";
+
+const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
+export const STARTER_TAGS: Record<string, string> = {
+	"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" };
+
+export interface InitIO {
+	ask(question: string, def: string): Promise<string>;
+	choose(question: string, options: Array<{ value: string; label: string }>, def: string): Promise<string>;
+	say(line: string): void;
+}
+
+export interface InitResult {
+	configFile: string;
+	envFile: string;
+	notes: string;
+	created: string[];
+	zotero: boolean;
+}
+
+/** Set KEY=VALUE lines in an env file text; other lines and comments stay. */
+export function upsertEnv(text: string, values: Record<string, string | undefined>): string {
+	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: string, prefix: string): boolean {
+	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: typeof fetch = fetch): Promise<boolean> {
+	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: InitIO,
+	flags: Record<string, string>,
+	env: NodeJS.ProcessEnv = process.env,
+	deps: { fetch?: typeof fetch; home?: string } = {},
+): Promise<InitResult> {
+	const home = deps.home ?? homedir();
+	const configFile = configPath(env);
+	const existing = readConfigFile(configFile) as Record<string, any>;
+	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: string[] = [];
+
+	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: Record<string, unknown> = {
+		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: string[]): Record<string, string> {
+	const out: Record<string, string> = {};
+	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: (l: string) => void): InitIO {
+	return {
+		ask: async (_q, def) => def,
+		choose: async (_q, _o, def) => def,
+		say,
+	};
+}
+
+function terminalIO(): InitIO & { close(): void } {
+	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: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+	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 as Error).message}`);
+		return 1;
+	} finally {
+		(io as { close?: () => void }).close?.();
+	}
+}

package/src/look.ts

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+
+import type { Mode } from "./config.ts";
+
+export const BANNER = [
+	"╔═╗╦ ╦╔╗    ╔═╗╦ ╦╔╗",
+	"╚═╗║ ║╠╩╗───╚═╗║ ║╠╩╗",
+	"╚═╝╚═╝╚═╝   ╚═╝╚═╝╚═╝",
+];
+
+/** Short public-domain lines from Moby-Dick and its Extracts. */
+export const QUOTES: Array<[string, string]> = [
+	["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: Record<Mode, string> = { librarian: "subsub-try-works", researcher: "subsub-glauca" };
+
+export type Scheme = "dark" | "light";
+
+/** Light or dark terminal, judged from the text colour of the current theme (dark text means a light background). */
+export function schemeFromAnsi(fgAnsi: string, themeName?: string): Scheme {
+	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: Mode, scheme: Scheme, map: Partial<Record<Mode, string>> = MODE_THEMES): string | undefined {
+	const base = map[mode];
+	return base ? `${base}-${scheme}` : undefined;
+}
+
+export interface LibraryState {
+	zotero: "checking" | "reachable" | "down";
+	items?: number;
+	toReview?: number;
+	error?: string;
+}
+
+export interface Paint {
+	mark(s: string): string;
+	text(s: string): string;
+	muted(s: string): string;
+	dim(s: string): string;
+	warn(s: string): string;
+}
+
+const plain: Paint = { mark: (s) => s, text: (s) => s, muted: (s) => s, dim: (s) => s, warn: (s) => s };
+
+function cut(s: string, width: number): string {
+	return [...s].length > width ? `${[...s].slice(0, Math.max(0, width - 3)).join("")}...` : s;
+}
+
+export function libraryLine(st: LibraryState): { text: string; warn: boolean } {
+	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: {
+	version: string;
+	mode: Mode;
+	/** Profile label, e.g. "Scholar". */
+	profile?: string;
+	model: string;
+	library: LibraryState;
+	quote?: [string, string];
+	width: number;
+	paint?: Paint;
+}): string[] {
+	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: string,
+	add: (s: string) => string,
+	remove: (s: string) => string,
+	base: (s: string) => string = (x) => x,
+): string {
+	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/src/paths.ts

@@ -0,0 +1,100 @@
+/**
+ * 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: string, cwd: string): string {
+	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: string): string {
+	let head = abs;
+	const tail: string[] = [];
+	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: string, parent: string | undefined): boolean {
+	if (!parent) return false;
+	const rel = relative(parent, child);
+	return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+export interface PathPolicy {
+	/** Folders where writes need no question. */
+	allowed: string[];
+	/** Files and folders that always need a question (rules, config, code). */
+	protectedPaths: string[];
+}
+
+export function buildPolicy(opts: { vault?: string; cwd: string; serverDir: string; packageDir: string }): PathPolicy {
+	const home = realish(homedir());
+	const cwd = realish(opts.cwd);
+	const allowed: string[] = [];
+	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 type PathVerdict = { ok: true } | { ok: false; why: string };
+
+export function judgePath(target: string, policy: PathPolicy): PathVerdict {
+	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" };
+}