@melaya/runner 1.1.61 → 1.1.63

package/dist/obsidianAppCli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `melaya-runner obsidian-rest` — connect the Obsidian Local REST API plugin
+ * of a vault registered on this computer, by hand (obsidianApp.ts).
+ *
+ * The usual path is the vault's settings in Melaya ("Obsidian app" →
+ * Connect), where the runner reads the plugin's own settings. This command is
+ * for setups where that fails (custom port, another config folder): the API
+ * key is typed HERE, never into Melaya, and the certificate's fingerprint is
+ * shown for the user to confirm before it is pinned.
+ *
+ *   melaya-runner obsidian-rest                       list vaults and their App status
+ *   melaya-runner obsidian-rest --vault "Work" [--url https://127.0.0.1:27124]
+ *   melaya-runner obsidian-rest --vault "Work" --disconnect
+ */
+export declare function obsidianRestCli(): Promise<void>;

package/dist/obsidianAppCli.js

@@ -0,0 +1,123 @@
+/**
+ * `melaya-runner obsidian-rest` — connect the Obsidian Local REST API plugin
+ * of a vault registered on this computer, by hand (obsidianApp.ts).
+ *
+ * The usual path is the vault's settings in Melaya ("Obsidian app" →
+ * Connect), where the runner reads the plugin's own settings. This command is
+ * for setups where that fails (custom port, another config folder): the API
+ * key is typed HERE, never into Melaya, and the certificate's fingerprint is
+ * shown for the user to confirm before it is pinned.
+ *
+ *   melaya-runner obsidian-rest                       list vaults and their App status
+ *   melaya-runner obsidian-rest --vault "Work" [--url https://127.0.0.1:27124]
+ *   melaya-runner obsidian-rest --vault "Work" --disconnect
+ */
+import readline from "readline";
+import { VaultRegistry } from "./vaults.js";
+import { AppLocalConfig, ObsidianAppBridge, normalizeFingerprint, parseRestUrl, peerFingerprint, pinnedRequest } from "./obsidianApp.js";
+function arg(name) {
+    const i = process.argv.indexOf(`--${name}`);
+    if (i >= 0 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--"))
+        return process.argv[i + 1];
+    const eq = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return eq ? eq.slice(name.length + 3) : null;
+}
+function ask(question, hidden = false) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        if (hidden) {
+            // Echo nothing while the key is typed.
+            rl._writeToOutput = (s) => {
+                if (s.includes(question))
+                    process.stdout.write(question);
+            };
+        }
+        rl.question(question, (a) => {
+            rl.close();
+            if (hidden)
+                process.stdout.write("\n");
+            resolve(a.trim());
+        });
+    });
+}
+export async function obsidianRestCli() {
+    const registry = new VaultRegistry();
+    registry.load();
+    const vaults = registry.list();
+    const want = arg("vault");
+    if (!want) {
+        if (!vaults.length) {
+            console.log("No Obsidian vault is registered on this computer. Connect one in Melaya: Connectors → Obsidian.");
+            return;
+        }
+        const bridge = new ObsidianAppBridge({ dir: registry.dir });
+        for (const v of vaults) {
+            const st = await bridge.status(v).catch(() => null);
+            console.log(`${v.label} (${v.id})  CLI: ${st?.cli ?? "?"}  Local REST API: ${st?.rest ?? "?"}`);
+        }
+        console.log("\nConnect a vault's Local REST API: melaya-runner obsidian-rest --vault \"<name>\"");
+        return;
+    }
+    const reg = vaults.find((v) => v.id === want) ?? vaults.find((v) => v.label.toLowerCase() === want.toLowerCase());
+    if (!reg) {
+        console.error(`No vault named "${want}" is registered on this computer.`);
+        process.exitCode = 1;
+        return;
+    }
+    const config = new AppLocalConfig(registry.dir);
+    if (process.argv.includes("--disconnect")) {
+        config.setRest(reg.id, null);
+        console.log(`Disconnected the Local REST API of "${reg.label}". The key was removed from this computer.`);
+        return;
+    }
+    const url = arg("url") || "https://127.0.0.1:27124";
+    if (!parseRestUrl(url)) {
+        console.error("The address must be https on this computer, e.g. https://127.0.0.1:27124");
+        process.exitCode = 1;
+        return;
+    }
+    let fp;
+    try {
+        fp = await peerFingerprint(url);
+    }
+    catch {
+        console.error(`Nothing answers at ${url}. Open Obsidian with the Local REST API plugin on (HTTPS server enabled).`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\nCertificate presented at ${url}`);
+    console.log(`SHA-256 ${fp.match(/.{2}/g)?.join(":")}`);
+    console.log("Compare it with the plugin's certificate (Obsidian → Settings → Local REST API).");
+    const yes = (await ask("Trust this certificate for this vault? [y/N] ")).toLowerCase();
+    if (yes !== "y" && yes !== "yes") {
+        console.log("Not connected.");
+        return;
+    }
+    const apiKey = await ask("API key (from the plugin's settings; stays on this computer): ", true);
+    if (apiKey.length < 16 || /\s/.test(apiKey)) {
+        console.error("That does not look like the plugin's API key.");
+        process.exitCode = 1;
+        return;
+    }
+    const cfg = { url, apiKey, fingerprint256: normalizeFingerprint(fp), headerName: "Authorization", connectedAt: new Date().toISOString() };
+    try {
+        const r = await pinnedRequest(cfg, { method: "GET", path: "/", headers: { Authorization: `Bearer ${apiKey}` }, timeoutMs: 8000 });
+        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) {
+            console.error("The plugin refused that key.");
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch {
+        console.error("The connection failed after the certificate check.");
+        process.exitCode = 1;
+        return;
+    }
+    config.setRest(reg.id, cfg);
+    console.log(`Connected "${reg.label}". Agents can now use the Obsidian app tools that need the Local REST API.`);
+}

package/dist/vaultMirror.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Cloud copy of device vaults — the runner's coordination side
+ * (docs/plans/obsidian-vault-connector.md §6.4, S4).
+ *
+ * When the owner sets a device vault's policy to `storage: mirror`, the server
+ * pushes `runner:vault-mirror {vaultId, enabled, capability, expiresAt}` to the
+ * computer that holds it (again on every reconnect). The capability is a
+ * mirror-scoped Ed25519 token (aud `vault-mirror`, one vault, ≤ 10 minutes):
+ * it lives in this process's memory only and is renewed over the socket
+ * (`runner:vault-mirror-renew`), never written to disk, never logged.
+ *
+ * This class decides WHEN to sync; the Python host (localVault.py →
+ * localVaultMirror.py) does the round itself over HTTPS:
+ *   - after an index change (host status with a new indexRev), debounced;
+ *   - when a capability arrives (enable, reconnect: uploads the device journal
+ *     written while offline);
+ *   - every 10 minutes (settings files are not watched);
+ *   - after a resume from sleep: a full stat reconciliation first (`changed`
+ *     with null), since fs.watch misses changes made while asleep.
+ * One sync runs at a time (all vaults); requests for a vault that is already
+ * queued or running coalesce into one more round.
+ *
+ * Status goes to the server as `runner:vault-mirror-status {vaultId, state,
+ * pending, error?}`; the builder reports each published revision itself.
+ */
+import type { VaultHostStatusEvent, VaultHostTransport } from "./vaults.js";
+export type MirrorState = "syncing" | "ready" | "partial" | "retry" | "busy" | "error" | "quota" | "auth" | "off";
+export interface MirrorStatus {
+    vaultId: string;
+    state: MirrorState;
+    pending?: number;
+    error?: string;
+    publishedSeq?: number;
+    replicaRev?: number;
+}
+export interface VaultMirrorOpts {
+    host: VaultHostTransport;
+    /** The vault is registered (and opened) on this runner. */
+    isRegistered: (vaultId: string) => boolean;
+    /** https base of the mirror routes for one vault (server proxy). */
+    apiBase: (vaultId: string) => string;
+    /** Socket emit (renew requests, status). */
+    emit: (event: string, payload: Record<string, unknown>) => void;
+    log?: (m: string) => void;
+    now?: () => number;
+    debounceMs?: number;
+    periodicMs?: number;
+    tickMs?: number;
+    /** Start the periodic timer (off in unit tests, which call tick()). */
+    timers?: boolean;
+}
+export declare class VaultMirrorManager {
+    private readonly o;
+    private readonly grants;
+    private readonly due;
+    private readonly lastSync;
+    private readonly lastIndexRev;
+    private readonly failures;
+    private readonly renewAsked;
+    private readonly status;
+    private running;
+    private wake;
+    private ticker;
+    private lastTick;
+    private stopped;
+    constructor(o: VaultMirrorOpts);
+    private now;
+    private get debounceMs();
+    private get periodicMs();
+    private get tickMs();
+    /** Vaults with a live mirror capability on this runner. */
+    mirrored(): string[];
+    latest(vaultId: string): MirrorStatus | undefined;
+    /** Statuses to re-send after a reconnect. */
+    latestStatuses(): MirrorStatus[];
+    /** runner:vault-mirror */
+    setGrant(p: {
+        vaultId?: unknown;
+        enabled?: unknown;
+        capability?: unknown;
+        expiresAt?: unknown;
+    }): void;
+    /** Index status from the host: a new revision means files changed. */
+    onIndexStatus(ev: VaultHostStatusEvent): void;
+    /** The vault was unregistered from this runner. */
+    forget(vaultId: string): void;
+    /** Ask for a round of `vaultId` in `delayMs` (an earlier request wins). */
+    schedule(vaultId: string, delayMs: number): void;
+    /** Periodic housekeeping: sleep detection and the 10-minute round. */
+    tick(): void;
+    /** Resolves once nothing is running or due now (tests, shutdown). */
+    idle(): Promise<void>;
+    stop(): void;
+    private startTicker;
+    private nextDue;
+    private arm;
+    private pump;
+    private report;
+    private requestRenew;
+    private backoff;
+    private runOne;
+}
+/** Server proxy base for one vault's mirror routes. */
+export declare function mirrorApiBase(serverHttpBase: string, vaultId: string): string;

package/dist/vaultMirror.js

@@ -0,0 +1,305 @@
+/**
+ * Cloud copy of device vaults — the runner's coordination side
+ * (docs/plans/obsidian-vault-connector.md §6.4, S4).
+ *
+ * When the owner sets a device vault's policy to `storage: mirror`, the server
+ * pushes `runner:vault-mirror {vaultId, enabled, capability, expiresAt}` to the
+ * computer that holds it (again on every reconnect). The capability is a
+ * mirror-scoped Ed25519 token (aud `vault-mirror`, one vault, ≤ 10 minutes):
+ * it lives in this process's memory only and is renewed over the socket
+ * (`runner:vault-mirror-renew`), never written to disk, never logged.
+ *
+ * This class decides WHEN to sync; the Python host (localVault.py →
+ * localVaultMirror.py) does the round itself over HTTPS:
+ *   - after an index change (host status with a new indexRev), debounced;
+ *   - when a capability arrives (enable, reconnect: uploads the device journal
+ *     written while offline);
+ *   - every 10 minutes (settings files are not watched);
+ *   - after a resume from sleep: a full stat reconciliation first (`changed`
+ *     with null), since fs.watch misses changes made while asleep.
+ * One sync runs at a time (all vaults); requests for a vault that is already
+ * queued or running coalesce into one more round.
+ *
+ * Status goes to the server as `runner:vault-mirror-status {vaultId, state,
+ * pending, error?}`; the builder reports each published revision itself.
+ */
+const VAULT_ID_RE = /^vlt_[A-Za-z0-9]{1,64}$/;
+const RENEW_MARGIN_S = 120;
+const MAX_BUDGET_S = 600;
+const MAX_BACKOFF_MS = 30 * 60_000;
+export class VaultMirrorManager {
+    o;
+    grants = new Map();
+    due = new Map();
+    lastSync = new Map();
+    lastIndexRev = new Map();
+    failures = new Map();
+    renewAsked = new Map();
+    status = new Map();
+    running = null;
+    wake = null;
+    ticker = null;
+    lastTick;
+    stopped = false;
+    constructor(o) {
+        this.o = o;
+        this.lastTick = this.now();
+    }
+    now() { return (this.o.now ?? Date.now)(); }
+    get debounceMs() { return this.o.debounceMs ?? 5_000; }
+    get periodicMs() { return this.o.periodicMs ?? 10 * 60_000; }
+    get tickMs() { return this.o.tickMs ?? 30_000; }
+    /** Vaults with a live mirror capability on this runner. */
+    mirrored() { return Array.from(this.grants.keys()); }
+    latest(vaultId) { return this.status.get(vaultId); }
+    /** Statuses to re-send after a reconnect. */
+    latestStatuses() { return Array.from(this.status.values()); }
+    /** runner:vault-mirror */
+    setGrant(p) {
+        const vaultId = String(p?.vaultId || "");
+        if (!VAULT_ID_RE.test(vaultId) || this.stopped)
+            return;
+        if (p?.enabled === false) {
+            const had = this.grants.delete(vaultId);
+            this.due.delete(vaultId);
+            this.renewAsked.delete(vaultId);
+            if (had || this.status.has(vaultId)) {
+                this.o.host.request("mirror_drop", { vaultId }, 30_000).catch(() => { });
+            }
+            this.report({ vaultId, state: "off" });
+            this.status.delete(vaultId);
+            return;
+        }
+        const capability = typeof p?.capability === "string" ? p.capability : "";
+        const exp = Number(p?.expiresAt);
+        if (!capability || !Number.isFinite(exp))
+            return;
+        this.grants.set(vaultId, { capability, exp });
+        this.renewAsked.delete(vaultId);
+        this.startTicker();
+        this.schedule(vaultId, 0);
+    }
+    /** Index status from the host: a new revision means files changed. */
+    onIndexStatus(ev) {
+        if (!this.grants.has(ev.vaultId) || ev.status !== "ready")
+            return;
+        const rev = Number(ev.indexRev);
+        if (!Number.isFinite(rev))
+            return;
+        const prev = this.lastIndexRev.get(ev.vaultId);
+        this.lastIndexRev.set(ev.vaultId, rev);
+        if (prev === undefined || rev !== prev)
+            this.schedule(ev.vaultId, this.debounceMs);
+    }
+    /** The vault was unregistered from this runner. */
+    forget(vaultId) {
+        this.grants.delete(vaultId);
+        this.due.delete(vaultId);
+        this.status.delete(vaultId);
+        this.lastIndexRev.delete(vaultId);
+    }
+    /** Ask for a round of `vaultId` in `delayMs` (an earlier request wins). */
+    schedule(vaultId, delayMs) {
+        if (this.stopped || !this.grants.has(vaultId))
+            return;
+        const at = this.now() + Math.max(0, delayMs);
+        const cur = this.due.get(vaultId);
+        if (cur === undefined || at < cur)
+            this.due.set(vaultId, at);
+        this.arm();
+    }
+    /** Periodic housekeeping: sleep detection and the 10-minute round. */
+    tick() {
+        const now = this.now();
+        const gap = now - this.lastTick;
+        this.lastTick = now;
+        if (gap > this.tickMs * 3) {
+            // Resumed from sleep (or the clock jumped): fs.watch missed whatever
+            // happened meanwhile. A full stat-only reconciliation, then a round.
+            for (const vaultId of this.grants.keys()) {
+                if (!this.o.isRegistered(vaultId))
+                    continue;
+                this.o.host.request("changed", { vaultId, paths: null }, 10 * 60_000).catch(() => { });
+                this.schedule(vaultId, this.debounceMs * 2);
+            }
+        }
+        for (const vaultId of this.grants.keys()) {
+            if (now - (this.lastSync.get(vaultId) ?? 0) >= this.periodicMs)
+                this.schedule(vaultId, 0);
+        }
+        this.arm();
+    }
+    /** Resolves once nothing is running or due now (tests, shutdown). */
+    async idle() {
+        for (let i = 0; i < 100; i++) {
+            if (this.running) {
+                await this.running;
+                continue;
+            }
+            const next = this.nextDue();
+            if (!next || next.at > this.now())
+                return;
+            this.pump();
+        }
+    }
+    stop() {
+        this.stopped = true;
+        if (this.wake)
+            clearTimeout(this.wake);
+        if (this.ticker)
+            clearInterval(this.ticker);
+        this.wake = null;
+        this.ticker = null;
+    }
+    // ── internals ──
+    startTicker() {
+        if (this.ticker || this.o.timers === false)
+            return;
+        this.lastTick = this.now();
+        this.ticker = setInterval(() => this.tick(), this.tickMs);
+        this.ticker.unref?.();
+    }
+    nextDue() {
+        let best = null;
+        for (const [vaultId, at] of this.due)
+            if (!best || at < best.at)
+                best = { vaultId, at };
+        return best;
+    }
+    arm() {
+        if (this.stopped || this.running)
+            return;
+        const next = this.nextDue();
+        if (this.wake) {
+            clearTimeout(this.wake);
+            this.wake = null;
+        }
+        if (!next)
+            return;
+        const delay = Math.max(0, next.at - this.now());
+        if (delay === 0) {
+            queueMicrotask(() => this.pump());
+            return;
+        }
+        if (this.o.timers === false)
+            return; // tests drive time
+        this.wake = setTimeout(() => { this.wake = null; this.pump(); }, delay);
+        this.wake.unref?.();
+    }
+    pump() {
+        if (this.running || this.stopped)
+            return;
+        const next = this.nextDue();
+        if (!next || next.at > this.now()) {
+            this.arm();
+            return;
+        }
+        this.due.delete(next.vaultId);
+        this.running = this.runOne(next.vaultId)
+            .catch((e) => this.o.log?.(`mirror ${next.vaultId}: ${String(e?.message || e).slice(0, 200)}`))
+            .finally(() => { this.running = null; this.arm(); });
+    }
+    report(s) {
+        const prev = this.status.get(s.vaultId);
+        this.status.set(s.vaultId, s);
+        if (prev && prev.state === s.state && prev.pending === s.pending && prev.error === s.error)
+            return;
+        const payload = { vaultId: s.vaultId, state: s.state };
+        if (s.pending !== undefined)
+            payload.pending = s.pending;
+        if (s.error)
+            payload.error = s.error.slice(0, 300);
+        if (s.replicaRev !== undefined)
+            payload.replicaRev = s.replicaRev;
+        try {
+            this.o.emit("runner:vault-mirror-status", payload);
+        }
+        catch { /* disconnected */ }
+    }
+    requestRenew(vaultId) {
+        const asked = this.renewAsked.get(vaultId) ?? 0;
+        if (this.now() - asked < 60_000)
+            return;
+        this.renewAsked.set(vaultId, this.now());
+        try {
+            this.o.emit("runner:vault-mirror-renew", { vaultId });
+        }
+        catch { /* disconnected: re-pushed on hello */ }
+    }
+    backoff(vaultId, baseMs) {
+        const n = (this.failures.get(vaultId) ?? 0) + 1;
+        this.failures.set(vaultId, n);
+        return Math.min(MAX_BACKOFF_MS, baseMs * 2 ** Math.min(n - 1, 10));
+    }
+    async runOne(vaultId) {
+        const grant = this.grants.get(vaultId);
+        if (!grant)
+            return;
+        if (!this.o.isRegistered(vaultId)) {
+            this.schedule(vaultId, 60_000);
+            return;
+        }
+        const remaining = grant.exp - Math.floor(this.now() / 1000);
+        if (remaining < RENEW_MARGIN_S) {
+            // A round needs a capability that outlives it: renew first; the next
+            // grant schedules the round.
+            this.requestRenew(vaultId);
+            return;
+        }
+        this.report({ vaultId, state: "syncing", pending: this.status.get(vaultId)?.pending });
+        const budget = Math.max(30, Math.min(MAX_BUDGET_S, remaining - 60));
+        let r;
+        try {
+            r = await this.o.host.request("mirror_sync", {
+                vaultId,
+                token: grant.capability,
+                apiBase: this.o.apiBase(vaultId),
+                budgetSeconds: budget,
+            }, (budget + 180) * 1000);
+        }
+        catch (e) {
+            // host restarting / vault not reopened yet: try again shortly
+            this.report({ vaultId, state: "retry", error: String(e?.message || "vault_host_failed").slice(0, 120) });
+            this.schedule(vaultId, this.backoff(vaultId, 30_000));
+            return;
+        }
+        this.lastSync.set(vaultId, this.now());
+        const state = String(r?.state || "error");
+        const pending = Number.isFinite(Number(r?.pending)) ? Number(r.pending) : undefined;
+        const base = { vaultId, pending, replicaRev: Number.isFinite(Number(r?.replicaRev)) ? Number(r.replicaRev) : undefined };
+        switch (state) {
+            case "ready":
+                this.failures.delete(vaultId);
+                this.report({ ...base, state: "ready" });
+                break;
+            case "partial":
+                // more to send (budget or journal batch): continue right away
+                this.report({ ...base, state: "syncing" });
+                this.schedule(vaultId, 0);
+                break;
+            case "busy":
+                this.schedule(vaultId, 5_000);
+                break;
+            case "auth":
+                this.report({ ...base, state: "auth" });
+                this.grants.set(vaultId, { ...grant, exp: 0 });
+                this.requestRenew(vaultId);
+                break;
+            case "quota":
+                this.report({ ...base, state: "quota", error: String(r?.error || "quota") });
+                this.schedule(vaultId, this.backoff(vaultId, 15 * 60_000));
+                break;
+            case "retry":
+                this.report({ ...base, state: "retry" });
+                this.schedule(vaultId, Math.max(this.debounceMs, this.backoff(vaultId, 15_000)));
+                break;
+            default:
+                this.report({ ...base, state: "error", error: String(r?.error || "sync failed") });
+                this.schedule(vaultId, this.backoff(vaultId, 60_000));
+        }
+    }
+}
+/** Server proxy base for one vault's mirror routes. */
+export function mirrorApiBase(serverHttpBase, vaultId) {
+    return `${serverHttpBase.replace(/\/+$/, "")}/api/v1/vault-api/mirror/${encodeURIComponent(vaultId)}`;
+}