omgbase 0.3.0 → 0.4.0

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,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, EmbedDrainer, EngineError, pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
+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";
@@ -127,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, {
@@ -144,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.3.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.3.0",
-    "@omgbase/fs-adapter": "^0.1.0",
-    "@omgbase/sync": "^0.3.0",
+    "@omgbase/core": "^0.4.0",
+    "@omgbase/fs-adapter": "^0.2.0",
+    "@omgbase/sync": "^0.4.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {