oh-my-pi/packages/coding-agent/src/internal-urls/vault-protocol.ts

import * as fs from "node:fs";
import * as path from "node:path";
import { $which, isEnoent } from "@oh-my-pi/pi-utils";
import { isSettingsInitialized, settings } from "../config/settings";
import { getDefault } from "../config/settings-schema";
import { parseInternalUrl } from "./parse";
import { validateRelativePath } from "./skill-protocol";
import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, WriteContext } from "./types";

const DARWIN_OBSIDIAN_BINARY = "/Applications/Obsidian.app/Contents/MacOS/obsidian";
const DEFAULT_OBSIDIAN_TIMEOUT_MS = 30_000;

type ContentType = InternalResource["contentType"];
type VaultParamValue = string | true;
type VaultParams = Record<string, VaultParamValue>;

type FileOp = "outline" | "backlinks" | "links" | "tags" | "properties" | "tasks" | "wordcount" | "history" | "base";

type VaultOp =
	| "search"
	| "daily"
	| "daily-path"
	| "tags"
	| "tag"
	| "tasks"
	| "orphans"
	| "unresolved"
	| "deadends"
	| "bases"
	| "bookmarks"
	| "recents"
	| "templates"
	| "aliases"
	| "properties"
	| "property";

const FILE_OPS: Record<FileOp, true> = {
	outline: true,
	backlinks: true,
	links: true,
	tags: true,
	properties: true,
	tasks: true,
	wordcount: true,
	history: true,
	base: true,
};

const VAULT_OPS: Record<VaultOp, true> = {
	search: true,
	daily: true,
	"daily-path": true,
	tags: true,
	tag: true,
	tasks: true,
	orphans: true,
	unresolved: true,
	deadends: true,
	bases: true,
	bookmarks: true,
	recents: true,
	templates: true,
	aliases: true,
	properties: true,
	property: true,
};

export interface VaultReference {
	vault: string | null;
	active: boolean;
	forwardVault: boolean;
	display: string;
}

export type ParsedVaultUrl =
	| { kind: "list-vaults"; url: string; params: VaultParams }
	| { kind: "vault-info"; url: string; ref: VaultReference; params: VaultParams }
	| { kind: "fs-dir"; url: string; ref: VaultReference; relativePath: string; params: VaultParams }
	| { kind: "fs-file"; url: string; ref: VaultReference; relativePath: string; params: VaultParams }
	| { kind: "file-op"; url: string; ref: VaultReference; relativePath: string; op: FileOp; params: VaultParams }
	| { kind: "vault-op"; url: string; ref: VaultReference; op: VaultOp; params: VaultParams };

export interface ObsidianSpawnResult {
	stdout: string;
	stderr: string;
	exitCode: number;
}

export interface VaultProtocolHandlerOptions {
	spawnObsidian?: typeof spawnObsidian;
	resolveObsidianBinary?: () => string | null;
}

interface CliInvocation {
	args: string[];
	contentType: ContentType;
	opLabel: string;
}

interface VaultCounts {
	files: number;
	folders: number;
}

let cachedObsidianBinary: string | null | undefined;
let binaryOverrideForTests: string | null | undefined;
let cachedVaultDirectory: Map<string, string> | undefined;
let cachedActiveVaultPath: string | undefined;
const cachedVaultInfo = new Map<string, string>();

function toVaultValidationError(error: unknown): Error {
	const message = error instanceof Error ? error.message : String(error);
	return new Error(message.replace("skill://", "vault://"));
}

function getContentType(filePath: string): ContentType {
	const ext = path.extname(filePath).toLowerCase();
	if (ext === ".md") return "text/markdown";
	if (ext === ".json") return "application/json";
	return "text/plain";
}

function ensureWithinRoot(targetPath: string, rootPath: string): void {
	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
		throw new Error("vault:// URL escapes vault root");
	}
}

function encodePathComponent(component: string): string {
	return encodeURIComponent(component).replaceAll("%2F", "/");
}

function encodeRelativePath(relativePath: string): string {
	return relativePath
		.split("/")
		.filter(segment => segment.length > 0)
		.map(encodeURIComponent)
		.join("/");
}

