@omgbase/sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/bin.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { runFsMirror } from "./mirror.js";
+// `omgbase-sync` — the standalone synchronizer (ADR-014). A thin wrapper over
+// `runFsMirror`: mirror a filesystem directory against an omgbase repo served
+// over MCP (default server `omg mcp -C <root>`). Identical to `omg sync
+// --server <cmd>` for callers that don't ship the full `omg` CLI.
+//
+//   omgbase-sync --root ./vault              # ingest the tree into the served repo
+//   omgbase-sync --root ./vault --out        # also export engine-authored changes back
+//   omgbase-sync --root ./vault --watch      # stay live: mirror edits as they land
+//   omgbase-sync --root ./vault --server "omg mcp -C ./vault"   # custom / remote server command
+function usage() {
+    process.stderr.write("usage: omgbase-sync --root <dir> [--server \"<cmd>\"] [--out] [--watch]\n" +
+        "  --root <dir>     filesystem directory to mirror (required)\n" +
+        "  --server <cmd>   MCP server command to spawn (default: omg mcp -C <root>)\n" +
+        "  --out            also export engine-authored changes back to the directory\n" +
+        "  --watch          stay live and mirror edits as they land\n");
+}
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            root: { type: "string" },
+            server: { type: "string" },
+            out: { type: "boolean" },
+            watch: { type: "boolean" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help || !values.root) {
+        usage();
+        process.exit(values.help ? 0 : 2);
+    }
+    const root = resolve(values.root);
+    const server = (values.server ?? `omg mcp -C ${root}`).split(/\s+/).filter(Boolean);
+    await runFsMirror({
+        server,
+        root,
+        ...(values.watch ? { watch: true } : {}),
+        ...(values.out ? { out: true } : {}),
+        log: (msg) => process.stderr.write(`[omgbase-sync] ${msg}\n`),
+    });
+}
+main().catch((err) => {
+    process.stderr.write(`[omgbase-sync] fatal: ${String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/src/coordinator.d.ts

@@ -0,0 +1,43 @@
+import type { SyncSource, SourceWatch } from "@omgbase/core";
+import type { EngineClient } from "./engine-client.js";
+export interface SyncInSummary {
+    ingested: string[];
+    suppressed: string[];
+    conflicted: string[];
+    deleted: string[];
+}
+export interface SyncOutSummary {
+    cursor: number;
+    written: string[];
+    removed: string[];
+}
+export declare class Coordinator {
+    private readonly engine;
+    private readonly source;
+    constructor(engine: EngineClient, source: SyncSource);
+    /** source → engine: ingest the source's full current scope (initial sync). */
+    syncIn(): Promise<SyncInSummary>;
+    /**
+     * source → engine: reconcile a set of changed paths (e.g. a watch batch). A
+     * path the source no longer has (`fetch` → null) is mirrored as a deletion.
+     */
+    reconcile(paths: string[]): Promise<SyncInSummary>;
+    /**
+     * engine → source: write engine-authored changes out to the source. Walks the
+     * commit feed from `cursor` (paging through `truncated`), skipping
+     * observed-origin commits (they originated from a source — §6), and writes
+     * each changed doc's current bytes to the source (or removes a tombstoned one).
+     * Requires a write-through source; a read-only source exports nothing.
+     */
+    syncOut(cursor?: number): Promise<SyncOutSummary>;
+    /**
+     * Live source→engine sync: subscribe to the source's change batches and
+     * reconcile each. Returns the subscription (call `.stop()`), or null if the
+     * source cannot watch. Reconcile runs off the batch callback; `onSummary`
+     * observes each batch's result, `onError` any failure.
+     */
+    watchIn(handlers?: {
+        onSummary?: (s: SyncInSummary) => void;
+        onError?: (err: unknown) => void;
+    }): Promise<SourceWatch | null>;
+}

package/dist/src/coordinator.js

@@ -0,0 +1,95 @@
+export class Coordinator {
+    engine;
+    source;
+    constructor(engine, source) {
+        this.engine = engine;
+        this.source = source;
+    }
+    /** source → engine: ingest the source's full current scope (initial sync). */
+    async syncIn() {
+        const entries = await this.source.enumerate();
+        return this.reconcile(entries.map((e) => e.path));
+    }
+    /**
+     * source → engine: reconcile a set of changed paths (e.g. a watch batch). A
+     * path the source no longer has (`fetch` → null) is mirrored as a deletion.
+     */
+    async reconcile(paths) {
+        const files = [];
+        const gonePaths = [];
+        for (const path of paths) {
+            const item = await this.source.fetch(path);
+            if (item)
+                files.push({ path, content: item.content });
+            else
+                gonePaths.push(path);
+        }
+        const summary = { ingested: [], suppressed: [], conflicted: [], deleted: [] };
+        if (files.length > 0) {
+            for (const r of await this.engine.observeMany(files)) {
+                if (r.echo)
+                    summary.suppressed.push(r.path);
+                else if (r.conflicted)
+                    summary.conflicted.push(r.path);
+                else
+                    summary.ingested.push(r.path);
+            }
+        }
+        for (const path of gonePaths) {
+            const d = await this.engine.observeDelete(path);
+            if (d.deleted)
+                summary.deleted.push(path);
+        }
+        return summary;
+    }
+    /**
+     * engine → source: write engine-authored changes out to the source. Walks the
+     * commit feed from `cursor` (paging through `truncated`), skipping
+     * observed-origin commits (they originated from a source — §6), and writes
+     * each changed doc's current bytes to the source (or removes a tombstoned one).
+     * Requires a write-through source; a read-only source exports nothing.
+     */
+    async syncOut(cursor) {
+        const written = [];
+        const removed = [];
+        let cur = cursor ?? 0;
+        if (!this.source.write)
+            return { cursor: cur, written, removed }; // read-only source
+        for (;;) {
+            const page = await this.engine.changesSince(cur);
+            for (const digest of page.digests) {
+                if (digest.origin === "observed")
+                    continue; // came from a source; don't echo back
+                for (const rev of digest.revisions) {
+                    const doc = await this.engine.readDoc(rev.path);
+                    if (doc) {
+                        await this.source.write(rev.path, doc.content);
+                        written.push(rev.path);
+                    }
+                    else if (this.source.remove) {
+                        await this.source.remove(rev.path);
+                        removed.push(rev.path);
+                    }
+                }
+            }
+            cur = page.cursor;
+            if (!page.truncated)
+                break;
+        }
+        return { cursor: cur, written, removed };
+    }
+    /**
+     * Live source→engine sync: subscribe to the source's change batches and
+     * reconcile each. Returns the subscription (call `.stop()`), or null if the
+     * source cannot watch. Reconcile runs off the batch callback; `onSummary`
+     * observes each batch's result, `onError` any failure.
+     */
+    async watchIn(handlers = {}) {
+        if (!this.source.watch)
+            return null;
+        return this.source.watch((paths) => {
+            this.reconcile(paths).then((s) => handlers.onSummary?.(s), (err) => handlers.onError?.(err));
+        });
+    }
+}
+//# sourceMappingURL=coordinator.js.map

package/dist/src/engine-client.d.ts

@@ -0,0 +1,48 @@
+import { type Store, type ObserveResult, type ObserveDeleteResult, type CommitDigest } from "@omgbase/core";
+export interface ChangesPage {
+    digests: CommitDigest[];
+    cursor: number;
+    truncated: boolean;
+    /** the repo's current max commit seq — cursor > head means the cursor came from another repo/server */
+    head?: number;
+}
+export interface DocBytes {
+    content: string;
+    /** hex of the doc's current rendered/file hash (matches changes_since contentHash). */
+    contentHash: string;
+}
+export interface EngineClient {
+    /** Push whole-file bytes in as observed commits (echo-suppressed engine-side). */
+    observeMany(files: {
+        path: string;
+        content: string;
+    }[]): Promise<ObserveResult[]>;
+    /** Mirror a source-side deletion: tombstone the doc (observed). */
+    observeDelete(path: string): Promise<ObserveDeleteResult>;
+    /** The repo-wide commit feed after a cursor (for the export direction). */
+    changesSince(cursor?: number, opts?: {
+        origin?: "api" | "observed" | "import";
+        limit?: number;
+    }): Promise<ChangesPage>;
+    /** Current whole-file bytes + content hash for a path, or null if absent. */
+    readDoc(path: string): Promise<DocBytes | null>;
+    close(): Promise<void>;
+}
+/** In-process EngineClient: calls @omgbase/core directly against an open Store.
+ *  Used by the local watcher/sync (no self-MCP-loop) and by tests. */
+export declare class InProcessEngineClient implements EngineClient {
+    private readonly store;
+    private readonly repoId;
+    constructor(store: Store, repoId: string);
+    observeMany(files: {
+        path: string;
+        content: string;
+    }[]): Promise<ObserveResult[]>;
+    observeDelete(path: string): Promise<ObserveDeleteResult>;
+    changesSince(cursor?: number, opts?: {
+        origin?: "api" | "observed" | "import";
+        limit?: number;
+    }): Promise<ChangesPage>;
+    readDoc(path: string): Promise<DocBytes | null>;
+    close(): Promise<void>;
+}

package/dist/src/engine-client.js

@@ -0,0 +1,40 @@
+import { observeMany, observeDelete, changesSince, docsRead, } from "@omgbase/core";
+/** In-process EngineClient: calls @omgbase/core directly against an open Store.
+ *  Used by the local watcher/sync (no self-MCP-loop) and by tests. */
+export class InProcessEngineClient {
+    store;
+    repoId;
+    constructor(store, repoId) {
+        this.store = store;
+        this.repoId = repoId;
+    }
+    observeMany(files) {
+        return Promise.resolve(observeMany(this.store, this.repoId, files));
+    }
+    observeDelete(path) {
+        return Promise.resolve(observeDelete(this.store, this.repoId, path));
+    }
+    changesSince(cursor, opts) {
+        return Promise.resolve(changesSince(this.store, this.repoId, {
+            ...(cursor !== undefined ? { cursor } : {}),
+            ...(opts?.origin ? { origin: opts.origin } : {}),
+            ...(opts?.limit !== undefined ? { limit: opts.limit } : {}),
+        }));
+    }
+    readDoc(path) {
+        const row = this.store.db
+            .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
+            .get(this.repoId, path);
+        if (!row)
+            return Promise.resolve(null);
+        const res = docsRead(this.store, row.doc_id);
+        if (!res)
+            return Promise.resolve(null);
+        return Promise.resolve({ content: res.content, contentHash: row.file_hash?.toString("hex") ?? "" });
+    }
+    close() {
+        // The store's lifetime is owned by the caller (it may serve other work).
+        return Promise.resolve();
+    }
+}
+//# sourceMappingURL=engine-client.js.map

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { type EngineClient, type ChangesPage, type DocBytes, InProcessEngineClient } from "./engine-client.js";
+export { McpEngineClient, connectStdioEngine, connectHttpEngine } from "./mcp-engine-client.js";
+export { Coordinator, type SyncInSummary, type SyncOutSummary } from "./coordinator.js";
+export { runFsMirror, type FsMirrorOptions } from "./mirror.js";

package/dist/src/index.js

@@ -0,0 +1,9 @@
+// @omgbase/sync — a standalone store-to-store synchronizer (ADR-014).
+// The Coordinator reconciles a SyncSource (external store, via the adapter
+// protocol) with an omgbase repo reached through an EngineClient seam:
+// InProcessEngineClient (local, direct Store) or McpEngineClient (remote, MCP).
+export { InProcessEngineClient } from "./engine-client.js";
+export { McpEngineClient, connectStdioEngine, connectHttpEngine } from "./mcp-engine-client.js";
+export { Coordinator } from "./coordinator.js";
+export { runFsMirror } from "./mirror.js";
+//# sourceMappingURL=index.js.map

package/dist/src/mcp-engine-client.d.ts

@@ -0,0 +1,39 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type ObserveResult, type ObserveDeleteResult } from "@omgbase/core";
+import type { EngineClient, ChangesPage, DocBytes } from "./engine-client.js";
+/** Wraps a connected MCP SDK Client, calling the engine's sync tools. */
+export declare class McpEngineClient implements EngineClient {
+    private readonly client;
+    constructor(client: Client);
+    /** Call any MCP tool and return its parsed JSON result. Throws on a tool
+     *  error (the message carries the engine error code) or non-JSON output. The
+     *  general-purpose call the CLI's `--server` mode uses for arbitrary tools. */
+    callTool<T>(name: string, args: Record<string, unknown>): Promise<T>;
+    observeMany(files: {
+        path: string;
+        content: string;
+    }[]): Promise<ObserveResult[]>;
+    observeDelete(path: string): Promise<ObserveDeleteResult>;
+    changesSince(cursor?: number, opts?: {
+        origin?: "api" | "observed" | "import";
+        limit?: number;
+    }): Promise<ChangesPage>;
+    readDoc(path: string): Promise<DocBytes | null>;
+    close(): Promise<void>;
+}
+/** Connect to an omgbase MCP server over stdio by spawning `command args`
+ *  (e.g. `omg mcp -C /vault`). Returns a ready EngineClient. */
+export declare function connectStdioEngine(spec: {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}): Promise<McpEngineClient>;
+/** Connect to an omgbase MCP server over Streamable HTTP at `url`. The full URL
+ *  (including any base path) is used verbatim, so a secret-prefixed endpoint
+ *  like `https://host/k/<secret>/mcp` authenticates by the path alone. Extra
+ *  `headers` are sent on every request (for hosts that need auth beyond the
+ *  path). Returns a ready EngineClient. */
+export declare function connectHttpEngine(spec: {
+    url: string;
+    headers?: Record<string, string>;
+}): Promise<McpEngineClient>;

package/dist/src/mcp-engine-client.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { VERSION } from "@omgbase/core";
+/** Wraps a connected MCP SDK Client, calling the engine's sync tools. */
+export class McpEngineClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Call any MCP tool and return its parsed JSON result. Throws on a tool
+     *  error (the message carries the engine error code) or non-JSON output. The
+     *  general-purpose call the CLI's `--server` mode uses for arbitrary tools. */
+    async callTool(name, args) {
+        const res = (await this.client.callTool({ name, arguments: args }));
+        const text = res.content?.find((c) => c.type === "text")?.text ?? "";
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`tool ${name} returned non-JSON: ${text.slice(0, 200)}`);
+        }
+        if (res.isError) {
+            const err = body;
+            throw new Error(`tool ${name} failed: ${err.error ?? "error"} — ${err.message ?? text.slice(0, 200)}`);
+        }
+        return body;
+    }
+    observeMany(files) {
+        return this.callTool("observe_many", { files });
+    }
+    observeDelete(path) {
+        return this.callTool("observe_delete", { path });
+    }
+    changesSince(cursor, opts) {
+        return this.callTool("changes_since", {
+            ...(cursor !== undefined ? { cursor } : {}),
+            ...(opts?.origin ? { origin: opts.origin } : {}),
+            ...(opts?.limit !== undefined ? { limit: opts.limit } : {}),
+        });
+    }
+    async readDoc(path) {
+        try {
+            const res = await this.callTool("docs_read", { path });
+            return { content: res.content, contentHash: createHash("sha256").update(res.content, "utf8").digest("hex") };
+        }
+        catch {
+            // doc_missing (or any read failure) → treat as absent.
+            return null;
+        }
+    }
+    async close() {
+        await this.client.close();
+    }
+}
+/** Connect to an omgbase MCP server over stdio by spawning `command args`
+ *  (e.g. `omg mcp -C /vault`). Returns a ready EngineClient. */
+export async function connectStdioEngine(spec) {
+    const client = new Client({ name: "omgbase-sync", version: VERSION });
+    const transport = new StdioClientTransport({
+        command: spec.command,
+        args: spec.args ?? [],
+        ...(spec.env ? { env: spec.env } : {}),
+    });
+    await client.connect(transport);
+    return new McpEngineClient(client);
+}
+/** Connect to an omgbase MCP server over Streamable HTTP at `url`. The full URL
+ *  (including any base path) is used verbatim, so a secret-prefixed endpoint
+ *  like `https://host/k/<secret>/mcp` authenticates by the path alone. Extra
+ *  `headers` are sent on every request (for hosts that need auth beyond the
+ *  path). Returns a ready EngineClient. */
+export async function connectHttpEngine(spec) {
+    const client = new Client({ name: "omgbase-sync", version: VERSION });
+    // The transport's `sessionId` getter is `string | undefined`, which trips the
+    // Transport interface's optional `sessionId?: string` under
+    // exactOptionalPropertyTypes; the value is only ever read by the SDK.
+    const transport = new StreamableHTTPClientTransport(new URL(spec.url), {
+        ...(spec.headers && Object.keys(spec.headers).length > 0 ? { requestInit: { headers: spec.headers } } : {}),
+    });
+    await client.connect(transport);
+    return new McpEngineClient(client);
+}
+//# sourceMappingURL=mcp-engine-client.js.map

