@melaya/runner 1.1.61 → 1.1.62

package/dist/obsidianApp.d.ts

@@ -0,0 +1,324 @@
+/**
+ * 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 { type ChildProcess, type SpawnOptions } from "child_process";
+import tls from "tls";
+type ParamKind = "str" | "int" | "flag" | "json" | "code" | "url" | "vpath" | readonly string[];
+/** How an op is served.
+ *  app       only the running app has it (`app_*` ops).
+ *  prefer    Files + App: the app when reachable, else the files engine.
+ *  untargeted  files engine when the call names a note; the app's active note otherwise.
+ *  fallback  files engine first; the app when the engine says unsupported. */
+type Mode = "app" | "prefer" | "untargeted" | "fallback";
+type RestRoute = "version" | "active" | "dataview" | "commands" | "command" | "open";
+export interface AppOpSpec {
+    cmd: string | null;
+    write: boolean;
+    dev?: boolean;
+    mode?: Mode;
+    params?: Record<string, ParamKind>;
+    /** A bare `on|off` positional (`sync on`, `dev:debug off`). */
+    state?: "required" | "optional";
+    required?: string[];
+    /** No `vault=` prefix (app-wide commands). */
+    noVault?: boolean;
+    /** Append `format=json` unless the caller chose a format. */
+    json?: boolean;
+    timeoutMs?: number;
+    rest?: RestRoute;
+    /** Args the files engine accepts for a prefer/fallback op (the rest are stripped on fallback). */
+    filesArgs?: readonly string[];
+    /** Files+App op without a files implementation. */
+    noFiles?: boolean;
+}
+export declare const APP_OPS: Readonly<Record<string, AppOpSpec>>;
+/** App ops that change something (need "write" in the grant; HITL at the tool). */
+export declare const APP_WRITE_OPS: ReadonlySet<string>;
+/** Developer ops: only when the vault owner turned on "Developer tools". */
+export declare const APP_DEV_OPS: ReadonlySet<string>;
+/** Ops that only the running app serves (app_* plus Files+App ops without a files implementation). */
+export declare const APP_ONLY_OPS: ReadonlySet<string>;
+export declare function isAppOp(op: string): boolean;
+export type AppErrorCode = "app_offline" | "unsupported" | "forbidden" | "forbidden_folder" | "invalid" | "not_found";
+export declare class AppBridgeError extends Error {
+    readonly code: AppErrorCode;
+    constructor(code: AppErrorCode, message: string);
+}
+export declare function appErr(code: AppErrorCode, message: string): {
+    ok: false;
+    error: {
+        code: AppErrorCode;
+        message: string;
+        retry_after: null;
+    };
+};
+export type AppBackend = "cli" | "rest";
+export declare function appOk(vaultId: string, value: unknown, o: {
+    backend: AppBackend;
+    truncated?: boolean;
+    status?: string;
+    extra?: Record<string, unknown>;
+}): {
+    ok: true;
+} & Record<string, unknown>;
+/**
+ * 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 declare function buildCliArgs(op: string, args: Record<string, unknown>, vaultRef: string | null): {
+    ok: true;
+    argv: string[];
+} | {
+    ok: false;
+    message: string;
+};
+export declare const CLI_DEFAULT_TIMEOUT_MS = 30000;
+export declare const CLI_MAX_OUTPUT_BYTES: number;
+export interface CliRunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    truncated: boolean;
+}
+export type SpawnFn = (cmd: string, args: string[], opts: SpawnOptions) => ChildProcess;
+/** Run the CLI once: argv array, no shell, deadline, output cap (the process
+ *  is killed past either). Never rejects. */
+export declare function runCli(bin: string, argv: string[], o?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+    spawnImpl?: SpawnFn;
+    cwd?: string;
+}): Promise<CliRunResult>;
+/** 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 declare function interpretCliOutput(r: CliRunResult, timeoutMs?: number): {
+    ok: true;
+    value: unknown;
+    truncated: boolean;
+} | {
+    ok: false;
+    code: AppErrorCode;
+    message: string;
+};
+export interface HostEnv {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}
+/** 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 declare function cliCandidates(h: HostEnv): string[];
+/** A launchable CLI binary. Batch files are refused: Windows runs them
+ *  through cmd.exe, where an argument array is no longer safe. */
+export declare function findCli(h: HostEnv, exists?: (p: string) => boolean): string | null;
+/** obsidian.json: the app's own list of vaults ({vaults: {id: {path, open}}}). */
+export declare function obsidianConfigCandidates(h: HostEnv): string[];
+/** The app's id for a vault folder (what `vault=` takes), or null. */
+export declare function findObsidianVaultId(config: unknown, vaultPath: string, platform: NodeJS.Platform): {
+    id: string;
+    open: boolean;
+} | null;
+export type RunningProbe = () => Promise<boolean | 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 declare function defaultRunningProbe(platform: NodeJS.Platform, spawnImpl?: SpawnFn): RunningProbe;
+export declare const REST_PLUGIN_ID = "obsidian-local-rest-api";
+export interface RestConfig {
+    url: string;
+    apiKey: string;
+    fingerprint256: string;
+    headerName?: string;
+    connectedAt?: string;
+}
+/** Upper-case hex without separators. */
+export declare function normalizeFingerprint(fp: string): string;
+export declare function fingerprintsEqual(a: string, b: string): boolean;
+/** https on a loopback host only: the bridge never talks to another machine. */
+export declare function parseRestUrl(u: string): {
+    host: string;
+    port: number;
+} | null;
+export interface PinnedResponse {
+    status: number;
+    contentType: string;
+    body: Buffer;
+}
+export type TlsConnectFn = (opts: tls.ConnectionOptions) => tls.TLSSocket;
+/**
+ * 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 declare function pinnedRequest(cfg: Pick<RestConfig, "url" | "fingerprint256">, req: {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+}, connectImpl?: TlsConnectFn): Promise<PinnedResponse>;
+/** 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 declare function peerFingerprint(url: string, connectImpl?: TlsConnectFn, timeoutMs?: number): Promise<string>;
+export interface RestPluginSettings {
+    port: number;
+    apiKey: string;
+    certPem: string;
+    fingerprint256: string;
+    headerName: string;
+}
+/** 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 declare function readRestPluginSettings(vaultRoot: string, configDirName: string): {
+    ok: true;
+    settings: RestPluginSettings;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class AppLocalConfig {
+    readonly dir: string;
+    readonly file: string;
+    private cache;
+    constructor(dir: string);
+    private load;
+    getRest(vaultId: string): RestConfig | null;
+    setRest(vaultId: string, cfg: RestConfig | null): void;
+}
+/** What the bridge needs of a registered vault. */
+export interface AppVaultRef {
+    id: string;
+    label: string;
+    path: string;
+    configDirName: string;
+}
+/** The grant fields the bridge re-checks. */
+export interface AppGrantRef {
+    ops: string[];
+    folders: string[];
+    dev_tools?: boolean;
+}
+export type CliState = "ready" | "not_installed" | "not_running" | "cli_disabled" | "vault_unknown";
+export type RestState = "connected" | "not_configured" | "unreachable" | "cert_changed" | "key_rejected";
+export interface AppStatus {
+    cli: CliState;
+    rest: RestState;
+    version: string | null;
+    /** Capability names for the vault report: app_cli, app_rest. */
+    features: string[];
+    /** Short fingerprint of the pinned certificate (display only). */
+    restFingerprint: string | null;
+}
+export type ServeResult = {
+    kind: "env";
+    env: Record<string, unknown>;
+} | {
+    kind: "files";
+    args: Record<string, unknown>;
+};
+export interface ObsidianAppBridgeOpts {
+    /** Folder for obsidian-app.json (the vault registry's folder). */
+    dir: string;
+    log?: (m: string) => void;
+    host?: HostEnv;
+    spawnImpl?: SpawnFn;
+    runningProbe?: RunningProbe;
+    tlsConnect?: TlsConnectFn;
+    fileExists?: (p: string) => boolean;
+    /** Override where obsidian.json is read from (tests). */
+    readObsidianConfig?: () => unknown;
+}
+export declare class ObsidianAppBridge {
+    private readonly o;
+    readonly config: AppLocalConfig;
+    private readonly h;
+    private readonly runningProbe;
+    private running;
+    private versionProbe;
+    private readonly applied;
+    private readonly writeChains;
+    constructor(o: ObsidianAppBridgeOpts);
+    private bin;
+    private obsidianConfig;
+    private isRunning;
+    /** CLI state for one vault + the vault= reference. */
+    private cliState;
+    private restRequest;
+    private restState;
+    /** Live App availability for one vault (UI status row, capability report). */
+    status(reg: AppVaultRef): Promise<AppStatus>;
+    /** Connect the Local REST API of this vault from the plugin's own settings. */
+    connectRest(reg: AppVaultRef): Promise<{
+        ok: true;
+        status: AppStatus;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    disconnectRest(vaultId: string): void;
+    /** Forget cached probes (after the user changed something). */
+    invalidate(): void;
+    /**
+     * 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).
+     */
+    serve(input: {
+        reg: AppVaultRef;
+        grant: AppGrantRef;
+        op: string;
+        args: Record<string, unknown>;
+        idempotencyKey?: string | null;
+    }): Promise<ServeResult | null>;
+    /** base_query: the files engine answered `unsupported`; the live app may serve it. */
+    afterFiles(input: {
+        reg: AppVaultRef;
+        grant: AppGrantRef;
+        op: string;
+        args: Record<string, unknown>;
+    }, filesEnv: unknown): Promise<Record<string, unknown> | null>;
+    /** One write at a time per vault; a retried idempotency key returns the stored result. */
+    private applyOnce;
+    private runViaCli;
+    private screenshot;
+    private runViaRest;
+}
+export declare function offlineReason(cli: CliState | null, restPossible: boolean): string;
+export {};