function decodeVaultPath(url: InternalUrl): {
	rawPathname: string;
	relativePath: string;
	hasPath: boolean;
	isDirectory: boolean;
} {
	const rawPathname = url.rawPathname ?? url.pathname;
	const hasPath = rawPathname !== undefined && rawPathname !== "" && rawPathname !== "/";
	const isDirectory = rawPathname === "/" || rawPathname.endsWith("/");
	if (!hasPath) {
		return { rawPathname, relativePath: "", hasPath: false, isDirectory };
	}

	let decoded: string;
	try {
		decoded = decodeURIComponent(rawPathname.slice(1).replaceAll("\\", "/"));
	} catch {
		throw new Error(`Invalid URL encoding in vault:// path: ${url.href}`);
	}

	try {
		validateRelativePath(decoded);
	} catch (error) {
		throw toVaultValidationError(error);
	}

	return { rawPathname, relativePath: decoded.replace(/\/+$/, ""), hasPath: true, isDirectory };
}

function paramsFromUrl(url: InternalUrl): VaultParams {
	const params: VaultParams = {};
	for (const [key, value] of url.searchParams) {
		params[key] = value === "" ? true : value;
	}
	return params;
}

function makeVaultReference(host: string): VaultReference {
	if (!host || host === "_") {
		return { vault: null, active: true, forwardVault: false, display: "_" };
	}
	return { vault: host, active: false, forwardVault: true, display: host };
}

function isFileOp(rawOp: string): rawOp is FileOp {
	return FILE_OPS[rawOp as FileOp] === true;
}

function isVaultOp(rawOp: string): rawOp is VaultOp {
	return VAULT_OPS[rawOp as VaultOp] === true;
}

function parseVaultOp(rawOp: string, hasFilePath: boolean): FileOp | VaultOp {
	if (hasFilePath) {
		if (!isFileOp(rawOp)) {
			throw new Error(`Unsupported vault:// file op: ${rawOp}`);
		}
		return rawOp;
	}
	if (!isVaultOp(rawOp)) {
		throw new Error(`Unsupported vault:// vault op: ${rawOp}`);
	}
	return rawOp;
}

export function parseVaultUrl(input: string | InternalUrl): ParsedVaultUrl {
	const url = typeof input === "string" ? parseInternalUrl(input) : input;
	const host = url.rawHost || url.hostname;
	const params = paramsFromUrl(url);
	const rawOp = typeof params.op === "string" ? params.op : undefined;
	const { rawPathname, relativePath, hasPath, isDirectory } = decodeVaultPath(url);

	if (!host && !hasPath && !rawOp) {
		return { kind: "list-vaults", url: url.href, params };
	}

	const ref = makeVaultReference(host);
	if (rawOp) {
		const op = parseVaultOp(rawOp, relativePath.length > 0);
		if (relativePath.length > 0) {
			return { kind: "file-op", url: url.href, ref, relativePath, op: op as FileOp, params };
		}
		return { kind: "vault-op", url: url.href, ref, op: op as VaultOp, params };
	}

	if (!host && !hasPath) {
		return { kind: "list-vaults", url: url.href, params };
	}

	if (!hasPath && rawPathname !== "/") {
		return { kind: "vault-info", url: url.href, ref, params };
	}

	if (isDirectory) {
		return { kind: "fs-dir", url: url.href, ref, relativePath, params };
	}

	return { kind: "fs-file", url: url.href, ref, relativePath, params };
}

function abortError(): Error {
	return new Error("obsidian command cancelled");
}

export async function spawnObsidian(
	bin: string,
	args: string[],
	signal?: AbortSignal,
	timeoutMs = DEFAULT_OBSIDIAN_TIMEOUT_MS,
): Promise<ObsidianSpawnResult> {
	if (signal?.aborted) throw abortError();

	const proc = Bun.spawn({
		cmd: [bin, ...args],
		stdout: "pipe",
		stderr: "pipe",
	});
	const stdout = new Response(proc.stdout as ReadableStream<Uint8Array>).text();
	const stderr = new Response(proc.stderr as ReadableStream<Uint8Array>).text();
	const aborted = Promise.withResolvers<never>();
	const timedOut = Promise.withResolvers<never>();

	const abortHandler = (): void => {
		proc.kill();
		aborted.reject(abortError());
	};
	if (signal) signal.addEventListener("abort", abortHandler, { once: true });

	const timeout = setTimeout(() => {
		proc.kill();
		timedOut.reject(new Error(`obsidian command timed out after ${timeoutMs}ms`));
	}, timeoutMs);

	const completed = proc.exited.then(async exitCode => ({
		stdout: await stdout,
		stderr: await stderr,
		exitCode,
	}));

	try {
		return await Promise.race([completed, aborted.promise, timedOut.promise]);
	} finally {
		clearTimeout(timeout);
		if (signal) signal.removeEventListener("abort", abortHandler);
	}
}

export function resolveObsidianBinary(): string | null {
	if (binaryOverrideForTests !== undefined) return binaryOverrideForTests;
	if (cachedObsidianBinary !== undefined) return cachedObsidianBinary;

	const onPath = $which("obsidian");
	if (onPath) {
		cachedObsidianBinary = onPath;
		return cachedObsidianBinary;
	}

	if (process.platform === "darwin" && fs.existsSync(DARWIN_OBSIDIAN_BINARY)) {
		cachedObsidianBinary = DARWIN_OBSIDIAN_BINARY;
		return cachedObsidianBinary;
	}

	cachedObsidianBinary = null;
	return cachedObsidianBinary;
}

/**
 * Whether the `vault://` protocol is enabled in the active settings profile.
 *
 * Reads `vault.enabled` from the global settings singleton. Falls back to the
 * schema default when settings are not yet initialized (e.g. during isolated
 * unit tests that exercise the handler before the host calls `Settings.init`).
 */
export function isVaultEnabled(): boolean {
	if (!isSettingsInitialized()) return getDefault("vault.enabled");
	try {
		return settings.get("vault.enabled");
	} catch {
		// Defensive: if the settings proxy throws (e.g. shutdown race), fall back to default.
		return getDefault("vault.enabled");
	}
}

export function hasObsidian(): boolean {
	return isVaultEnabled() && resolveObsidianBinary() !== null;
}

const VAULT_DISABLED_MESSAGE =
	"vault:// is disabled. Enable it by setting `vault.enabled = true` (Settings → Tools → Obsidian Vault).";

export class VaultDisabledError extends Error {
	constructor() {
		super(VAULT_DISABLED_MESSAGE);
		this.name = "VaultDisabledError";
	}
}

function missingBinaryError(): Error {
	return new Error(
		"Obsidian CLI binary not found. Checked PATH entry 'obsidian' and " +
			`${DARWIN_OBSIDIAN_BINARY}. Install Obsidian from https://obsidian.md or add its CLI binary to PATH.`,
	);
}

function requireObsidianBinary(resolveBinary: () => string | null): string {
	const bin = resolveBinary();
	if (bin) return bin;
	throw missingBinaryError();
}

function cliReportedError(result: ObsidianSpawnResult): string | undefined {
	const stderr = result.stderr.trim();
	if (stderr.startsWith("Error:")) return stderr;
	const stdout = result.stdout.trim();
	if (stdout.startsWith("Error:")) return stdout;
	return undefined;
}

function assertCliSuccess(opLabel: string, result: ObsidianSpawnResult): void {
	const reportedError = cliReportedError(result);
	if (result.exitCode === 0 && !reportedError) return;
	const stderr = result.stderr.trim();
	const stdout = result.stdout.trim();
	const detail = reportedError || stderr || stdout || `obsidian exited with code ${result.exitCode}`;
	throw new Error(`vault://${opLabel} failed: ${detail}`);
}

function parseVaultDirectory(stdout: string): Map<string, string> {
	const vaults = new Map<string, string>();
	for (const line of stdout.split(/\r?\n/)) {
		const trimmed = line.trimEnd();
		if (!trimmed) continue;
		const tab = trimmed.indexOf("\t");
		if (tab <= 0) continue;
		const name = trimmed.slice(0, tab);
		const vaultPath = trimmed.slice(tab + 1).trim();
		if (!name || !vaultPath) continue;
		vaults.set(name, path.resolve(vaultPath));
	}
	return vaults;
}

function parseActiveVaultPath(stdout: string): string {
	for (const line of stdout.split(/\r?\n/)) {
		const trimmed = line.trim();
		if (!trimmed) continue;
		const tab = trimmed.indexOf("\t");
		if (tab > 0 && trimmed.slice(0, tab).toLowerCase() === "path") {
			return trimmed.slice(tab + 1).trim();
		}
		const colon = trimmed.indexOf(":");
		if (colon > 0 && trimmed.slice(0, colon).toLowerCase() === "path") {
			return trimmed.slice(colon + 1).trim();
		}
	}
	const trimmed = stdout.trim();
	return trimmed.includes("\n") ? "" : trimmed;
}

function getCachedVaultRoot(ref: VaultReference): string | undefined {
	if (ref.active) return cachedActiveVaultPath ? path.resolve(cachedActiveVaultPath) : undefined;
	if (!ref.vault) return undefined;
	const cached = cachedVaultDirectory?.get(ref.vault);
	return cached ? path.resolve(cached) : undefined;
}

function findExistingAncestorSync(targetPath: string, rootPath: string): string {
	let current = targetPath;
	while (true) {
		ensureWithinRoot(current, rootPath);
		try {
			return fs.realpathSync(current);
		} catch (error) {
			if (!isEnoent(error)) throw error;
			const parent = path.dirname(current);
			if (parent === current) throw error;
			current = parent;
		}
	}
}

export function resolveVaultUrlToPath(input: string | InternalUrl): string {
	if (!isVaultEnabled()) throw new VaultDisabledError();
	const parsed = parseVaultUrl(input);
	if (parsed.kind !== "fs-file" && parsed.kind !== "fs-dir") {
		throw new Error("vault:// path resolution only supports plain filesystem paths");
	}

	const cachedRoot = getCachedVaultRoot(parsed.ref);
	if (!cachedRoot) {
		throw new Error(
			"vault:// path resolution requires a cached vault root; read vault:// first or use the write tool",
		);
	}

	const resolvedRoot = fs.realpathSync(cachedRoot);
	const targetPath = parsed.relativePath ? path.resolve(resolvedRoot, parsed.relativePath) : resolvedRoot;
	ensureWithinRoot(targetPath, resolvedRoot);

	try {
		const realTarget = fs.realpathSync(targetPath);
		ensureWithinRoot(realTarget, resolvedRoot);
	} catch (error) {
		if (!isEnoent(error)) throw error;
		const realParent = findExistingAncestorSync(path.dirname(targetPath), resolvedRoot);
		ensureWithinRoot(realParent, resolvedRoot);
	}

	return targetPath;
}

async function findExistingAncestor(targetPath: string, rootPath: string): Promise<string> {
	let current = targetPath;
	while (true) {
		ensureWithinRoot(current, rootPath);
		try {
			return await fs.promises.realpath(current);
		} catch (error) {
			if (!isEnoent(error)) throw error;
			const parent = path.dirname(current);
			if (parent === current) throw error;
			current = parent;
		}
	}
}

async function countVaultEntries(rootPath: string): Promise<VaultCounts> {
	const pending = [rootPath];
	let files = 0;
	let folders = 0;
	while (pending.length > 0) {
		const dir = pending.pop();
		if (!dir) continue;
		const entries = await fs.promises.readdir(dir, { withFileTypes: true });
		for (const entry of entries) {
			const entryPath = path.join(dir, entry.name);
			if (entry.isDirectory()) {
				folders++;
				pending.push(entryPath);
			} else if (entry.isFile()) {
				files++;
			}
		}
	}
	return { files, folders };
}

function formatVaultPathForLink(ref: VaultReference, relativePath: string, trailingSlash: boolean): string {
	const encodedVault = ref.active ? "_" : encodePathComponent(ref.display);
	const encodedPath = encodeRelativePath(relativePath);
	const suffix = trailingSlash ? "/" : "";
	return encodedPath ? `vault://${encodedVault}/${encodedPath}${suffix}` : `vault://${encodedVault}/`;
}

function paramString(params: VaultParams, name: string): string | undefined {
	const value = params[name];
	return typeof value === "string" && value.length > 0 ? value : undefined;
}

function requireParam(params: VaultParams, name: string, op: string): string {
	const value = paramString(params, name);
	if (value) return value;
	throw new Error(`vault://${op} requires '${name}' query parameter`);
}

function validateQueryPath(params: VaultParams, name: string): string | undefined {
	const value = paramString(params, name);
	if (!value) return undefined;
	try {
		validateRelativePath(value.replaceAll("\\", "/"));
	} catch (error) {
		throw toVaultValidationError(error);
	}
	return value;
}

export function buildObsidianCliInvocation(
	parsed: Extract<ParsedVaultUrl, { kind: "file-op" | "vault-op" }>,
): CliInvocation {
	if (parsed.kind === "file-op") {
		const pathArg = `path=${parsed.relativePath}`;
		switch (parsed.op) {
			case "outline":
				return { args: ["outline", pathArg, "format=md"], contentType: "text/markdown", opLabel: "outline" };
			case "backlinks":
				return {
					args: ["backlinks", pathArg, "counts", "format=tsv"],
					contentType: "text/plain",
					opLabel: "backlinks",
				};
			case "links":
				return { args: ["links", pathArg], contentType: "text/plain", opLabel: "links" };
			case "tags":
				return {
					args: ["tags", pathArg, "counts", "format=json"],
					contentType: "application/json",
					opLabel: "tags",
				};
			case "properties":
				return {
					args: ["properties", pathArg, "format=yaml"],
					contentType: "text/markdown",
					opLabel: "properties",
				};
			case "tasks":
				return {
					args: ["tasks", pathArg, "verbose", "format=json"],
					contentType: "application/json",
					opLabel: "tasks",
				};
			case "wordcount":
				return { args: ["wordcount", pathArg], contentType: "text/plain", opLabel: "wordcount" };
			case "history":
				return { args: ["history", pathArg], contentType: "text/plain", opLabel: "history" };
			case "base": {
				const view = requireParam(parsed.params, "view", "base");
				return {
					args: ["base:query", pathArg, `view=${view}`, "format=md"],
					contentType: "text/markdown",
					opLabel: "base",
				};
			}
		}
	}

	switch (parsed.op) {
		case "search": {
			const query = requireParam(parsed.params, "q", "search");
			const args = ["search:context", `query=${query}`];
			const pathFilter = validateQueryPath(parsed.params, "path");
			if (pathFilter) args.push(`path=${pathFilter}`);
			const limit = paramString(parsed.params, "limit");
			if (limit) args.push(`limit=${limit}`);
			if (parsed.params.case !== undefined) args.push("case");
			args.push("format=json");
			return { args, contentType: "application/json", opLabel: "search" };
		}
		case "daily":
			return { args: ["daily:read"], contentType: "text/markdown", opLabel: "daily" };
		case "daily-path":
			return { args: ["daily:path"], contentType: "text/plain", opLabel: "daily-path" };
		case "tags":
			return {
				args: ["tags", "counts", "format=json"],
				contentType: "application/json",
				opLabel: "tags",
			};
		case "tag": {
			const tag = paramString(parsed.params, "name") ?? requireParam(parsed.params, "tag", "tag");
			return { args: ["tag", `name=${tag}`, "verbose"], contentType: "text/plain", opLabel: "tag" };
		}
		case "tasks":
			return {
				args: ["tasks", "todo", "verbose", "format=json"],
				contentType: "application/json",
				opLabel: "tasks",
			};
		case "orphans":
			return { args: ["orphans"], contentType: "text/plain", opLabel: "orphans" };
		case "unresolved":
			return {
				args: ["unresolved", "counts", "verbose", "format=json"],
				contentType: "application/json",
				opLabel: "unresolved",
			};
		case "deadends":
			return { args: ["deadends"], contentType: "text/plain", opLabel: "deadends" };
		case "bases":
			return { args: ["bases"], contentType: "text/plain", opLabel: "bases" };
		case "bookmarks":
			return {
				args: ["bookmarks", "verbose", "format=json"],
				contentType: "application/json",
				opLabel: "bookmarks",
			};
		case "recents":
			return { args: ["recents"], contentType: "text/plain", opLabel: "recents" };
		case "templates":
			return { args: ["templates"], contentType: "text/plain", opLabel: "templates" };
		case "aliases":
			return {
				args: ["aliases", "verbose", "format=json"],
				contentType: "application/json",
				opLabel: "aliases",
			};
		case "properties":
			return {
				args: ["properties", "counts", "format=yaml"],
				contentType: "text/markdown",
				opLabel: "properties",
			};
		case "property": {
			const name = requireParam(parsed.params, "name", "property");
			const propertyPath = requireParam(parsed.params, "path", "property");
			validateQueryPath(parsed.params, "path");
			return {
				args: ["property:read", `name=${name}`, `path=${propertyPath}`],
				contentType: "text/plain",
				opLabel: "property",
			};
		}
	}
}