package/dist/src/mirror.d.ts

@@ -0,0 +1,18 @@
+export interface FsMirrorOptions {
+    /** MCP server command argv, e.g. ["omg","mcp","-C","/vault"]. */
+    server: string[];
+    /** Filesystem directory to mirror (absolute). */
+    root: string;
+    /** Stay live after the initial sync, mirroring edits as they land. */
+    watch?: boolean;
+    /** Also export engine-authored changes back to the directory. */
+    out?: boolean;
+    /** Diagnostics sink (stderr-style); defaults to no-op. */
+    log?: (msg: string) => void;
+}
+/**
+ * Run one filesystem↔engine mirror over MCP. Resolves when the initial sync (+
+ * optional export) completes; in `watch` mode it resolves only after SIGINT/
+ * SIGTERM, having torn down the source + engine. Throws on connect/spawn failure.
+ */
+export declare function runFsMirror(opts: FsMirrorOptions): Promise<void>;

package/dist/src/mirror.js

@@ -0,0 +1,57 @@
+import { execPath } from "node:process";
+import { createExternalSource } from "@omgbase/core";
+import { fsAdapterBinPath } from "@omgbase/fs-adapter";
+import { connectStdioEngine } from "./mcp-engine-client.js";
+import { Coordinator } from "./coordinator.js";
+/**
+ * Run one filesystem↔engine mirror over MCP. Resolves when the initial sync (+
+ * optional export) completes; in `watch` mode it resolves only after SIGINT/
+ * SIGTERM, having torn down the source + engine. Throws on connect/spawn failure.
+ */
+export async function runFsMirror(opts) {
+    const log = opts.log ?? (() => { });
+    const engine = await connectStdioEngine({ command: opts.server[0], args: opts.server.slice(1) });
+    const source = await createExternalSource({ command: execPath, args: [fsAdapterBinPath(), "--root", opts.root] });
+    const coord = new Coordinator(engine, source);
+    const shutdown = async () => {
+        try {
+            await source.close();
+        }
+        finally {
+            await engine.close();
+        }
+    };
+    try {
+        const s = await coord.syncIn();
+        log(`in: +${s.ingested.length} ingested, =${s.suppressed.length} unchanged, !${s.conflicted.length} conflicted, -${s.deleted.length} deleted`);
+        if (opts.out) {
+            const o = await coord.syncOut();
+            log(`out: →${o.written.length} written, ✗${o.removed.length} removed`);
+        }
+        if (opts.watch) {
+            const sub = await coord.watchIn({
+                onSummary: (w) => log(`watch: +${w.ingested.length} =${w.suppressed.length} !${w.conflicted.length} -${w.deleted.length}`),
+                onError: (err) => log(`watch error: ${String(err)}`),
+            });
+            if (!sub) {
+                log("source cannot watch — nothing to do (did the initial sync above)");
+                await shutdown();
+                return;
+            }
+            log("watching — Ctrl-C to stop");
+            await new Promise((resolve) => {
+                const stop = () => {
+                    void sub.stop().then(shutdown).then(resolve);
+                };
+                process.once("SIGINT", stop);
+                process.once("SIGTERM", stop);
+            });
+            return;
+        }
+    }
+    finally {
+        if (!opts.watch)
+            await shutdown();
+    }
+}
+//# sourceMappingURL=mirror.js.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@omgbase/sync",
+  "version": "0.1.0",
+  "description": "Open Markdown Graph Base — standalone store-to-store synchronizer: a coordinator over an EngineClient seam (in-process or MCP-client) and source adapters",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omgbase/omgbase.git",
+    "directory": "packages/sync"
+  },
+  "homepage": "https://github.com/omgbase/omgbase#readme",
+  "bugs": {
+    "url": "https://github.com/omgbase/omgbase/issues"
+  },
+  "keywords": [
+    "markdown",
+    "knowledge-graph",
+    "sqlite",
+    "mcp",
+    "model-context-protocol",
+    "obsidian",
+    "agents",
+    "omgbase",
+    "sync",
+    "mirror",
+    "coordinator"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/corpus/**",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "omgbase-sync": "./dist/src/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@omgbase/core": "^0.1.0",
+    "@omgbase/fs-adapter": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}