@omgbase/core 0.1.0

package/dist/src/sync/watch-lease.js

@@ -0,0 +1,91 @@
+import { openSync, closeSync, writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+// Watch lease (11 §3.4). `omg watch` / `omg mcp`'s in-process watcher holds an
+// advisory lock on <workspace>/.omgbase/watch.lock for its lifetime. Liveness is
+// the lock itself: try-acquire non-blocking; acquirable ⇒ no live watcher. No
+// heartbeats, no PID files beyond this record, no stale-lease sweeper. Commands
+// probe it to skip the freshness sweep; `omg status` reports live/none.
+//
+// Implemented with the same O_EXCL + pid-liveness substitution as the writer
+// lock (Node exposes no flock; no new deps — 11 §8). Held open until release().
+const LEASE_NAME = "watch.lock";
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function readHolderPid(leasePath) {
+    try {
+        return JSON.parse(readFileSync(leasePath, "utf8")).pid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if a live watcher currently holds the lease. */
+export function watchLeaseLive(omgbaseDir) {
+    const leasePath = join(omgbaseDir, LEASE_NAME);
+    if (!existsSync(leasePath))
+        return false;
+    const pid = readHolderPid(leasePath);
+    return pid != null && pidAlive(pid);
+}
+export class WatchLease {
+    held = false;
+    leasePath;
+    constructor(omgbaseDir) {
+        this.leasePath = join(omgbaseDir, LEASE_NAME);
+    }
+    /**
+     * Try to take the lease. Returns a held lease, or null if a live watcher
+     * already holds it. A lease whose holder pid is dead is stolen.
+     */
+    static tryAcquire(omgbaseDir) {
+        mkdirSync(omgbaseDir, { recursive: true });
+        const lease = new WatchLease(omgbaseDir);
+        if (lease.take())
+            return lease;
+        return null;
+    }
+    take() {
+        try {
+            const fd = openSync(this.leasePath, "wx");
+            writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+            closeSync(fd);
+            this.held = true;
+            return true;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            const pid = readHolderPid(this.leasePath);
+            if (pid == null || !pidAlive(pid)) {
+                try {
+                    unlinkSync(this.leasePath);
+                }
+                catch {
+                    return false;
+                }
+                return this.take();
+            }
+            return false;
+        }
+    }
+    release() {
+        if (!this.held)
+            return;
+        this.held = false;
+        try {
+            if (existsSync(this.leasePath))
+                unlinkSync(this.leasePath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+//# sourceMappingURL=watch-lease.js.map

package/dist/src/sync/watcher.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from "../core/store/store.js";
+import { type CheckpointResult } from "./driver.js";
+import type { SyncSource } from "./plugin.js";
+export interface WatcherOptions {
+    onCheckpoint?: (result: CheckpointResult) => void;
+    /** Surface a reconcile error from a background batch (the watch stays live). */
+    onError?: (err: unknown) => void;
+}
+export declare class Watcher {
+    private store;
+    private repoId;
+    private source;
+    private opts;
+    private sub;
+    constructor(store: Store, repoId: string, source: SyncSource, opts?: WatcherOptions);
+    start(): Promise<void>;
+    private ingest;
+    stop(): Promise<void>;
+}

package/dist/src/sync/watcher.js

@@ -0,0 +1,34 @@
+import { reconcileChanges } from "./driver.js";
+export class Watcher {
+    store;
+    repoId;
+    source;
+    opts;
+    sub = null;
+    constructor(store, repoId, source, opts = {}) {
+        this.store = store;
+        this.repoId = repoId;
+        this.source = source;
+        this.opts = opts;
+    }
+    async start() {
+        if (!this.source.watch)
+            throw new Error("source does not support watch()");
+        this.sub = await this.source.watch((paths) => {
+            // A batch arrives from the adapter's stream; reconcile it off the callback.
+            void this.ingest(paths).catch((err) => this.opts.onError?.(err));
+        });
+    }
+    async ingest(paths) {
+        if (paths.length === 0)
+            return null;
+        const result = await reconcileChanges(this.store, this.repoId, this.source, paths.map((path) => ({ path })));
+        this.opts.onCheckpoint?.(result);
+        return result;
+    }
+    async stop() {
+        await this.sub?.stop();
+        this.sub = null;
+    }
+}
+//# sourceMappingURL=watcher.js.map

package/dist/src/sync/workspace.d.ts

@@ -0,0 +1,34 @@
+import { Store } from "../core/store/store.js";
+export interface RepoRow {
+    repoId: string;
+    slug: string;
+    /** The repo's filesystem root, DERIVED from its attached `fs` source's
+     *  `config.root` (ADR-014; the `repos.root_path` column was removed in v13).
+     *  null for a sourceless/headless repo (its `sync`/`watch` are no-ops). */
+    rootPath: string | null;
+}
+export declare class Workspace {
+    readonly root: string;
+    readonly omgbaseDir: string;
+    readonly dbPath: string;
+    readonly store: Store;
+    private constructor();
+    /** Find the workspace containing `startDir` (walk up); null if none. */
+    static find(startDir?: string): Workspace | null;
+    /** Open the workspace rooted exactly at `root` (creating .omgbase/ + db). */
+    static open(root: string): Workspace;
+    repos(): RepoRow[];
+    repoBySlug(slug: string): RepoRow | null;
+    /**
+     * Select the active repo. With an explicit slug, that repo (or throws
+     * repo_not_found). Otherwise the repo whose root_path contains `cwd`; if none
+     * or several match, throws AmbiguousRepo with the candidate slugs.
+     */
+    selectRepo(cwd: string, slug?: string): RepoRow;
+    close(): void;
+}
+export declare class RepoSelectionError extends Error {
+    readonly code: "repo_not_found";
+    readonly candidates: string[];
+    constructor(code: "repo_not_found", message: string, candidates: string[]);
+}

package/dist/src/sync/workspace.js

@@ -0,0 +1,120 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, resolve, relative, isAbsolute } from "node:path";
+import { Store } from "../core/store/store.js";
+/** Extract an fs source's root from its stored `config` JSON, or null. */
+function fsRootFromConfig(config) {
+    if (!config)
+        return null;
+    try {
+        const root = JSON.parse(config).root;
+        return typeof root === "string" && root !== "" ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class Workspace {
+    root;
+    omgbaseDir;
+    dbPath;
+    store;
+    constructor(root) {
+        this.root = root;
+        this.omgbaseDir = join(root, ".omgbase");
+        this.dbPath = join(this.omgbaseDir, "omgbase.db");
+        this.store = new Store({ path: this.dbPath });
+    }
+    /** Find the workspace containing `startDir` (walk up); null if none. */
+    static find(startDir = process.cwd()) {
+        let dir = resolve(startDir);
+        for (;;) {
+            const candidate = join(dir, ".omgbase");
+            if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+                return new Workspace(dir);
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    /** Open the workspace rooted exactly at `root` (creating .omgbase/ + db). */
+    static open(root) {
+        return new Workspace(resolve(root));
+    }
+    repos() {
+        // rootPath is derived from the repo's attached `fs` source (ADR-014). A repo
+        // may have several attachments, so the LEFT JOIN can yield multiple rows per
+        // repo; dedup by repo and take the first fs source's root.
+        const rows = this.store.db
+            .prepare(`SELECT r.repo_id AS repo_id, r.slug AS slug, s.config AS fs_config
+         FROM repos r
+         LEFT JOIN attachments a ON a.repo_id = r.repo_id
+         LEFT JOIN sources s ON s.source_id = a.source_id AND s.adapter = 'fs'
+         ORDER BY r.slug`)
+            .all();
+        const byId = new Map();
+        for (const r of rows) {
+            const existing = byId.get(r.repo_id);
+            if (existing) {
+                if (!existing.rootPath)
+                    existing.rootPath = fsRootFromConfig(r.fs_config);
+            }
+            else {
+                byId.set(r.repo_id, { repoId: r.repo_id, slug: r.slug, rootPath: fsRootFromConfig(r.fs_config) });
+            }
+        }
+        return [...byId.values()];
+    }
+    repoBySlug(slug) {
+        return this.repos().find((r) => r.slug === slug) ?? null;
+    }
+    /**
+     * Select the active repo. With an explicit slug, that repo (or throws
+     * repo_not_found). Otherwise the repo whose root_path contains `cwd`; if none
+     * or several match, throws AmbiguousRepo with the candidate slugs.
+     */
+    selectRepo(cwd, slug) {
+        const repos = this.repos();
+        if (slug) {
+            const found = repos.find((r) => r.slug === slug);
+            if (!found) {
+                throw new RepoSelectionError("repo_not_found", `no repo with slug '${slug}'`, repos.map((r) => r.slug));
+            }
+            return found;
+        }
+        if (repos.length === 1)
+            return repos[0];
+        const here = resolve(cwd);
+        // Only filesystem-backed repos (a derived rootPath) can contain the cwd; a
+        // sourceless/headless repo has no location, so it never matches by cwd.
+        const containing = repos.filter((r) => {
+            if (r.rootPath == null)
+                return false;
+            const rel = relative(resolve(r.rootPath), here);
+            return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+        });
+        if (containing.length === 1)
+            return containing[0];
+        if (containing.length === 0) {
+            throw new RepoSelectionError("repo_not_found", `no repo contains ${here}; select one with --repo`, repos.map((r) => r.slug));
+        }
+        // Several contain cwd (nested roots): pick the deepest (longest root path).
+        containing.sort((a, b) => resolve(b.rootPath).length - resolve(a.rootPath).length);
+        return containing[0];
+    }
+    close() {
+        this.store.close();
+    }
+}
+export class RepoSelectionError extends Error {
+    code;
+    candidates;
+    constructor(code, message, candidates) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+        this.name = "RepoSelectionError";
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/src/sync/writer-lock.d.ts

@@ -0,0 +1,16 @@
+export interface WriterLockOptions {
+    /** Max time to wait for the lock before throwing (ms). Default 5000. */
+    timeoutMs?: number;
+    /** Poll interval while waiting (ms). Default 25. */
+    pollMs?: number;
+}
+export declare class WriterLockTimeout extends Error {
+    constructor(lockPath: string, holderPid: number | null);
+}
+/**
+ * Run fn while holding the workspace writer lock. Blocks (polling) until the
+ * lock is free or the timeout elapses, then releases the lock even if fn throws.
+ */
+export declare function withWriterLock<T>(omgbaseDir: string, fn: () => T, opts?: WriterLockOptions): T;
+/** True if no live writer holds the lock (probe without acquiring). */
+export declare function writerLockFree(omgbaseDir: string): boolean;

package/dist/src/sync/writer-lock.js

@@ -0,0 +1,121 @@
+import { openSync, closeSync, readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+// Cross-process writer lock (11 §3.2). The write protocol's per-repo writer
+// mutex (04 §6 step 1) generalizes to an advisory lock on
+// <workspace>/.omgbase/writer.lock, held for steps 2–7. All writers — one-shot
+// CLI mutations, watcher checkpoint ingests, `omg mcp` applies — acquire it.
+//
+// Node core exposes no flock(2), and the design forbids new runtime deps (11
+// §8). We implement the same advisory contract with an O_EXCL lockfile: exclusive
+// creation is atomic on local filesystems, the holder writes its pid for
+// liveness, and a lock whose pid is dead is stolen (no daemon, no lease sweeper —
+// the same "probe by trying" spirit as the watch lease in §3.4). This is an
+// as-built substitution for flock; the file-CAS + ingest-and-replay behavior in
+// the write protocol is unchanged.
+const LOCK_NAME = "writer.lock";
+const STALE_MS = 30_000;
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process; EPERM = alive but not ours (still alive).
+        return err.code === "EPERM";
+    }
+}
+export class WriterLockTimeout extends Error {
+    constructor(lockPath, holderPid) {
+        super(`could not acquire writer lock ${lockPath} (held by pid ${holderPid ?? "?"})`);
+        this.name = "WriterLockTimeout";
+    }
+}
+function tryAcquire(lockPath) {
+    try {
+        const fd = openSync(lockPath, "wx"); // O_CREAT | O_EXCL
+        writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+        closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+        // Lock exists: steal it if the holder is dead or the record is stale.
+        let holderPid = null;
+        let ts = 0;
+        try {
+            const rec = JSON.parse(readFileSync(lockPath, "utf8"));
+            holderPid = rec.pid ?? null;
+            ts = rec.ts ?? 0;
+        }
+        catch {
+            // Unreadable/partial lock record — treat as stale.
+        }
+        const dead = holderPid != null && !pidAlive(holderPid);
+        const stale = Date.now() - ts > STALE_MS;
+        if (dead || stale) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* someone else stole it first; fall through to retry */
+            }
+            return tryAcquire(lockPath);
+        }
+        return false;
+    }
+}
+function readHolderPid(lockPath) {
+    try {
+        return JSON.parse(readFileSync(lockPath, "utf8")).pid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Busy-wait with a blocking sleep between polls. Writers hold the lock only for
+// the brief file-CAS + ingest window, so contention waits are short; a sync
+// spin keeps the lock API synchronous like the rest of the write path.
+function sleepSync(ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        /* spin */
+    }
+}
+/**
+ * Run fn while holding the workspace writer lock. Blocks (polling) until the
+ * lock is free or the timeout elapses, then releases the lock even if fn throws.
+ */
+export function withWriterLock(omgbaseDir, fn, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    const pollMs = opts.pollMs ?? 25;
+    mkdirSync(omgbaseDir, { recursive: true });
+    const lockPath = join(omgbaseDir, LOCK_NAME);
+    const deadline = Date.now() + timeoutMs;
+    while (!tryAcquire(lockPath)) {
+        if (Date.now() >= deadline)
+            throw new WriterLockTimeout(lockPath, readHolderPid(lockPath));
+        sleepSync(pollMs);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            if (existsSync(lockPath))
+                unlinkSync(lockPath);
+        }
+        catch {
+            /* best-effort release */
+        }
+    }
+}
+/** True if no live writer holds the lock (probe without acquiring). */
+export function writerLockFree(omgbaseDir) {
+    const lockPath = join(omgbaseDir, LOCK_NAME);
+    if (!existsSync(lockPath))
+        return true;
+    const pid = readHolderPid(lockPath);
+    return pid == null || !pidAlive(pid);
+}
+//# sourceMappingURL=writer-lock.js.map

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@omgbase/core",
+  "version": "0.1.0",
+  "description": "Open Markdown Graph Base — embedded engine",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omgbase/omgbase.git",
+    "directory": "packages/core"
+  },
+  "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",
+    "engine",
+    "oqx",
+    "query",
+    "embedded"
+  ],
+  "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",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/src/*.js",
+      "types": "./dist/src/*.d.ts"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@omgbase/oqx": "^0.10.2",
+    "better-sqlite3": "^13.0.3",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-frontmatter": "^2.0.1",
+    "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-frontmatter": "^2.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/mdast": "^4.0.4",
+    "fast-check": "^4.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}