export class VaultProtocolHandler implements ProtocolHandler {
	readonly scheme = "vault";
	readonly immutable = false;

	readonly #spawnObsidian: typeof spawnObsidian;
	readonly #resolveObsidianBinary: () => string | null;

	constructor(options: VaultProtocolHandlerOptions = {}) {
		this.#spawnObsidian = options.spawnObsidian ?? spawnObsidian;
		this.#resolveObsidianBinary = options.resolveObsidianBinary ?? resolveObsidianBinary;
	}

	static resetForTests(): void {
		cachedObsidianBinary = undefined;
		binaryOverrideForTests = undefined;
		cachedVaultDirectory = undefined;
		cachedActiveVaultPath = undefined;
		cachedVaultInfo.clear();
	}

	static setObsidianBinaryForTests(value: string | null | undefined): void {
		binaryOverrideForTests = value;
		cachedObsidianBinary = undefined;
	}

	static setVaultDirectoryForTests(entries: ReadonlyMap<string, string> | Record<string, string> | undefined): void {
		if (!entries) {
			cachedVaultDirectory = undefined;
			return;
		}
		if (entries instanceof Map) {
			cachedVaultDirectory = new Map(entries);
			return;
		}
		const record = entries as Record<string, string>;
		cachedVaultDirectory = new Map<string, string>();
		for (const name in record) {
			cachedVaultDirectory.set(name, record[name]);
		}
	}

