omgbase 0.2.0 → 0.4.0

package/dist/src/cmd/_mutate.js

@@ -1,6 +1,6 @@
 import { readFileSync, readSync } from "node:fs";
 import { userInfo } from "node:os";
-import { apply } from "@omgbase/core";
+import { apply, unifiedDiff } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, EXIT_ERROR } from "../output.js";
 import { remoteCall } from "./_remote.js";
 // Shared plumbing for every write command (11 §5.6, §5.7). Sugar commands build
@@ -166,7 +166,7 @@ function renderDryRun(cli, result) {
     io.err(style.dim(`  dry run — ${Object.keys(result.diffs ?? {}).length} file(s) would change, nothing committed`));
     for (const [path, { before, after }] of Object.entries(result.diffs ?? {})) {
         io.out(`${style.bold(path)}`);
-        for (const line of unifiedDiff(before, after)) {
+        for (const line of unifiedDiff(before, after).split("\n")) {
             if (line.startsWith("+"))
                 io.out(style.ok(line));
             else if (line.startsWith("-"))
@@ -190,22 +190,5 @@ function renderCommitted(cli, result) {
         io.out(id);
     return EXIT_OK;
 }
-// Minimal line-based unified diff (matches the engine's diffUnified style; a
-// full Myers isn't needed for a human preview).
-function unifiedDiff(before, after) {
-    const a = before.split("\n");
-    const b = after.split("\n");
-    const out = [];
-    const max = Math.max(a.length, b.length);
-    for (let i = 0; i < max; i++) {
-        if (a[i] === b[i])
-            continue;
-        if (a[i] !== undefined)
-            out.push(`- ${a[i]}`);
-        if (b[i] !== undefined)
-            out.push(`+ ${b[i]}`);
-    }
-    return out;
-}
 export { EXIT_OK, EXIT_ERROR };
 //# sourceMappingURL=_mutate.js.map

package/dist/src/cmd/_source.d.ts

@@ -2,9 +2,9 @@ import { type SyncSource, type Store, type RepoRow } from "@omgbase/core";
 /** The built-in filesystem adapter's registry name. */
 export declare const FS_ADAPTER = "fs";
 /** Seed the built-in `fs` adapter row (idempotent). Required before creating an
- *  fs source (the `sources.adapter` FK is enforced). The stored command is the
- *  globally-installed bin name; the actual spawn uses the bundled binary via
- *  execPath (see spawnSource) so a source is never pinned to a stale path. */
+ *  fs source (the `sources.adapter` FK is enforced). The stored command is
+ *  registry data only (spec/sync §2, §5): the host never runs it for `fs` — see
+ *  spawnSource — so a source is never pinned to a stale path. */
 export declare function ensureFsAdapter(store: Store): void;
 /**
  * Build the live filesystem SyncSource for a repo from its attached `fs` source

package/dist/src/cmd/_source.js

@@ -1,6 +1,5 @@
-import { execPath } from "node:process";
-import { createExternalSource, ensureAdapter, sourcesForRepo, renderConfigFlags, } from "@omgbase/core";
-import { fsAdapterBinPath } from "@omgbase/fs-adapter";
+import { createExternalSource, ensureAdapter, listAdapters, sourcesForRepo, renderConfigFlags, } from "@omgbase/core";
+import { fsAdapterLaunch } from "@omgbase/fs-adapter";
 // Resolve a repo's live sync source for `omg watch`/`omg mcp`/`omg sync`
 // (sync-plugins, ADR-014 Stage 3). Resolution now prefers the source REGISTRY
 // (adapters/sources/attachments tables): a repo's attached filesystem source is
@@ -11,19 +10,23 @@ import { fsAdapterBinPath } from "@omgbase/fs-adapter";
 /** The built-in filesystem adapter's registry name. */
 export const FS_ADAPTER = "fs";
 /** Seed the built-in `fs` adapter row (idempotent). Required before creating an
- *  fs source (the `sources.adapter` FK is enforced). The stored command is the
- *  globally-installed bin name; the actual spawn uses the bundled binary via
- *  execPath (see spawnSource) so a source is never pinned to a stale path. */
+ *  fs source (the `sources.adapter` FK is enforced). The stored command is
+ *  registry data only (spec/sync §2, §5): the host never runs it for `fs` — see
+ *  spawnSource — so a source is never pinned to a stale path. */
 export function ensureFsAdapter(store) {
     ensureAdapter(store, FS_ADAPTER, "omgbase-fs-adapter", []);
 }
 /** Spawn one registered source as a live SyncSource. The built-in `fs` adapter
- *  is served by the bundled `@omgbase/fs-adapter` (execPath + bin path); other
- *  adapters spawn their stored command. Source config renders to argv flags. */
-function spawnSource(source) {
+ *  is launched per spec/sync §5 (1.2): `$OMGBASE_FS_ADAPTER` whitespace-split
+ *  when set and non-empty, else the bundled `@omgbase/fs-adapter` bin under the
+ *  running `node`; then the row's fixed `args`, then the rendered config flags
+ *  (`fsAdapterLaunch`). Other adapters would spawn their stored command. */
+function spawnSource(store, source) {
     const flags = renderConfigFlags(source.config);
     if (source.adapter === FS_ADAPTER) {
-        return createExternalSource({ command: execPath, args: [fsAdapterBinPath(), ...flags], ...(hasEnv(source) ? { env: source.env } : {}) });
+        const row = listAdapters(store).find((a) => a.name === FS_ADAPTER);
+        const launch = fsAdapterLaunch(row?.args ?? [], flags);
+        return createExternalSource({ ...launch, ...(hasEnv(source) ? { env: source.env } : {}) });
     }
     // Custom adapter: spawn its stored command (looked up by the caller).
     throw new Error(`no launcher for adapter '${source.adapter}' (only the built-in '${FS_ADAPTER}' is wired)`);
@@ -42,6 +45,6 @@ export async function openRepoSource(store, repo) {
     const root = fsSource.config.root;
     if (typeof root !== "string" || root === "")
         return null;
-    return spawnSource(fsSource);
+    return spawnSource(store, fsSource);
 }
 //# sourceMappingURL=_source.js.map

package/dist/src/cmd/mcp.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, EmbedDrainer, EngineError } from "@omgbase/core";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError, pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { openRepoSource } from "./_source.js";
 // `omg mcp [--no-watch]` (11 §5.8) — MCP server on stdio; the host owns the
@@ -10,6 +10,41 @@ import { openRepoSource } from "./_source.js";
 //
 // CRITICAL: on stdio, stdout is the MCP protocol channel. Nothing may write to
 // stdout here — every diagnostic goes to stderr (cli.io.err).
+/**
+ * The two conformance seams of spec/surface §7.1, read from the environment
+ * BEFORE the workspace opens (so no id is minted and no timestamp read without
+ * them). For conformance runs only — never set in production:
+ *
+ *   OMGBASE_SPEC_MINTER=sequential   the fixture minter of spec/store §2.2 for
+ *                                    the whole process (`d_0, d_1, …`, each
+ *                                    prefix from 0); any other value is a
+ *                                    startup error
+ *   OMGBASE_SPEC_CLOCK=<RFC 3339>    "now" is that instant for the whole
+ *                                    process: every commit a tool stamps, every
+ *                                    `ts` reported as current
+ *
+ * Both are announced on stderr (stdout is the protocol channel).
+ */
+function installSpecSeams(cli) {
+    const minter = process.env.OMGBASE_SPEC_MINTER;
+    if (minter !== undefined && minter !== "") {
+        if (minter !== "sequential") {
+            throw new CliUsageError(`OMGBASE_SPEC_MINTER=${JSON.stringify(minter)}: the only value is "sequential" (spec/surface §7.1)`, "unset it, or set OMGBASE_SPEC_MINTER=sequential for a conformance run");
+        }
+        setIdMinter(sequentialMinter());
+        cli.io.err(cli.style.dim("[mcp] spec seam: sequential id minter (OMGBASE_SPEC_MINTER=sequential) — conformance run, not for production"));
+    }
+    const clock = process.env.OMGBASE_SPEC_CLOCK;
+    if (clock !== undefined && clock !== "") {
+        try {
+            pinClock(clock);
+        }
+        catch {
+            throw new CliUsageError(`OMGBASE_SPEC_CLOCK=${JSON.stringify(clock)}: not an RFC 3339 instant (spec/surface §7.1)`, "e.g. OMGBASE_SPEC_CLOCK=2026-09-27T00:00:00.000Z");
+        }
+        cli.io.err(cli.style.dim(`[mcp] spec seam: clock pinned to ${new Date().toISOString()} (OMGBASE_SPEC_CLOCK) — conformance run, not for production`));
+    }
+}
 async function runMcp(cli, args) {
     const { values } = parseArgs({
         args,
@@ -29,6 +64,7 @@ async function runMcp(cli, args) {
             notes: [`host config: {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]}`],
         });
     }
+    installSpecSeams(cli);
     // The host launches us from its own cwd, so a missing workspace here almost
     // always means the host config lacks `-C <dir>` — say so, rather than the
     // generic "run init" hint (which would create an empty workspace in the wrong place).
@@ -91,10 +127,10 @@ async function runMcp(cli, args) {
     if (wantWatch) {
         lease = WatchLease.tryAcquire(ws.omgbaseDir);
         if (lease) {
-            // Prime with a one-shot sweep so the session starts fresh, then watch via
-            // the external fs-adapter process (chokidar lives there, not in-engine).
-            if (repo.rootPath)
-                freshnessSweep(ws.store, repo.repoId, repo.rootPath);
+            // spec/sync §5 order: open the source (the external fs-adapter process —
+            // chokidar lives there, not in-engine), `watch`, wait for `ready` (bounded),
+            // THEN the priming sweep, then report live. An edit landing before the feed
+            // is primed is caught by the sweep, one after it by the feed.
             source = await openRepoSource(ws.store, repo);
             if (source) {
                 watcher = new Watcher(ws.store, repo.repoId, source, {
@@ -108,6 +144,11 @@ async function runMcp(cli, args) {
                     onError: (err) => cli.io.err(cli.style.dim(`[watch] error: ${String(err)}`)),
                 });
                 await watcher.start();
+                if (!(await awaitReady(watcher.ready(), WATCH_READY_PATIENCE_MS))) {
+                    cli.io.err(cli.style.dim(`[watch] the fs adapter did not report ready within ${WATCH_READY_PATIENCE_MS / 1000}s — proceeding as if ready`));
+                }
+                if (repo.rootPath)
+                    freshnessSweep(ws.store, repo.repoId, repo.rootPath); // prime: anything that landed before the feed was ready
                 cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · watcher live`));
             }
             else {

package/dist/src/cmd/mutate.js

@@ -67,19 +67,20 @@ async function runInsert(cli, args) {
     const { values, positionals } = parseArgs({
         args: content.rest,
         allowPositionals: true,
-        options: { at: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+        options: { at: { type: "string" }, expect: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "insert",
             summary: "Insert markdown as new block(s) under a parent block or heading",
-            usage: "insert <to> (-m <markdown> | -f <file> | -) [--at end|start|before <id>|after <id>] [--actor <s>] [--dry-run]",
+            usage: "insert <to> (-m <markdown> | -f <file> | -) [--at end|start|before <id>|after <id>] [--expect <parent_children_hash>] [--actor <s>] [--dry-run]",
             options: [
                 ["<to>", "parent block id, or a heading block id to append into its section"],
                 ["-m <markdown>", "content inline"],
                 ["-f <file>", "content from a file"],
                 ["-", "content from stdin"],
                 ["--at <pos>", "end (default) | start | before <id> | after <id>"],
+                ["--expect <hash>", "destination CAS: fail with stale_expectation unless the parent's direct child ids (joined by \",\", sha256 hex) still hash to this"],
                 ["--actor <s>", "commit actor (default human:$USER)"],
             ],
         });
@@ -88,12 +89,14 @@ async function runInsert(cli, args) {
     if (!to)
         throw new CliUsageError("insert requires a <to> parent (block id, or a heading id for section append)");
     const markdown = readContent(content);
+    // The destination-parent CAS (spec/mutate §1.2) rides as the op-level expect.
+    const expect = values.expect ? { expect: { parent_children_hash: values.expect } } : {};
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_insert", { to, markdown, at: parseAt(values) });
+        return runOpsRemote(cli, "blocks_insert", { to, markdown, at: parseAt(values), ...expect });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const parent = block(cli, ws, repo.repoId, to);
-    const op = { op: "insert", to: { parent, at: parseAt(values) }, markdown };
+    const op = { op: "insert", to: { parent, at: parseAt(values) }, markdown, ...expect };
     return runOps(cli, ws, repo, [op], actorOf(values));
 }
 // ---- update -----------------------------------------------------------------
@@ -143,17 +146,18 @@ async function runMove(cli, args) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
-        options: { to: { type: "string" }, at: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+        options: { to: { type: "string" }, at: { type: "string" }, expect: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "move",
             summary: "Move block(s) under a new parent, identity preserved",
-            usage: "move <blocks…|-> --to <parent> [--at end|start|before <id>|after <id>] [--actor <s>] [--dry-run]",
+            usage: "move <blocks…|-> --to <parent> [--at end|start|before <id>|after <id>] [--expect <parent_children_hash>] [--actor <s>] [--dry-run]",
             options: [
                 ["<blocks…>", "block ids; `-` reads them from stdin, one per line"],
                 ["--to <parent>", "destination parent block"],
                 ["--at <pos>", "end (default) | start | before <id> | after <id>"],
+                ["--expect <hash>", "destination CAS: fail with stale_expectation unless the destination's direct child ids (joined by \",\", sha256 hex) still hash to this"],
                 ["--actor <s>", "commit actor (default human:$USER)"],
             ],
         });
@@ -163,13 +167,15 @@ async function runMove(cli, args) {
     const refs = expandBlockArgs(positionals);
     if (refs.length === 0)
         throw new CliUsageError("move requires one or more blocks (or - for stdin)");
+    // The destination-parent CAS (spec/mutate §1.2), checked once for the run.
+    const expect = values.expect ? { expect: { parent_children_hash: values.expect } } : {};
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_move", { blocks: refs, to: values.to, at: parseAt(values) });
+        return runOpsRemote(cli, "blocks_move", { blocks: refs, to: values.to, at: parseAt(values), ...expect });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
     const parent = block(cli, ws, repo.repoId, values.to);
-    const op = { op: "move", blocks, to: { parent, at: parseAt(values) } };
+    const op = { op: "move", blocks, to: { parent, at: parseAt(values) }, ...expect };
     return runOps(cli, ws, repo, [op], actorOf(values));
 }
 // ---- rm (blocks; --doc handled by the doc-level command) --------------------

package/dist/src/cmd/sync.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, EngineError } from "@omgbase/core";
+import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EngineError } from "@omgbase/core";
 import { runFsMirror } from "@omgbase/sync";
 import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
@@ -97,8 +97,11 @@ function runOneShot(cli, ws, repo) {
         io.out(`  ${style.dim("already up to date")}`);
     return EXIT_OK;
 }
-// Local live watcher (the former `omg watch`): prime with a sweep, then run the
-// external fs-adapter watcher until a signal, keeping embeddings warm.
+// Local live watcher (the former `omg watch`), in the order of spec/sync §5:
+// take the lease, open the source, `watch`, wait for `ready` (bounded), THEN the
+// priming sweep, then report live — so an edit landing before the feed is primed
+// is caught by the sweep and one landing after it by the feed. Runs until a
+// signal, keeping embeddings warm.
 async function runLocalWatch(cli, ws, repo) {
     const lease = WatchLease.tryAcquire(ws.omgbaseDir);
     if (!lease)
@@ -124,8 +127,6 @@ async function runLocalWatch(cli, ws, repo) {
             onError: (err) => cli.io.err(cli.style.dim(`  embed drain failed: ${String(err)}`)),
         })
         : null;
-    if (repo.rootPath)
-        freshnessSweep(ws.store, repo.repoId, repo.rootPath); // start fresh
     const source = await openRepoSource(ws.store, repo);
     if (!source) {
         cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to watch`));
@@ -146,6 +147,11 @@ async function runLocalWatch(cli, ws, repo) {
         onError: (err) => cli.io.err(cli.style.err(`  watch error: ${String(err)}`)),
     });
     await watcher.start();
+    if (!(await awaitReady(watcher.ready(), WATCH_READY_PATIENCE_MS))) {
+        cli.io.err(cli.style.dim(`  the fs adapter did not report ready within ${WATCH_READY_PATIENCE_MS / 1000}s — proceeding as if ready (an edit made before now may be missed until the next sweep)`));
+    }
+    if (repo.rootPath)
+        freshnessSweep(ws.store, repo.repoId, repo.rootPath); // prime: anything that landed before the feed was ready
     drainer?.schedule(); // embed anything already stale at startup, in the background
     cli.io.err(cli.style.dim(`  watching ${repo.slug} — Ctrl-C to stop${drainer ? " · auto-embed on" : ""}`));
     await new Promise((resolveWait) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.2.0",
-    "@omgbase/fs-adapter": "^0.1.0",
-    "@omgbase/sync": "^0.2.0",
+    "@omgbase/core": "^0.4.0",
+    "@omgbase/fs-adapter": "^0.2.0",
+    "@omgbase/sync": "^0.4.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {