@melaya/runner 1.1.60 → 1.1.62

package/dist/obsidianApp.js

@@ -0,0 +1,1143 @@
+/**
+ * Obsidian app bridge — the "Runs on: App" tools of
+ * docs/plans/obsidian-vault-connector.md §7.1 (§6.3 S1 "App bridge").
+ *
+ * Some Obsidian features only exist in the running app: file recovery
+ * (history, diff), Sync, Publish, the command palette, plugins, themes,
+ * snippets, workspaces and tabs, the web viewer, developer tools. For a vault
+ * registered on THIS computer the runner reaches the user's own Obsidian
+ * through one of two backends:
+ *
+ *   - the official Obsidian CLI (1.12.7+, Settings → General → Command line
+ *     interface), detected automatically. Always spawned with an ARGUMENT
+ *     ARRAY (never a shell string), `vault=<the app's id for the registered
+ *     folder>` first, a deadline and an output cap;
+ *   - optionally the Local REST API plugin (5.4.0). Its URL and API key are
+ *     stored on this computer only (~/.melaya-runner/vaults/obsidian-app.json,
+ *     0600) and never sent to Melaya, logs or models. The plugin serves a
+ *     self-signed certificate: its SHA-256 fingerprint is pinned at connect
+ *     time and every request checks it BEFORE any header (the key) is
+ *     written. TLS verification is never disabled globally.
+ *
+ * Endpoints come from the user (the plugin's own settings in the vault, or
+ * `melaya-runner obsidian-rest`), never from a model's arguments.
+ *
+ * Authority (capability, grant, read/write, route, revocation, dev_tools) is
+ * checked by vaults.ts before an op reaches this module; the bridge re-checks
+ * dev_tools and folder bounds. App ops act on the whole vault, so a grant
+ * limited to folders cannot use them (Files+App reads then stay on the files
+ * engine, which filters by folder).
+ *
+ * Never logged: the API key, op arguments, app output.
+ */
+import { spawn } from "child_process";
+import { X509Certificate, randomBytes, timingSafeEqual } from "crypto";
+import { chmodSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "fs";
+import http from "http";
+import tls from "tls";
+import { homedir, platform as osPlatform, tmpdir } from "os";
+import path from "path";
+const TARGET = { file: "str", path: "vpath" };
+const ONOFF_STATE = ["on", "off"];
+export const APP_OPS = {
+    // General and vault
+    app_version: { cmd: "version", write: false, noVault: true, rest: "version" },
+    app_reload: { cmd: "reload", write: true, timeoutMs: 60_000 },
+    app_restart: { cmd: "restart", write: true, timeoutMs: 60_000 },
+    app_vault_open: { cmd: "vault:open", write: true, noVault: true },
+    // Files
+    app_open: { cmd: "open", write: true, params: { ...TARGET, newtab: "flag" }, rest: "open" },
+    app_active_file: { cmd: "file", write: false, rest: "active" },
+    // Daily, random, search
+    app_daily: { cmd: "daily", write: true, params: { paneType: ["tab", "split", "window"] } },
+    app_random: { cmd: "random", write: true, params: { folder: "vpath", newtab: "flag" } },
+    app_search_open: { cmd: "search:open", write: true, params: { query: "str" } },
+    app_dataview_query: { cmd: null, write: false, params: { query: "code" }, required: ["query"], rest: "dataview" },
+    // File history
+    app_history: { cmd: "history", write: false, params: { ...TARGET } },
+    app_history_list: { cmd: "history:list", write: false },
+    app_history_read: { cmd: "history:read", write: false, params: { ...TARGET, version: "int" } },
+    app_history_restore: { cmd: "history:restore", write: true, params: { ...TARGET, version: "int" }, required: ["version"] },
+    app_history_open: { cmd: "history:open", write: true, params: { ...TARGET } },
+    app_diff: { cmd: "diff", write: false, params: { ...TARGET, from: "int", to: "int", filter: ["local", "sync"] } },
+    // Sync
+    app_sync: { cmd: "sync", write: true, state: "required" },
+    app_sync_status: { cmd: "sync:status", write: false },
+    app_sync_history: { cmd: "sync:history", write: false, params: { ...TARGET, total: "flag" } },
+    app_sync_read: { cmd: "sync:read", write: false, params: { ...TARGET, version: "int" }, required: ["version"] },
+    app_sync_deleted: { cmd: "sync:deleted", write: false, params: { total: "flag" } },
+    app_sync_restore: { cmd: "sync:restore", write: true, params: { ...TARGET, version: "int" }, required: ["version"] },
+    app_sync_open: { cmd: "sync:open", write: true, params: { ...TARGET } },
+    // Publish
+    app_publish_list: { cmd: "publish:list", write: false, params: { total: "flag" } },
+    app_publish_status: { cmd: "publish:status", write: false, params: { total: "flag", new: "flag", changed: "flag", deleted: "flag" } },
+    app_publish_site: { cmd: "publish:site", write: false },
+    app_publish_add: { cmd: "publish:add", write: true, params: { ...TARGET, changed: "flag" }, timeoutMs: 120_000 },
+    app_publish_remove: { cmd: "publish:remove", write: true, params: { ...TARGET }, timeoutMs: 120_000 },
+    app_publish_open: { cmd: "publish:open", write: true, params: { ...TARGET } },
+    // Command palette
+    app_commands: { cmd: "commands", write: false, params: { filter: "str" }, rest: "commands" },
+    app_command: { cmd: "command", write: true, params: { id: "str" }, required: ["id"], rest: "command", timeoutMs: 60_000 },
+    app_hotkeys: { cmd: "hotkeys", write: false, params: { total: "flag", verbose: "flag", format: ["json", "tsv", "csv"] }, json: true },
+    app_hotkey: { cmd: "hotkey", write: false, params: { id: "str", verbose: "flag" }, required: ["id"] },
+    // Plugins
+    plugins: { cmd: "plugins", write: false, mode: "prefer", params: { filter: ["core", "community"], versions: "flag", format: ["json", "tsv", "csv"] }, json: true, filesArgs: ["filter"] },
+    plugins_enabled: { cmd: "plugins:enabled", write: false, mode: "prefer", params: { filter: ["core", "community"], versions: "flag", format: ["json", "tsv", "csv"] }, json: true, filesArgs: [] },
+    plugin: { cmd: "plugin", write: false, mode: "prefer", params: { id: "str" }, required: ["id"], filesArgs: ["id"] },
+    app_plugin_enable: { cmd: "plugin:enable", write: true, params: { id: "str", filter: ["core", "community"] }, required: ["id"] },
+    app_plugin_disable: { cmd: "plugin:disable", write: true, params: { id: "str", filter: ["core", "community"] }, required: ["id"] },
+    app_plugin_install: { cmd: "plugin:install", write: true, params: { id: "str", enable: "flag" }, required: ["id"], timeoutMs: 100_000 },
+    app_plugin_uninstall: { cmd: "plugin:uninstall", write: true, params: { id: "str" }, required: ["id"], timeoutMs: 60_000 },
+    app_plugin_reload: { cmd: "plugin:reload", write: true, params: { id: "str" }, required: ["id"], timeoutMs: 60_000 },
+    app_plugins_restrict: { cmd: "plugins:restrict", write: true, state: "required" },
+    // Themes and snippets
+    themes: { cmd: "themes", write: false, mode: "prefer", params: { versions: "flag" }, filesArgs: [] },
+    theme: { cmd: "theme", write: false, mode: "prefer", params: { name: "str" }, noFiles: true },
+    snippets: { cmd: "snippets", write: false, mode: "prefer", filesArgs: [] },
+    snippets_enabled: { cmd: "snippets:enabled", write: false, mode: "prefer", filesArgs: [] },
+    app_theme_set: { cmd: "theme:set", write: true, params: { name: "str" }, required: ["name"] },
+    app_theme_install: { cmd: "theme:install", write: true, params: { name: "str", enable: "flag" }, required: ["name"], timeoutMs: 100_000 },
+    app_theme_uninstall: { cmd: "theme:uninstall", write: true, params: { name: "str" }, required: ["name"] },
+    app_snippet_enable: { cmd: "snippet:enable", write: true, params: { name: "str" }, required: ["name"] },
+    app_snippet_disable: { cmd: "snippet:disable", write: true, params: { name: "str" }, required: ["name"] },
+    // Workspace, tabs, recents, web viewer
+    recents: { cmd: "recents", write: false, mode: "prefer", params: { total: "flag" }, filesArgs: [] },
+    workspace: { cmd: "workspace", write: false, mode: "prefer", params: { ids: "flag" }, filesArgs: [] },
+    workspaces: { cmd: "workspaces", write: false, mode: "prefer", params: { total: "flag" }, filesArgs: [] },
+    tabs: { cmd: "tabs", write: false, mode: "prefer", params: { ids: "flag" }, noFiles: true },
+    app_workspace_save: { cmd: "workspace:save", write: true, params: { name: "str" }, required: ["name"] },
+    app_workspace_load: { cmd: "workspace:load", write: true, params: { name: "str" }, required: ["name"] },
+    app_workspace_delete: { cmd: "workspace:delete", write: true, params: { name: "str" }, required: ["name"] },
+    app_tab_open: { cmd: "tab:open", write: true, params: { group: "str", file: "vpath", view: "str" } },
+    app_web: { cmd: "web", write: true, params: { url: "url", newtab: "flag" }, required: ["url"] },
+    // Files + App writes the running app owns (bookmarks.json is rewritten by
+    // the app while it runs) or that target the active note.
+    bookmark: {
+        cmd: "bookmark", write: true, mode: "prefer",
+        params: { file: "vpath", subpath: "str", folder: "vpath", search: "str", url: "url", title: "str" },
+        filesArgs: ["file", "subpath", "folder", "search", "url", "title"],
+    },
+    template_insert: { cmd: "template:insert", write: true, mode: "untargeted", params: { name: "str" }, required: ["name"] },
+    base_query: {
+        cmd: "base:query", write: false, mode: "fallback",
+        params: { ...TARGET, view: "str", format: ["json", "csv", "tsv", "md", "paths"] }, json: true,
+    },
+    // Developer (vault policy dev_tools)
+    app_dev_errors: { cmd: "dev:errors", write: false, dev: true, params: { clear: "flag" } },
+    app_dev_console: { cmd: "dev:console", write: false, dev: true, params: { limit: "int", level: ["log", "warn", "error", "info", "debug"], clear: "flag" } },
+    app_dev_css: { cmd: "dev:css", write: false, dev: true, params: { selector: "str", prop: "str" }, required: ["selector"] },
+    app_dev_dom: {
+        cmd: "dev:dom", write: false, dev: true,
+        params: { selector: "str", attr: "str", css: "str", total: "flag", text: "flag", inner: "flag", all: "flag" }, required: ["selector"],
+    },
+    app_dev_screenshot: { cmd: "dev:screenshot", write: false, dev: true, timeoutMs: 60_000 },
+    app_eval: { cmd: "eval", write: true, dev: true, params: { code: "code" }, required: ["code"], timeoutMs: 60_000 },
+    app_dev_cdp: { cmd: "dev:cdp", write: true, dev: true, params: { method: "str", params: "json" }, required: ["method"], timeoutMs: 60_000 },
+    app_dev_debug: { cmd: "dev:debug", write: true, dev: true, state: "optional" },
+    app_dev_mobile: { cmd: "dev:mobile", write: true, dev: true, state: "optional" },
+    app_devtools: { cmd: "devtools", write: true, dev: true },
+};
+/** App ops that change something (need "write" in the grant; HITL at the tool). */
+export const APP_WRITE_OPS = new Set(Object.entries(APP_OPS).filter(([, s]) => s.write).map(([k]) => k));
+/** Developer ops: only when the vault owner turned on "Developer tools". */
+export const APP_DEV_OPS = new Set(Object.entries(APP_OPS).filter(([, s]) => s.dev).map(([k]) => k));
+/** Ops that only the running app serves (app_* plus Files+App ops without a files implementation). */
+export const APP_ONLY_OPS = new Set(Object.entries(APP_OPS).filter(([k, s]) => k.startsWith("app_") || s.noFiles).map(([k]) => k));
+export function isAppOp(op) {
+    return Object.prototype.hasOwnProperty.call(APP_OPS, op);
+}
+export class AppBridgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function appErr(code, message) {
+    return { ok: false, error: { code, message, retry_after: null } };
+}
+const RETURN_CAP_CHARS = 200_000;
+export function appOk(vaultId, value, o) {
+    const env = {
+        ok: true,
+        vault_id: vaultId,
+        path: null,
+        revision: null,
+        index_rev: null,
+        freshness: { as_of: new Date().toISOString(), stale: false, source: "app" },
+    };
+    if (Array.isArray(value))
+        env.items = value;
+    else
+        env.content = value;
+    env.next_cursor = null;
+    env.truncated = !!o.truncated;
+    env.capabilities = [o.backend === "cli" ? "app_cli" : "app_rest"];
+    if (o.status)
+        env.status = o.status;
+    return { ...env, ...(o.extra ?? {}) };
+}
+// ── CLI arguments (argument arrays only) ─────────────────────────────────
+const MAX_VALUE = 4096;
+const MAX_CODE = 64 * 1024;
+function checkVaultPath(v) {
+    const s = v.replace(/\\/g, "/");
+    if (s.startsWith("/") || /^[A-Za-z]:/.test(s))
+        return "must be a path inside the vault";
+    const parts = s.split("/").filter(Boolean);
+    if (parts.some((p) => p === ".."))
+        return "must stay inside the vault";
+    // The configuration folder, .git and .trash are never addressed by agents.
+    if (parts.length && parts[0].startsWith("."))
+        return "cannot address the vault's hidden folders";
+    return null;
+}
+/**
+ * Build the argv for one CLI call: [`vault=<ref>`], <command>, key=value…,
+ * flags, an optional on|off positional. Each value is ONE argv element, so no
+ * value can add a parameter, a flag or a shell construct. Unknown arguments
+ * are refused (the model sees which).
+ */
+export function buildCliArgs(op, args, vaultRef) {
+    const spec = APP_OPS[op];
+    if (!spec || !spec.cmd)
+        return { ok: false, message: `${op} has no Obsidian CLI command.` };
+    const params = spec.params ?? {};
+    const allowed = new Set([...Object.keys(params), ...(spec.state ? ["state"] : []), "dry_run"]);
+    for (const k of Object.keys(args)) {
+        if (!allowed.has(k))
+            return { ok: false, message: `Unknown argument "${k.slice(0, 40)}" for ${op}.` };
+    }
+    const argv = [];
+    if (!spec.noVault) {
+        if (!vaultRef)
+            return { ok: false, message: "The vault is not known to Obsidian on this computer." };
+        argv.push(`vault=${vaultRef}`);
+    }
+    argv.push(spec.cmd);
+    for (const r of spec.required ?? []) {
+        const v = args[r];
+        if (v === undefined || v === null || v === "")
+            return { ok: false, message: `${r} is required for ${op}.` };
+    }
+    for (const [k, kind] of Object.entries(params)) {
+        const v = args[k];
+        if (v === undefined || v === null || v === "" || v === false)
+            continue;
+        if (kind === "flag") {
+            if (v !== true && v !== "true")
+                return { ok: false, message: `${k} is a flag (true or false).` };
+            argv.push(k);
+            continue;
+        }
+        let s;
+        if (kind === "int") {
+            const n = typeof v === "number" ? v : Number(String(v));
+            if (!Number.isInteger(n) || n < 0 || n > 1e9)
+                return { ok: false, message: `${k} must be a whole number.` };
+            s = String(n);
+        }
+        else if (kind === "json") {
+            if (typeof v === "string") {
+                try {
+                    JSON.parse(v);
+                }
+                catch {
+                    return { ok: false, message: `${k} must be JSON.` };
+                }
+                s = v;
+            }
+            else {
+                s = JSON.stringify(v);
+            }
+        }
+        else {
+            if (typeof v !== "string" && typeof v !== "number")
+                return { ok: false, message: `${k} must be text.` };
+            s = String(v);
+        }
+        if (s.includes("\u0000"))
+            return { ok: false, message: `${k} contains a NUL character.` };
+        const max = kind === "code" || kind === "json" ? MAX_CODE : MAX_VALUE;
+        if (s.length > max)
+            return { ok: false, message: `${k} is too long (max ${max} characters).` };
+        if (kind !== "code" && kind !== "json" && /[\r\n]/.test(s))
+            return { ok: false, message: `${k} must be on one line.` };
+        if (Array.isArray(kind) && !kind.includes(s))
+            return { ok: false, message: `${k} must be one of ${kind.join(", ")}.` };
+        if (kind === "vpath") {
+            const bad = checkVaultPath(s);
+            if (bad)
+                return { ok: false, message: `${k} ${bad}.` };
+        }
+        if (kind === "url" && !/^https?:\/\//i.test(s))
+            return { ok: false, message: `${k} must be an http(s) URL.` };
+        argv.push(`${k}=${s}`);
+    }
+    if (spec.json && !args.format)
+        argv.push("format=json");
+    if (spec.state) {
+        const st = args.state;
+        if (st === undefined || st === null || st === "") {
+            if (spec.state === "required")
+                return { ok: false, message: `state (on or off) is required for ${op}.` };
+        }
+        else if (!ONOFF_STATE.includes(String(st))) {
+            return { ok: false, message: "state must be on or off." };
+        }
+        else {
+            argv.push(String(st));
+        }
+    }
+    return { ok: true, argv };
+}
+// ── CLI process (bounded) ─────────────────────────────────────────────────
+export const CLI_DEFAULT_TIMEOUT_MS = 30_000;
+export const CLI_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** Run the CLI once: argv array, no shell, deadline, output cap (the process
+ *  is killed past either). Never rejects. */
+export function runCli(bin, argv, o = {}) {
+    const timeoutMs = o.timeoutMs ?? CLI_DEFAULT_TIMEOUT_MS;
+    const maxBytes = o.maxBytes ?? CLI_MAX_OUTPUT_BYTES;
+    return new Promise((resolve) => {
+        let out = [];
+        let err = [];
+        let outLen = 0;
+        let errLen = 0;
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        let child;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                code,
+                stdout: Buffer.concat(out).toString("utf-8"),
+                stderr: Buffer.concat(err).toString("utf-8").slice(0, 4000),
+                timedOut,
+                truncated,
+            });
+            out = [];
+            err = [];
+        };
+        try {
+            child = (o.spawnImpl ?? spawn)(bin, argv, {
+                shell: false,
+                windowsHide: true,
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: o.cwd ?? tmpdir(),
+            });
+        }
+        catch {
+            resolve({ code: -1, stdout: "", stderr: "spawn failed", timedOut: false, truncated: false });
+            return;
+        }
+        const kill = () => { try {
+            child.kill();
+        }
+        catch { /* gone */ } };
+        const timer = setTimeout(() => { timedOut = true; kill(); finish(null); }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (d) => {
+            if (truncated)
+                return;
+            if (outLen + d.length > maxBytes) {
+                out.push(d.subarray(0, Math.max(0, maxBytes - outLen)));
+                outLen = maxBytes;
+                truncated = true;
+                kill();
+                return;
+            }
+            out.push(d);
+            outLen += d.length;
+        });
+        child.stderr?.on("data", (d) => {
+            if (errLen < 16_384) {
+                err.push(d);
+                errLen += d.length;
+            }
+        });
+        child.on("error", () => finish(-1));
+        child.on("close", (code) => finish(typeof code === "number" ? code : null));
+    });
+}
+const CLI_DISABLED_RE = /command line interface is not enabled/i;
+/** Map one CLI result to a value or a typed error. The CLI prints errors on
+ *  stdout with exit code 0 ("Error: …"), so the text is checked too. */
+export function interpretCliOutput(r, timeoutMs = CLI_DEFAULT_TIMEOUT_MS) {
+    if (r.timedOut)
+        return { ok: false, code: "app_offline", message: `Obsidian did not answer within ${Math.round(timeoutMs / 1000)} s.` };
+    const text = r.stdout.replace(/^/, "");
+    const trimmed = text.trim();
+    if (CLI_DISABLED_RE.test(text) || CLI_DISABLED_RE.test(r.stderr)) {
+        return { ok: false, code: "app_offline", message: "The Obsidian command line interface is off. Turn it on in Obsidian: Settings → General → Advanced → Command line interface." };
+    }
+    const firstLine = (s) => s.split(/\r?\n/).find((l) => l.trim())?.trim().slice(0, 300) || "";
+    const errText = /^error\b[:\s]/i.test(trimmed) ? firstLine(trimmed) : r.code !== 0 ? firstLine(r.stderr) || firstLine(trimmed) || `exit code ${r.code}` : "";
+    if (errText) {
+        const msg = errText.replace(/^error[:\s]+/i, "");
+        const code = /not found|does not exist|no such|unknown (file|note|plugin|theme|snippet|workspace|command)/i.test(msg)
+            ? "not_found"
+            : /not (enabled|available|supported)|requires|subscription|not signed in|not logged in/i.test(msg) ? "unsupported" : "invalid";
+        return { ok: false, code, message: `Obsidian: ${msg}` };
+    }
+    if (!r.truncated && (trimmed.startsWith("{") || trimmed.startsWith("["))) {
+        try {
+            return { ok: true, value: JSON.parse(trimmed), truncated: false };
+        }
+        catch { /* plain text */ }
+    }
+    if (trimmed.length > RETURN_CAP_CHARS)
+        return { ok: true, value: trimmed.slice(0, RETURN_CAP_CHARS), truncated: true };
+    return { ok: true, value: trimmed, truncated: r.truncated };
+}
+function defaultHostEnv() {
+    return { platform: osPlatform(), env: process.env, home: homedir() };
+}
+/** Where the official installer registers the CLI (help: "Command line
+ *  interface"). MELAYA_OBSIDIAN_CLI overrides it for custom installs; it is
+ *  local configuration of this computer, never a model argument. */
+export function cliCandidates(h) {
+    const out = [];
+    const override = h.env.MELAYA_OBSIDIAN_CLI;
+    if (override)
+        out.push(override);
+    const P = h.platform === "win32" ? path.win32 : path.posix;
+    if (h.platform === "win32") {
+        const local = h.env.LOCALAPPDATA || P.join(h.home, "AppData", "Local");
+        out.push(P.join(local, "Programs", "Obsidian", "Obsidian.com"));
+        if (h.env.ProgramFiles)
+            out.push(P.join(h.env.ProgramFiles, "Obsidian", "Obsidian.com"));
+        for (const dir of String(h.env.PATH || h.env.Path || "").split(";"))
+            if (dir)
+                out.push(P.join(dir, "Obsidian.com"));
+    }
+    else {
+        if (h.platform === "darwin")
+            out.push("/usr/local/bin/obsidian", "/opt/homebrew/bin/obsidian");
+        else
+            out.push(P.join(h.home, ".local", "bin", "obsidian"), "/usr/local/bin/obsidian", "/usr/bin/obsidian");
+        for (const dir of String(h.env.PATH || "").split(":"))
+            if (dir)
+                out.push(P.join(dir, "obsidian"));
+    }
+    return Array.from(new Set(out));
+}
+/** A launchable CLI binary. Batch files are refused: Windows runs them
+ *  through cmd.exe, where an argument array is no longer safe. */
+export function findCli(h, exists = isFile) {
+    for (const c of cliCandidates(h)) {
+        if (/\.(cmd|bat|ps1)$/i.test(c))
+            continue;
+        if (exists(c))
+            return c;
+    }
+    return null;
+}
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** obsidian.json: the app's own list of vaults ({vaults: {id: {path, open}}}). */
+export function obsidianConfigCandidates(h) {
+    const P = h.platform === "win32" ? path.win32 : path.posix;
+    if (h.platform === "win32") {
+        const roaming = h.env.APPDATA || P.join(h.home, "AppData", "Roaming");
+        return [P.join(roaming, "obsidian", "obsidian.json")];
+    }
+    if (h.platform === "darwin")
+        return [P.join(h.home, "Library", "Application Support", "obsidian", "obsidian.json")];
+    const xdg = h.env.XDG_CONFIG_HOME || P.join(h.home, ".config");
+    return [
+        P.join(xdg, "obsidian", "obsidian.json"),
+        P.join(h.home, ".var", "app", "md.obsidian.Obsidian", "config", "obsidian", "obsidian.json"),
+        P.join(h.home, "snap", "obsidian", "current", ".config", "obsidian", "obsidian.json"),
+    ];
+}
+/** The app's id for a vault folder (what `vault=` takes), or null. */
+export function findObsidianVaultId(config, vaultPath, platform) {
+    const vaults = config?.vaults;
+    if (!vaults || typeof vaults !== "object")
+        return null;
+    const P = platform === "win32" ? path.win32 : path.posix;
+    const fold = (p) => {
+        const r = P.resolve(p).replace(/[\\/]+$/, "");
+        return platform === "win32" || platform === "darwin" ? r.toLowerCase() : r;
+    };
+    const want = fold(vaultPath);
+    for (const [id, v] of Object.entries(vaults)) {
+        if (!/^[A-Za-z0-9_-]{1,64}$/.test(id) || typeof v?.path !== "string")
+            continue;
+        let p = v.path;
+        try {
+            p = realpathSync.native(p);
+        }
+        catch { /* compare as written */ }
+        if (fold(p) === want || fold(v.path) === want)
+            return { id, open: v.open === true };
+    }
+    return null;
+}
+/** Is the Obsidian desktop app running? null = could not tell. Checked first
+ *  so a read never launches the app as a side effect. */
+export function defaultRunningProbe(platform, spawnImpl) {
+    return async () => {
+        const [cmd, args, match] = platform === "win32"
+            ? ["tasklist", ["/FI", "IMAGENAME eq Obsidian.exe", "/NH", "/FO", "CSV"], /"obsidian\.exe"/i]
+            : platform === "darwin"
+                ? ["pgrep", ["-x", "Obsidian"], /\d/]
+                : ["pgrep", ["-x", "obsidian"], /\d/];
+        const r = await runCli(cmd, args, { timeoutMs: 8000, maxBytes: 256 * 1024, spawnImpl });
+        if (r.code === -1 || r.timedOut)
+            return null;
+        return match.test(r.stdout);
+    };
+}
+// ── Local REST API plugin (pinned TLS) ────────────────────────────────────
+export const REST_PLUGIN_ID = "obsidian-local-rest-api";
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/** Upper-case hex without separators. */
+export function normalizeFingerprint(fp) {
+    return String(fp || "").replace(/[^A-Fa-f0-9]/g, "").toUpperCase();
+}
+export function fingerprintsEqual(a, b) {
+    const x = Buffer.from(normalizeFingerprint(a));
+    const y = Buffer.from(normalizeFingerprint(b));
+    return x.length === 64 && x.length === y.length && timingSafeEqual(x, y);
+}
+/** https on a loopback host only: the bridge never talks to another machine. */
+export function parseRestUrl(u) {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username || url.password)
+        return null;
+    const host = url.hostname;
+    if (!LOOPBACK.has(host))
+        return null;
+    const port = url.port ? Number(url.port) : 443;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return { host: host === "localhost" ? "127.0.0.1" : host.replace(/^\[|\]$/g, ""), port };
+}
+/**
+ * One HTTPS request to the plugin with the certificate pinned. The TLS
+ * session is opened first; the peer certificate's SHA-256 fingerprint must
+ * equal the pinned one before the request (and its Authorization header) is
+ * written. A mismatch is a `forbidden` refusal, never a silent retry.
+ */
+export function pinnedRequest(cfg, req, connectImpl = tls.connect) {
+    const target = parseRestUrl(cfg.url);
+    if (!target)
+        return Promise.reject(new AppBridgeError("invalid", "The Local REST API address must be https on this computer (127.0.0.1)."));
+    const timeoutMs = req.timeoutMs ?? 15_000;
+    const maxBytes = req.maxBytes ?? CLI_MAX_OUTPUT_BYTES;
+    return new Promise((resolve, reject) => {
+        let done = false;
+        let sock = null;
+        const fail = (e) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                sock?.destroy();
+            }
+            catch { /* closed */ }
+            reject(e);
+        };
+        const timer = setTimeout(() => fail(new AppBridgeError("app_offline", "The Obsidian Local REST API did not answer in time.")), timeoutMs);
+        timer.unref?.();
+        try {
+            // Verification is replaced by the pin for THIS socket only (the plugin
+            // signs with its own CA); nothing is sent before the pin matches.
+            sock = connectImpl({ host: target.host, port: target.port, rejectUnauthorized: false, ALPNProtocols: ["http/1.1"] });
+        }
+        catch {
+            fail(new AppBridgeError("app_offline", "The Obsidian Local REST API is not reachable."));
+            return;
+        }
+        sock.once("error", () => fail(new AppBridgeError("app_offline", "The Obsidian Local REST API is not reachable (is Obsidian open with the plugin on?).")));
+        sock.once("secureConnect", () => {
+            if (done || !sock)
+                return;
+            const cert = sock.getPeerCertificate();
+            const fp = cert && typeof cert.fingerprint256 === "string" ? cert.fingerprint256 : "";
+            if (!fp || !fingerprintsEqual(fp, cfg.fingerprint256)) {
+                fail(new AppBridgeError("forbidden", "The Local REST API certificate changed since you connected it. Reconnect it in Melaya (vault settings → Obsidian app) to trust the new one."));
+                return;
+            }
+            const s = sock;
+            const r = http.request({
+                host: target.host,
+                port: target.port,
+                method: req.method,
+                path: req.path,
+                headers: { Host: `127.0.0.1:${target.port}`, ...(req.headers ?? {}), ...(req.body !== undefined ? { "Content-Length": String(Buffer.byteLength(req.body)) } : {}) },
+                createConnection: () => s,
+            });
+            r.on("response", (res) => {
+                const chunks = [];
+                let len = 0;
+                res.on("data", (d) => {
+                    len += d.length;
+                    if (len > maxBytes) {
+                        fail(new AppBridgeError("invalid", "The Local REST API answer is too large."));
+                        return;
+                    }
+                    chunks.push(d);
+                });
+                res.on("end", () => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    try {
+                        s.destroy();
+                    }
+                    catch { /* closed */ }
+                    resolve({ status: res.statusCode || 0, contentType: String(res.headers["content-type"] || ""), body: Buffer.concat(chunks) });
+                });
+                res.on("error", () => fail(new AppBridgeError("app_offline", "The Local REST API connection broke.")));
+            });
+            r.on("error", () => fail(new AppBridgeError("app_offline", "The Local REST API connection broke.")));
+            r.end(req.body);
+        });
+    });
+}
+/** SHA-256 of the certificate the endpoint presents (trust-on-first-use for
+ *  a manual connect; the user confirms it). Sends nothing but a TLS hello. */
+export function peerFingerprint(url, connectImpl = tls.connect, timeoutMs = 8000) {
+    const target = parseRestUrl(url);
+    if (!target)
+        return Promise.reject(new AppBridgeError("invalid", "The address must be https on 127.0.0.1."));
+    return new Promise((resolve, reject) => {
+        const sock = connectImpl({ host: target.host, port: target.port, rejectUnauthorized: false });
+        const t = setTimeout(() => { sock.destroy(); reject(new AppBridgeError("app_offline", "No answer.")); }, timeoutMs);
+        sock.once("error", () => { clearTimeout(t); reject(new AppBridgeError("app_offline", "Not reachable.")); });
+        sock.once("secureConnect", () => {
+            clearTimeout(t);
+            const fp = sock.getPeerCertificate()?.fingerprint256 || "";
+            sock.destroy();
+            fp ? resolve(normalizeFingerprint(fp)) : reject(new AppBridgeError("invalid", "No certificate."));
+        });
+    });
+}
+/** Read the plugin's own settings from the vault's configuration folder
+ *  (`<config>/plugins/obsidian-local-rest-api/data.json`): the port, the API
+ *  key and the certificate it serves, so the fingerprint is pinned from the
+ *  plugin itself rather than trusted on first use. Local read; nothing leaves
+ *  this computer. */
+export function readRestPluginSettings(vaultRoot, configDirName) {
+    const f = path.join(vaultRoot, configDirName, "plugins", REST_PLUGIN_ID, "data.json");
+    let raw;
+    try {
+        const st = lstatSync(f);
+        if (st.isSymbolicLink() || !st.isFile() || st.size > 1024 * 1024)
+            return { ok: false, error: "plugin_settings_unreadable" };
+        raw = readFileSync(f, "utf-8");
+    }
+    catch {
+        return { ok: false, error: "plugin_not_installed" };
+    }
+    let d;
+    try {
+        d = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: "plugin_settings_unreadable" };
+    }
+    if (d?.enableSecureServer === false)
+        return { ok: false, error: "plugin_https_off" };
+    const apiKey = typeof d?.apiKey === "string" ? d.apiKey : "";
+    if (apiKey.length < 16 || apiKey.length > 512 || /[\r\n]/.test(apiKey))
+        return { ok: false, error: "plugin_no_key" };
+    const certPem = typeof d?.crypto?.cert === "string" ? d.crypto.cert : "";
+    let fingerprint256 = "";
+    try {
+        fingerprint256 = normalizeFingerprint(new X509Certificate(certPem).fingerprint256);
+    }
+    catch { /* below */ }
+    if (!fingerprint256)
+        return { ok: false, error: "plugin_no_certificate" };
+    const port = Number.isInteger(d?.port) && d.port > 0 && d.port < 65536 ? d.port : 27124;
+    const headerName = typeof d?.authorizationHeaderName === "string" && /^[A-Za-z0-9-]{1,64}$/.test(d.authorizationHeaderName)
+        ? d.authorizationHeaderName : "Authorization";
+    return { ok: true, settings: { port, apiKey, certPem, fingerprint256, headerName } };
+}
+// ── Local config (~/.melaya-runner/vaults/obsidian-app.json, 0600) ────────
+export class AppLocalConfig {
+    dir;
+    file;
+    cache = null;
+    constructor(dir) {
+        this.dir = dir;
+        this.file = path.join(dir, "obsidian-app.json");
+    }
+    load() {
+        let mtimeMs = -1;
+        try {
+            mtimeMs = statSync(this.file).mtimeMs;
+        }
+        catch { /* none yet */ }
+        if (this.cache && this.cache.mtimeMs === mtimeMs)
+            return this.cache.data;
+        let data = { rest: {} };
+        if (mtimeMs >= 0) {
+            try {
+                const p = JSON.parse(readFileSync(this.file, "utf-8"));
+                if (p && typeof p.rest === "object" && p.rest)
+                    data = { rest: p.rest };
+            }
+            catch { /* corrupt: treated as empty */ }
+        }
+        this.cache = { mtimeMs, data };
+        return data;
+    }
+    getRest(vaultId) {
+        const r = this.load().rest[vaultId];
+        if (!r || typeof r.url !== "string" || typeof r.apiKey !== "string" || typeof r.fingerprint256 !== "string")
+            return null;
+        return parseRestUrl(r.url) ? r : null;
+    }
+    setRest(vaultId, cfg) {
+        const data = { rest: { ...this.load().rest } };
+        if (cfg)
+            data.rest[vaultId] = cfg;
+        else
+            delete data.rest[vaultId];
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 0o600 });
+        renameSync(tmp, this.file);
+        try {
+            chmodSync(this.file, 0o600);
+        }
+        catch { /* not supported on this FS */ }
+        this.cache = null;
+    }
+}
+const RUNNING_TTL_MS = 10_000;
+const VERSION_TTL_MS = 60_000;
+const IDEMPOTENCY_MAX = 512;
+export class ObsidianAppBridge {
+    o;
+    config;
+    h;
+    runningProbe;
+    running = null;
+    versionProbe = null;
+    applied = new Map();
+    writeChains = new Map();
+    constructor(o) {
+        this.o = o;
+        this.config = new AppLocalConfig(o.dir);
+        this.h = o.host ?? defaultHostEnv();
+        this.runningProbe = o.runningProbe ?? defaultRunningProbe(this.h.platform, o.spawnImpl);
+    }
+    bin() {
+        return findCli(this.h, this.o.fileExists ?? isFile);
+    }
+    obsidianConfig() {
+        if (this.o.readObsidianConfig)
+            return this.o.readObsidianConfig();
+        for (const f of obsidianConfigCandidates(this.h)) {
+            try {
+                return JSON.parse(readFileSync(f, "utf-8"));
+            }
+            catch { /* next */ }
+        }
+        return null;
+    }
+    async isRunning() {
+        const now = Date.now();
+        if (this.running && now - this.running.at < RUNNING_TTL_MS)
+            return this.running.value;
+        const value = await this.runningProbe().catch(() => null);
+        this.running = { at: now, value };
+        return value;
+    }
+    /** CLI state for one vault + the vault= reference. */
+    async cliState(reg) {
+        const bin = this.bin();
+        if (!bin)
+            return { state: "not_installed", bin: null, vaultRef: null, version: null };
+        if ((await this.isRunning()) === false)
+            return { state: "not_running", bin, vaultRef: null, version: null };
+        const hit = findObsidianVaultId(this.obsidianConfig(), reg.path, this.h.platform);
+        const now = Date.now();
+        if (!this.versionProbe || this.versionProbe.bin !== bin || now - this.versionProbe.at > VERSION_TTL_MS) {
+            const r = await runCli(bin, ["version"], { timeoutMs: 10_000, maxBytes: 64 * 1024, spawnImpl: this.o.spawnImpl });
+            const i = interpretCliOutput(r, 10_000);
+            this.versionProbe = i.ok
+                ? { at: now, bin, state: "ready", version: String(i.value ?? "").split(/\r?\n/)[0].slice(0, 80) || null }
+                : { at: now, bin, state: /command line interface/i.test(i.message) ? "cli_disabled" : "error", version: null };
+        }
+        if (this.versionProbe.state === "cli_disabled")
+            return { state: "cli_disabled", bin, vaultRef: null, version: null };
+        if (this.versionProbe.state === "error")
+            return { state: "not_running", bin, vaultRef: null, version: null };
+        if (!hit)
+            return { state: "vault_unknown", bin, vaultRef: null, version: this.versionProbe.version };
+        return { state: "ready", bin, vaultRef: hit.id, version: this.versionProbe.version };
+    }
+    async restRequest(cfg, req) {
+        const headers = { [cfg.headerName || "Authorization"]: `Bearer ${cfg.apiKey}` };
+        if (req.contentType)
+            headers["Content-Type"] = req.contentType;
+        if (req.accept)
+            headers.Accept = req.accept;
+        return pinnedRequest(cfg, { method: req.method, path: req.path, headers, body: req.body, timeoutMs: req.timeoutMs }, this.o.tlsConnect);
+    }
+    async restState(vaultId) {
+        const cfg = this.config.getRest(vaultId);
+        if (!cfg)
+            return { state: "not_configured", version: null, cfg: null };
+        try {
+            const r = await this.restRequest(cfg, { method: "GET", path: "/", timeoutMs: 4000 });
+            let j = null;
+            try {
+                j = JSON.parse(r.body.toString("utf-8"));
+            }
+            catch { /* not JSON */ }
+            if (r.status === 401 || r.status === 403 || j?.authenticated === false)
+                return { state: "key_rejected", version: null, cfg };
+            return { state: "connected", version: typeof j?.versions?.obsidian === "string" ? j.versions.obsidian : null, cfg };
+        }
+        catch (e) {
+            if (e instanceof AppBridgeError && e.code === "forbidden")
+                return { state: "cert_changed", version: null, cfg };
+            return { state: "unreachable", version: null, cfg };
+        }
+    }
+    /** Live App availability for one vault (UI status row, capability report). */
+    async status(reg) {
+        const [cli, rest] = await Promise.all([this.cliState(reg), this.restState(reg.id)]);
+        const features = [];
+        if (cli.state === "ready")
+            features.push("app_cli");
+        if (rest.state === "connected")
+            features.push("app_rest");
+        return {
+            cli: cli.state,
+            rest: rest.state,
+            version: cli.version ?? rest.version,
+            features,
+            restFingerprint: rest.cfg ? normalizeFingerprint(rest.cfg.fingerprint256).slice(0, 16) : null,
+        };
+    }
+    /** Connect the Local REST API of this vault from the plugin's own settings. */
+    async connectRest(reg) {
+        const s = readRestPluginSettings(reg.path, reg.configDirName);
+        if (!s.ok)
+            return s;
+        const cfg = {
+            url: `https://127.0.0.1:${s.settings.port}`,
+            apiKey: s.settings.apiKey,
+            fingerprint256: s.settings.fingerprint256,
+            headerName: s.settings.headerName,
+            connectedAt: new Date().toISOString(),
+        };
+        try {
+            const r = await this.restRequest(cfg, { method: "GET", path: "/", timeoutMs: 6000 });
+            let j = null;
+            try {
+                j = JSON.parse(r.body.toString("utf-8"));
+            }
+            catch { /* not JSON */ }
+            if (r.status === 401 || r.status === 403 || j?.authenticated === false)
+                return { ok: false, error: "key_rejected" };
+        }
+        catch (e) {
+            if (e instanceof AppBridgeError && e.code === "forbidden")
+                return { ok: false, error: "cert_mismatch" };
+            return { ok: false, error: "unreachable" };
+        }
+        this.config.setRest(reg.id, cfg);
+        return { ok: true, status: await this.status(reg) };
+    }
+    disconnectRest(vaultId) {
+        this.config.setRest(vaultId, null);
+    }
+    /** Forget cached probes (after the user changed something). */
+    invalidate() {
+        this.running = null;
+        this.versionProbe = null;
+    }
+    /**
+     * Serve an op through the app, or say it belongs to the files engine.
+     * Returns null for ops the bridge does not know. `grant` is the already
+     * verified grant (vaults.ts authorizeVaultOp).
+     */
+    async serve(input) {
+        const { reg, grant, op } = input;
+        const spec = APP_OPS[op];
+        if (!spec)
+            return null;
+        const mode = op.startsWith("app_") ? "app" : spec.mode ?? "app";
+        const args = { ...input.args };
+        if (spec.dev && grant.dev_tools !== true) {
+            return { kind: "env", env: appErr("forbidden", "Developer tools are off for this vault. The owner can turn them on in the vault's settings (Developer tools).") };
+        }
+        const bounded = Array.isArray(grant.folders) && grant.folders.length > 0;
+        const filesArgs = () => {
+            const keep = new Set(spec.filesArgs ?? Object.keys(spec.params ?? {}));
+            const out = {};
+            for (const [k, v] of Object.entries(args))
+                if (keep.has(k) || k === "dry_run")
+                    out[k] = v;
+            return out;
+        };
+        if (mode === "fallback")
+            return { kind: "files", args };
+        if (mode === "untargeted" && (args.file || args.path))
+            return { kind: "files", args };
+        if (bounded && op !== "app_version") {
+            if (mode === "prefer" && !spec.noFiles)
+                return { kind: "files", args: filesArgs() };
+            return { kind: "env", env: appErr("forbidden_folder", "Obsidian app tools act on the whole vault; this run may only see some folders.") };
+        }
+        const cli = spec.cmd ? await this.cliState(reg) : null;
+        const restCfg = spec.rest ? this.config.getRest(reg.id) : null;
+        const viaCli = !!cli && cli.state === "ready";
+        if (!viaCli && !restCfg) {
+            if (mode === "prefer" && !spec.noFiles)
+                return { kind: "files", args: filesArgs() };
+            const why = offlineReason(cli?.state ?? null, !!spec.rest);
+            return { kind: "env", env: appErr("app_offline", mode === "untargeted" ? `${why} Or name the note with file= or path=.` : why) };
+        }
+        if (APP_WRITE_OPS.has(op) && args.dry_run) {
+            return { kind: "env", env: appOk(reg.id, { op, command: spec.cmd, arguments: describeArgs(args) }, { backend: viaCli ? "cli" : "rest", status: "proposed", extra: { proposal: { op, vault_id: reg.id, command: spec.cmd } } }) };
+        }
+        delete args.dry_run;
+        const run = async () => {
+            try {
+                if (viaCli)
+                    return await this.runViaCli(reg, op, spec, args, cli.bin, cli.vaultRef);
+                return await this.runViaRest(reg, op, spec, args, restCfg);
+            }
+            catch (e) {
+                if (e instanceof AppBridgeError)
+                    return appErr(e.code, e.message);
+                return appErr("app_offline", "The Obsidian app did not answer.");
+            }
+        };
+        if (!APP_WRITE_OPS.has(op))
+            return { kind: "env", env: await run() };
+        return { kind: "env", env: await this.applyOnce(reg.id, op, input.idempotencyKey ?? null, run) };
+    }
+    /** base_query: the files engine answered `unsupported`; the live app may serve it. */
+    async afterFiles(input, filesEnv) {
+        const spec = APP_OPS[input.op];
+        if (!spec || spec.mode !== "fallback")
+            return null;
+        const e = filesEnv;
+        if (!e || e.ok !== false || e.error?.code !== "unsupported")
+            return null;
+        if (Array.isArray(input.grant.folders) && input.grant.folders.length)
+            return null;
+        const cli = await this.cliState(input.reg);
+        if (cli.state !== "ready")
+            return null;
+        try {
+            return await this.runViaCli(input.reg, input.op, spec, { ...input.args }, cli.bin, cli.vaultRef);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** One write at a time per vault; a retried idempotency key returns the stored result. */
+    applyOnce(vaultId, op, key, run) {
+        const k = key ? `${vaultId}\u0000${op}\u0000${key}` : null;
+        const prev = this.writeChains.get(vaultId) ?? Promise.resolve();
+        const next = prev.catch(() => undefined).then(async () => {
+            if (k && this.applied.has(k))
+                return this.applied.get(k);
+            const env = await run();
+            if (k && env.ok === true) {
+                this.applied.set(k, env);
+                while (this.applied.size > IDEMPOTENCY_MAX)
+                    this.applied.delete(this.applied.keys().next().value);
+            }
+            return env;
+        });
+        this.writeChains.set(vaultId, next);
+        void next.finally(() => { if (this.writeChains.get(vaultId) === next)
+            this.writeChains.delete(vaultId); });
+        return next;
+    }
+    async runViaCli(reg, op, spec, args, bin, vaultRef) {
+        if (op === "app_dev_screenshot")
+            return this.screenshot(reg, bin, vaultRef, spec);
+        let argv;
+        if (op === "app_vault_open") {
+            if (Object.keys(args).length)
+                return appErr("invalid", "obsidian_vault_open takes no arguments: it opens this vault.");
+            // vault:open takes the vault's NAME (its folder name in Obsidian).
+            argv = { ok: true, argv: ["vault:open", `name=${path.basename(reg.path)}`] };
+        }
+        else {
+            argv = buildCliArgs(op, args, vaultRef);
+        }
+        if (!argv.ok)
+            return appErr("invalid", argv.message);
+        const timeoutMs = spec.timeoutMs ?? CLI_DEFAULT_TIMEOUT_MS;
+        const r = await runCli(bin, argv.argv, { timeoutMs, spawnImpl: this.o.spawnImpl });
+        const i = interpretCliOutput(r, timeoutMs);
+        if (!i.ok) {
+            if (i.code === "app_offline")
+                this.invalidate();
+            return appErr(i.code, i.message);
+        }
+        return appOk(reg.id, i.value, { backend: "cli", truncated: i.truncated, status: spec.write ? "applied" : undefined });
+    }
+    async screenshot(reg, bin, vaultRef, spec) {
+        // The image goes to a temp file the runner chooses (never a model path),
+        // is read back, then deleted.
+        const dir = path.join(tmpdir(), `melaya-obsidian-${randomBytes(6).toString("hex")}`);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = path.join(dir, "screenshot.png");
+        try {
+            const argv = buildCliArgs("app_dev_screenshot", {}, vaultRef);
+            if (!argv.ok)
+                return appErr("invalid", argv.message);
+            const timeoutMs = spec.timeoutMs ?? CLI_DEFAULT_TIMEOUT_MS;
+            const r = await runCli(bin, [...argv.argv, `path=${file}`], { timeoutMs, spawnImpl: this.o.spawnImpl, maxBytes: 16 * 1024 * 1024 });
+            const i = interpretCliOutput(r, timeoutMs);
+            if (!i.ok)
+                return appErr(i.code, i.message);
+            let data = null;
+            try {
+                const st = statSync(file);
+                if (st.isFile() && st.size > 0 && st.size <= 12 * 1024 * 1024)
+                    data = readFileSync(file);
+            }
+            catch { /* the app may have printed it instead */ }
+            if (!data) {
+                const m = /(?:data:image\/png;base64,)?([A-Za-z0-9+/]{200,}={0,2})/.exec(String(i.value ?? ""));
+                if (m)
+                    data = Buffer.from(m[1], "base64");
+            }
+            if (!data || data.length < 8 || data.readUInt32BE(0) !== 0x89504e47)
+                return appErr("unsupported", "Obsidian did not return a screenshot.");
+            return appOk(reg.id, { media_type: "image/png", data_b64: data.toString("base64"), bytes: data.length }, { backend: "cli" });
+        }
+        finally {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    async runViaRest(reg, op, spec, args, cfg) {
+        const json = (r) => {
+            const t = r.body.toString("utf-8");
+            try {
+                return JSON.parse(t);
+            }
+            catch {
+                return t;
+            }
+        };
+        const check = (r) => {
+            if (r.status === 401 || r.status === 403)
+                throw new AppBridgeError("forbidden", "The Local REST API refused the key. Reconnect it in the vault's settings.");
+            if (r.status === 404)
+                throw new AppBridgeError("not_found", "Obsidian: not found.");
+            if (r.status >= 400) {
+                const j = json(r);
+                throw new AppBridgeError("invalid", `Obsidian Local REST API: ${String(j?.message || r.status).slice(0, 300)}`);
+            }
+        };
+        const allowed = new Set([...Object.keys(spec.params ?? {})]);
+        for (const k of Object.keys(args))
+            if (!allowed.has(k))
+                throw new AppBridgeError("invalid", `Unknown argument "${k.slice(0, 40)}" for ${op}.`);
+        switch (spec.rest) {
+            case "version": {
+                const r = await this.restRequest(cfg, { method: "GET", path: "/" });
+                check(r);
+                const j = json(r);
+                return appOk(reg.id, { obsidian: j?.versions?.obsidian ?? null, plugin: j?.versions?.self ?? null }, { backend: "rest" });
+            }
+            case "active": {
+                const r = await this.restRequest(cfg, { method: "GET", path: "/active/", accept: "application/vnd.olrapi.note+json" });
+                check(r);
+                const j = json(r);
+                return appOk(reg.id, { path: j?.path ?? null, stat: j?.stat ?? null, tags: j?.tags ?? [], frontmatter: j?.frontmatter ?? {} }, { backend: "rest" });
+            }
+            case "dataview": {
+                const q = String(args.query ?? "");
+                if (!q.trim() || q.length > MAX_CODE)
+                    throw new AppBridgeError("invalid", "query must be a Dataview DQL query.");
+                const r = await this.restRequest(cfg, { method: "POST", path: "/search/", body: q, contentType: "application/vnd.olrapi.dataview.dql+txt", accept: "application/json" });
+                check(r);
+                return appOk(reg.id, json(r), { backend: "rest" });
+            }
+            case "commands": {
+                const r = await this.restRequest(cfg, { method: "GET", path: "/commands/" });
+                check(r);
+                const list = (json(r)?.commands ?? []);
+                const f = typeof args.filter === "string" ? args.filter : "";
+                return appOk(reg.id, list.filter((c) => !f || String(c.id || "").startsWith(f)), { backend: "rest" });
+            }
+            case "command": {
+                const id = String(args.id ?? "");
+                if (!/^[A-Za-z0-9:_.\-]{1,200}$/.test(id))
+                    throw new AppBridgeError("invalid", "id must be a command id (e.g. editor:toggle-bold).");
+                const r = await this.restRequest(cfg, { method: "POST", path: `/commands/${encodeURIComponent(id)}/` });
+                check(r);
+                return appOk(reg.id, { executed: id }, { backend: "rest", status: "applied" });
+            }
+            case "open": {
+                const p = typeof args.path === "string" ? args.path : "";
+                if (!p)
+                    throw new AppBridgeError("invalid", "With the Local REST API, pass path= (the exact vault path).");
+                const bad = checkVaultPath(p);
+                if (bad)
+                    throw new AppBridgeError("invalid", `path ${bad}.`);
+                const qs = args.newtab === true || args.newtab === "true" ? "?newLeaf=true" : "";
+                const r = await this.restRequest(cfg, { method: "POST", path: `/open/${p.split("/").map(encodeURIComponent).join("/")}${qs}` });
+                check(r);
+                return appOk(reg.id, { opened: p }, { backend: "rest", status: "applied" });
+            }
+            default:
+                throw new AppBridgeError("app_offline", offlineReason(null, false));
+        }
+    }
+}
+function describeArgs(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args))
+        if (k !== "dry_run")
+            out[k] = typeof v === "string" && v.length > 400 ? `${v.slice(0, 400)}…` : v;
+    return out;
+}
+export function offlineReason(cli, restPossible) {
+    const rest = restPossible ? " or connect the Local REST API plugin in the vault's settings" : "";
+    switch (cli) {
+        case "not_installed":
+            return `This needs the Obsidian app on the vault's computer with its command line interface on (Settings → General → Advanced → Command line interface)${rest}.`;
+        case "not_running":
+            return `Obsidian is not running on the vault's computer. Open Obsidian there, then retry.`;
+        case "cli_disabled":
+            return `The Obsidian command line interface is off. Turn it on in Obsidian: Settings → General → Advanced → Command line interface${rest}.`;
+        case "vault_unknown":
+            return "Obsidian on that computer does not know this folder as a vault yet. Open the folder once in Obsidian (Open folder as vault), then retry.";
+        default:
+            return restPossible
+                ? "This needs the Obsidian Local REST API plugin connected in the vault's settings."
+                : "This needs the running Obsidian app on the vault's computer.";
+    }
+}