	static setActiveVaultPathForTests(vaultPath: string | undefined): void {
		cachedActiveVaultPath = vaultPath;
	}

	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
		if (!isVaultEnabled()) throw new VaultDisabledError();
		const parsed = parseVaultUrl(url);
		switch (parsed.kind) {
			case "list-vaults":
				return this.#listVaults(parsed, context);
			case "vault-info":
				return this.#vaultInfo(parsed, context);
			case "fs-dir":
				return this.#listDir(parsed, context);
			case "fs-file":
				return this.#readFile(parsed, context);
			case "file-op":
			case "vault-op":
				return this.#runCli(parsed, context);
		}
	}

	async write(url: InternalUrl, content: string, context?: WriteContext): Promise<void> {
		if (!isVaultEnabled()) throw new VaultDisabledError();
		const parsed = parseVaultUrl(url);
		if (parsed.kind !== "fs-file") {
			throw new Error("vault:// write only supports plain file paths");
		}
		await this.#writeFile(parsed, content, context);
	}

	async #spawn(args: string[], context?: ResolveContext | WriteContext): Promise<ObsidianSpawnResult> {
		const bin = requireObsidianBinary(this.#resolveObsidianBinary);
		return this.#spawnObsidian(bin, args, context?.signal, DEFAULT_OBSIDIAN_TIMEOUT_MS);
	}

	async #loadVaultDirectory(context?: ResolveContext | WriteContext): Promise<Map<string, string>> {
		if (cachedVaultDirectory) return cachedVaultDirectory;
		const result = await this.#spawn(["vaults", "verbose"], context);
		assertCliSuccess("vaults", result);
		cachedVaultDirectory = parseVaultDirectory(result.stdout);
		return cachedVaultDirectory;
	}

	async #resolveVaultRoot(ref: VaultReference, context?: ResolveContext | WriteContext): Promise<string> {
		const cached = getCachedVaultRoot(ref);
		if (cached) return cached;

		if (ref.active) {
			const result = await this.#spawn(["vault", "info", "path"], context);
			assertCliSuccess("vault info path", result);
			const activePath = parseActiveVaultPath(result.stdout);
			if (!activePath) {
				throw new Error("vault:// active vault path was empty");
			}
			cachedActiveVaultPath = path.resolve(activePath);
			return cachedActiveVaultPath;
		}

		if (!ref.vault) {
			throw new Error("vault:// URL requires a vault name or '_' for the active vault");
		}
		const vaults = await this.#loadVaultDirectory(context);
		const root = vaults.get(ref.vault);
		if (!root) {
			const available = Array.from(vaults.keys()).sort().join(", ") || "none";
			throw new Error(`Unknown Obsidian vault: ${ref.vault}\nAvailable: ${available}`);
		}
		return path.resolve(root);
	}

	#vaultCliArg(ref: VaultReference): string[] {
		return ref.forwardVault && ref.vault ? [`vault=${ref.vault}`] : [];
	}

	async #listVaults(
		parsed: Extract<ParsedVaultUrl, { kind: "list-vaults" }>,
		context?: ResolveContext,
	): Promise<InternalResource> {
		const vaults = await this.#loadVaultDirectory(context);
		const entries = Array.from(vaults.keys()).sort((a, b) => a.localeCompare(b));
		const listing =
			entries.length === 0
				? "(none)"
				: entries.map(name => `- [${name}](vault://${encodePathComponent(name)}/)`).join("\n");
		const content = `# Obsidian Vaults\n\n${entries.length} vault${entries.length === 1 ? "" : "s"} available:\n\n${listing}\n`;
		return {
			url: parsed.url,
			content,
			contentType: "text/markdown",
			size: Buffer.byteLength(content, "utf-8"),
			immutable: true,
		};
	}

	async #vaultInfo(
		parsed: Extract<ParsedVaultUrl, { kind: "vault-info" }>,
		context?: ResolveContext,
	): Promise<InternalResource> {
		const root = await this.#resolveVaultRoot(parsed.ref, context);
		const cacheKey = parsed.ref.active ? "_" : (parsed.ref.vault ?? "_");
		let cliInfo = cachedVaultInfo.get(cacheKey);
		if (cliInfo === undefined) {
			const result = await this.#spawn(["vault", "info", ...this.#vaultCliArg(parsed.ref)], context);
			assertCliSuccess("vault info", result);
			cliInfo = result.stdout.trim();
			cachedVaultInfo.set(cacheKey, cliInfo);
		}
		const counts = await countVaultEntries(root);
		const payload = {
			name: parsed.ref.display,
			rootPath: root,
			files: counts.files,
			folders: counts.folders,
			info: cliInfo,
		};
		const content = `${JSON.stringify(payload, null, 2)}\n`;
		return {
			url: parsed.url,
			content,
			contentType: "application/json",
			size: Buffer.byteLength(content, "utf-8"),
			sourcePath: root,
			immutable: true,
		};
	}

	async #resolveFsTarget(
		parsed: Extract<ParsedVaultUrl, { kind: "fs-dir" | "fs-file" }>,
		context?: ResolveContext | WriteContext,
	): Promise<{ root: string; targetPath: string }> {
		const root = await this.#resolveVaultRoot(parsed.ref, context);
		const resolvedRoot = await fs.promises.realpath(root);
		const targetPath = parsed.relativePath ? path.resolve(resolvedRoot, parsed.relativePath) : resolvedRoot;
		ensureWithinRoot(targetPath, resolvedRoot);
		return { root: resolvedRoot, targetPath };
	}

	async #listDir(
		parsed: Extract<ParsedVaultUrl, { kind: "fs-dir" }>,
		context?: ResolveContext,
	): Promise<InternalResource> {
		const { root, targetPath } = await this.#resolveFsTarget(parsed, context);
		const realTargetPath = await fs.promises.realpath(targetPath);
		ensureWithinRoot(realTargetPath, root);
		const stat = await fs.promises.stat(realTargetPath);
		if (!stat.isDirectory()) {
			throw new Error(`vault:// URL must resolve to a directory: ${parsed.url}`);
		}
		const entries = await fs.promises.readdir(realTargetPath, { withFileTypes: true });
		entries.sort((a, b) => a.name.localeCompare(b.name));
		const baseRelative = parsed.relativePath ? `${parsed.relativePath}/` : "";
		const lines = entries.map(entry => {
			const entryRelativePath = `${baseRelative}${entry.name}`;
			const isDir = entry.isDirectory();
			const href = formatVaultPathForLink(parsed.ref, entryRelativePath, isDir);
			return `- [${entry.name}${isDir ? "/" : ""}](${href})`;
		});
		const listing = lines.length === 0 ? "(empty)" : lines.join("\n");
		const titlePath = parsed.relativePath ? `/${parsed.relativePath}/` : "/";
		const content = `# Vault ${parsed.ref.display}${titlePath}\n\n${entries.length} entr${entries.length === 1 ? "y" : "ies"}:\n\n${listing}\n`;
		return {
			url: parsed.url,
			content,
			contentType: "text/markdown",
			size: Buffer.byteLength(content, "utf-8"),
			sourcePath: realTargetPath,
			immutable: true,
		};
	}

	async #readFile(
		parsed: Extract<ParsedVaultUrl, { kind: "fs-file" }>,
		context?: ResolveContext,
	): Promise<InternalResource> {
		const { root, targetPath } = await this.#resolveFsTarget(parsed, context);
		const parentDir = path.dirname(targetPath);
		try {
			const realParent = await fs.promises.realpath(parentDir);
			ensureWithinRoot(realParent, root);
		} catch (error) {
			if (!isEnoent(error)) throw error;
		}

		let realTargetPath: string;
		try {
			realTargetPath = await fs.promises.realpath(targetPath);
		} catch (error) {
			if (isEnoent(error)) {
				throw new Error(`Vault file not found: ${parsed.url}`);
			}
			throw error;
		}
		ensureWithinRoot(realTargetPath, root);
		const stat = await fs.promises.stat(realTargetPath);
		if (!stat.isFile()) {
			throw new Error(`vault:// URL must resolve to a file: ${parsed.url}`);
		}

		const content = await Bun.file(realTargetPath).text();
		return {
			url: parsed.url,
			content,
			contentType: getContentType(realTargetPath),
			size: Buffer.byteLength(content, "utf-8"),
			sourcePath: realTargetPath,
		};
	}

	async #writeFile(
		parsed: Extract<ParsedVaultUrl, { kind: "fs-file" }>,
		content: string,
		context?: WriteContext,
	): Promise<void> {
		const { root, targetPath } = await this.#resolveFsTarget(parsed, context);
		try {
			const realTargetPath = await fs.promises.realpath(targetPath);
			ensureWithinRoot(realTargetPath, root);
			const stat = await fs.promises.stat(realTargetPath);
			if (stat.isDirectory()) {
				throw new Error(`vault:// URL must resolve to a file: ${parsed.url}`);
			}
		} catch (error) {
			if (!isEnoent(error)) throw error;
			const parentDir = path.dirname(targetPath);
			const existingAncestor = await findExistingAncestor(parentDir, root);
			ensureWithinRoot(existingAncestor, root);
			await fs.promises.mkdir(parentDir, { recursive: true });
			const realParent = await fs.promises.realpath(parentDir);
			ensureWithinRoot(realParent, root);
		}
		await Bun.write(targetPath, content);
	}

	async #runCli(
		parsed: Extract<ParsedVaultUrl, { kind: "file-op" | "vault-op" }>,
		context?: ResolveContext,
	): Promise<InternalResource> {
		const invocation = buildObsidianCliInvocation(parsed);
		const args = [...invocation.args, ...this.#vaultCliArg(parsed.ref)];
		const result = await this.#spawn(args, context);
		assertCliSuccess(invocation.opLabel, result);
		return {
			url: parsed.url,
			content: result.stdout,
			contentType: invocation.contentType,
			size: Buffer.byteLength(result.stdout, "utf-8"),
			immutable: true,
		};
	}
}