omgbase 0.8.0 → 0.10.0

package/README.md

@@ -50,7 +50,7 @@ $ omg q 'from blocks where type == "task" && !attrs.checked'
 b_24nr0y0  README.md
 b_36p2zw1  README.md
 
-$ omg q '$repo.blocks count { where type == "task" && !attrs.checked }'
+$ omg q 'blocks count { where type == "task" && !attrs.checked }'
 2
 
 $ omg outline README.md

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "d35d3d9",
-  "built": "2026-10-09T22:09:12.327Z"
+  "commit": "d2df0ed",
+  "built": "2026-10-10T07:57:27.728Z"
 }

package/dist/src/cmd/_mutate.js

@@ -1,6 +1,6 @@
 import { readFileSync, readSync } from "node:fs";
 import { userInfo } from "node:os";
-import { apply, unifiedDiff } from "@omgbase/core";
+import { apply, unifiedDiff, surfaceApplyResult } 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
@@ -135,7 +135,9 @@ export function runOps(cli, ws, repo, ops, opts = {}) {
         omgbaseDir: ws.omgbaseDir,
         ...(cli.flags.dryRun ? { dryRun: true } : {}),
     };
-    const result = apply(ws.store, req);
+    // The reference form on every printed path (spec/surface §1 "Paths"): the
+    // kernel's result is re-shaped exactly as the MCP server re-shapes it.
+    const result = surfaceApplyResult(apply(ws.store, req));
     return renderApply(cli, result);
 }
 /**

package/dist/src/cmd/cat.js

@@ -59,7 +59,7 @@ async function runCat(cli, args) {
             summary: "Content bytes of a node — exact raw bytes by default, pipe-clean (`show` is the metadata card)",
             usage: "cat <node…|-> [--resolution raw|text|outline|skeleton|full]",
             options: [
-                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a repo-relative doc path (`notes/x.md`)"],
+                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a doc path (`/notes/x.md`; the leading `/` is optional)"],
                 ["-", `read refs from stdin, one per line (\`${cli.prog} q … --ids | ${cli.prog} cat -\`)`],
                 ["--resolution <r>", "block refs only: raw (default: exact bytes) | text | outline | skeleton | full; a document is always its exact bytes (warns if given)"],
             ],

package/dist/src/cmd/docs.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { parse as parseYamlScalar } from "yaml";
-import { docsCreate, docsMove, docsDelete, docsSetMeta } from "@omgbase/core";
+import { docsCreate, docsMove, docsDelete, docsSetMeta, surfaceDocOpResult, surfaceDocMoveResult, referencePath } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts, renderDiffs } from "./_mutate.js";
 import { remoteCall } from "./_remote.js";
@@ -8,6 +8,9 @@ import { remoteCall } from "./_remote.js";
 // over the core doc ops, which own the file-write + commit + flock protocol.
 // The global --dry-run rides as the op's `dryRun` (spec/cli §3.6): the op
 // validates and returns the per-file diffs it would make, committing nothing.
+// Every path printed is the reference form (spec/surface §1 "Paths"): the
+// library's result is re-shaped through `surfaceDocOpResult` — the same
+// function the MCP server applies — before it is rendered.
 function ctxOf(cli, ws, repoId, rootPath, actor) {
     return {
         repoId,
@@ -52,7 +55,7 @@ function reportMove(cli, from, res) {
     const n = res.dangling.length;
     io.err(style.warn(`  ${style.warn(cli.render.g.warn)} ${n} inbound link${n === 1 ? "" : "s"} still name${n === 1 ? "s" : ""} the old path: ${where}`));
     if (res.dangling.some((l) => l.block))
-        io.err(style.dim(`  fix: ${cli.prog} retarget /${from} /${res.path} --apply`));
+        io.err(style.dim(`  fix: ${cli.prog} retarget ${from} ${res.path} --apply`));
     const seen = new Set();
     for (const l of res.dangling) {
         if (l.block || !l.field)
@@ -61,7 +64,7 @@ function reportMove(cli, from, res) {
         if (seen.has(key))
             continue;
         seen.add(key);
-        io.err(style.dim(`  fix: ${cli.prog} meta ${l.path} --set ${l.field}=/${res.path}`));
+        io.err(style.dim(`  fix: ${cli.prog} meta ${l.path} --set ${l.field}=${res.path}`));
     }
     return code;
 }
@@ -95,7 +98,7 @@ async function runNew(cli, args) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = docsCreate(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), path, bytes);
+    const res = surfaceDocOpResult(docsCreate(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), path, bytes));
     return report(cli, "created", res);
 }
 // ---- mv ---------------------------------------------------------------------
@@ -127,7 +130,7 @@ async function runMv(cli, args) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = docsMove(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, toPath, noRetarget ? { retargetInbound: false } : {});
+    const res = surfaceDocMoveResult(docsMove(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, toPath, noRetarget ? { retargetInbound: false } : {}));
     return reportMove(cli, fromPathOf(res, doc), res);
 }
 // ---- rm --doc (block rm lives in mutate.ts; this handles the --doc branch) --
@@ -137,7 +140,7 @@ export async function runRmDoc(cli, doc, actor) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = docsDelete(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, actor), doc);
+    const res = surfaceDocOpResult(docsDelete(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, actor), doc));
     return report(cli, "deleted", res);
 }
 // ---- meta -------------------------------------------------------------------
@@ -198,18 +201,18 @@ async function runMeta(cli, args) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const res = docsSetMeta(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, { set, unset });
+    const res = surfaceDocOpResult(docsSetMeta(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, values.actor), doc, { set, unset }));
     return report(cli, "patched", res);
 }
 function dryRunArg(cli) {
     return cli.flags.dryRun ? { dry_run: true } : {};
 }
-// The path a move left behind, for the retarget hint: the dangling links name
-// it as written (`target`), which is the canonical spelling with a leading `/`;
-// fall back to the ref the user typed when nothing dangles.
+// The path a move left behind, for the retarget hint, in the reference form:
+// the dangling links name it as written (`target`, the canonical spelling with
+// a leading `/`); fall back to the ref the user typed when nothing dangles.
 function fromPathOf(res, ref) {
     const named = res.dangling.find((l) => l.target)?.target;
-    return (named ?? ref).replace(/^\/+/, "");
+    return referencePath(named ?? ref);
 }
 export const cmdNew = { name: "new", summary: "Create a document", run: (c, a) => runNew(c, a) };
 export const cmdMv = { name: "mv", summary: "Rename a document", run: (c, a) => runMv(c, a) };

package/dist/src/cmd/find.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { resolve as resolveThing } from "@omgbase/core";
+import { resolve as resolveThing, surfaceResolveHits } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
@@ -59,7 +59,7 @@ async function runFind(cli, args) {
                 }
             }
         }
-        hits = resolveThing(ws.store, input);
+        hits = surfaceResolveHits(resolveThing(ws.store, input)); // locators in the reference form
     }
     cli.capture?.(hits); // shell: the ranked hits become the addressable frame
     // -1: bare top id.

package/dist/src/cmd/oqx.js

@@ -9,7 +9,7 @@ import { readStdin } from "./_mutate.js";
 // object model (`doc.layer`, `section.blocks`); whitespace query directives
 // belong to OQX (`<receiver> collect|exists|count|first|single { <block> }`).
 // `from E` selects + flattens a relation relative to the current source scope
-// (top-level `from docs` = the repository's docs; `$repo.docs collect { from
+// (top-level `from docs` = the repository's docs; `docs collect { from
 // nodes … }` re-projects each doc through its nodes). Clause order is fixed
 // (ADR-020): `select … from … where … follow … order by … limit … offset …`,
 // each at most once, at the top level and inside every block. Only `select` may
@@ -20,14 +20,14 @@ import { readStdin } from "./_mutate.js";
 // tree over scalar predicates and consumer directives, count comparisons
 // (`nodes count { … } >= 2`), nestable collect, one-scope lifts (^name:) that
 // filter + capture, one-scope-outward references (^name) that correlate a nested
-// query to a parent binding, explicit root relations $repo.docs/nodes/blocks for
+// query to a parent binding, the root row's collections ^docs/^nodes/^blocks for
 // join-equivalents, first/single lookups, full-text text(...) + embedding-score
 // semantic(...) predicates, `order by <expr> [asc|desc]` ranking, and recursive
 // `follow [distinct] <rel> [{ where … frontier … depth n by … }]` traversal over
 // a type-preserving relation with $depth/$stop/$ordinal recursion metadata +
 // post-walk filtering. A top-level consumer directive changes the result shape:
-// `$repo.docs count { … }` / `$repo.docs exists { … }` reduce to a scalar,
-// `$repo.docs first { … }` / `$repo.docs single { … }` to zero-or-one row (bare
+// `docs count { … }` / `docs exists { … }` reduce to a scalar,
+// `docs first { … }` / `docs single { … }` to zero-or-one row (bare
 // `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
 // string or -f file|-. Human output: one hit per line (id + path), or an aligned
 // id/path/columns table when the query projects (`select`), or the scalar for
@@ -64,20 +64,20 @@ async function runOqx(cli, args) {
         cli.io.out("  e.g. query 'from docs where nodes count { where kind == \"md:task\" } >= 2'");
         cli.io.out("       query 'select items: section.blocks collect { where type == \"list_item\" } from nodes where kind == \"md:section\"'");
         cli.io.out("       query 'select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !attrs.checked }'");
-        cli.io.out("       query 'select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id } from docs'");
-        cli.io.out("       query '$repo.docs count { where layer == \"canon\" }'   # scalar; also $repo.<target> exists/none/first/single { … }");
+        cli.io.out("       query 'select owner_id, owner: ^nodes single { where kind == \"person\" && attrs.id == ^owner_id } from docs'   # ^docs/^nodes/^blocks/^edges: the repository (the root row) from inside a row; 0^docs from any depth");
+        cli.io.out("       query 'docs count { where layer == \"canon\" }'   # scalar; also <target> exists/none/first/single { … } at the top level");
         cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" && !checked }'   # none = zero rows (≡ !exists; \"every\" = none over the complement)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc limit 2 offset 1'   # limit/offset bound the set (after order/distinct, before the consumer)");
-        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $it } from docs where $path == \"x.md\"'   # a record as a collection ($key/$it); also entries(attrs), entries(inline)");
+        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $it } from docs where $path == \"/x.md\"'   # a record as a collection ($key/$it); also entries(attrs), entries(inline)");
         cli.io.out("       query 'select $path values from docs where layer == \"canon\"'   # `values`: bare values, no {id,path} hits (one item only)");
         cli.io.out("       query 'select $path, tags: tags collect { $it values where $it != \"draft\" } from docs'   # $it = the current item (here: each tag)");
-        cli.io.out("       query '$repo.docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
+        cli.io.out("       query 'docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
         cli.io.out("       query 'from docs where text(\"philosophers stone\") && layer == \"canon\"'   # full-text prune");
         cli.io.out("       query 'select s: semantic(\"the great work\") from blocks where semantic(\"the great work\") > 0.6'  # embedding score (needs a provider)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc'   # order by <expr> [asc|desc]");
         cli.io.out("       query 'select t: text, d: $depth, s: $stop from blocks where $id == \"b_x\" follow block.children'   # recursive walk ($depth/$stop metadata)");
         cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <rel> [{ where … frontier … depth n by … }]");
-        cli.io.out("       query 'select p: $path, d: $depth, s: $stop from docs where $path == \"index.md\" follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
+        cli.io.out("       query 'select p: $path, d: $depth, s: $stop from docs where $path == \"/index.md\" follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
         cli.io.out("       query 'from blocks where type == \"list_item\" && $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
         cli.io.out("       query 'select src: $src, to: $dst_path from edges where predicate == \"depends_on\"'   # the edges target: predicate/provenance/dst_kind + $src/$dst_path/$dst_uri");
         return EXIT_OK;

package/dist/src/cmd/outline.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { findDoc, docsOutline } from "@omgbase/core";
+import { findDoc, docsOutline, referencePath } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 // `omg outline <doc|path>` (alias ol) — the wire format (06 §6). Human output
@@ -33,13 +33,14 @@ async function runOutline(cli, args) {
     let header;
     if (cli.flags.server) {
         // Remote: the docs_outline tool resolves the ref + returns the same
-        // OutlineResult. The header shows the ref you passed (no local path lookup).
+        // OutlineResult. The header shows the ref you passed (no local path lookup):
+        // a path ref rooted (spec/surface §1 "Paths"), a `d_` id verbatim.
         result = await remoteCall(cli, "docs_outline", {
             doc: ref,
             ...(values.depth ? { depth: Number(values.depth) } : {}),
             ...(values.skeleton ? { resolution: "skeleton" } : {}),
         });
-        header = ref;
+        header = ref.startsWith("d_") ? ref : referencePath(ref);
     }
     else {
         const ws = cli.workspace();
@@ -53,7 +54,7 @@ async function runOutline(cli, args) {
         if (values.skeleton)
             opts.resolution = "skeleton";
         result = docsOutline(ws.store, info.docId, opts);
-        header = info.path;
+        header = referencePath(info.path);
     }
     // `{ text, truncated }` carries neither a list nor ids: every machine mode is the document.
     if (cli.flags.mode !== "human")

package/dist/src/cmd/retarget.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { linksRetarget } from "@omgbase/core";
+import { linksRetarget, surfaceRetargetHits } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { runOps, unifiedDiffLines } from "./_mutate.js";
 import { remoteCall } from "./_remote.js";
@@ -45,7 +45,8 @@ async function runRetarget(cli, args) {
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const { ops, hits } = linksRetarget(ws.store, repo.repoId, from, to, values.scope ? { pathGlob: values.scope } : {});
+    const { ops, hits: rawHits } = linksRetarget(ws.store, repo.repoId, from, to, values.scope ? { pathGlob: values.scope } : {});
+    const hits = surfaceRetargetHits(rawHits); // the hits' document paths in the reference form
     // --apply → commit via the shared helper (honors --dry-run too, if combined).
     if (values.apply) {
         return runOps(cli, ws, repo, ops, values.actor ? { actor: values.actor } : {});

package/dist/src/cmd/show.js

@@ -37,7 +37,7 @@ function runShow(cli, args) {
             summary: "Metadata card for a node: attrs, placement, open edges, last change (`cat` is the bytes)",
             usage: "show <node…|-> [--include history]",
             options: [
-                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a repo-relative doc path"],
+                ["<node…>", "one or more refs: a block id (`b_…`), a doc id (`d_…`), a node id (`n_…`), or a doc path (`/notes/x.md`; the leading `/` is optional)"],
                 ["-", `read refs from stdin, one per line (\`${cli.prog} q … --ids | ${cli.prog} show -\`)`],
                 ["--include <list>", "comma-separated extras; `history` adds the block's last 5 changes"],
             ],

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, awaitReady, WATCH_READY_PATIENCE_MS, EngineError } from "@omgbase/core";
+import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EngineError, surfaceSweepResult } from "@omgbase/core";
 import { runFsMirror } from "@omgbase/sync";
 import { EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
@@ -68,7 +68,8 @@ function runOneShot(cli, ws, repo) {
         cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
         return EXIT_OK;
     }
-    const result = freshnessSweep(ws.store, repo.repoId, repo.rootPath);
+    // The paths the sweep names are printed in the reference form (spec/surface §1 "Paths").
+    const result = surfaceSweepResult(freshnessSweep(ws.store, repo.repoId, repo.rootPath));
     // A `SweepResult` is a record (its lists are per-kind): every machine mode is the document.
     if (cli.flags.mode !== "human")
         return emitMachine(cli, result);

package/dist/src/cmd/update.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { docsUpdate, renderOpsetPlan } from "@omgbase/core";
+import { docsUpdate, renderOpsetPlan, surfaceDocsUpdate } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
@@ -76,10 +76,10 @@ async function runDocUpdate(cli, args) {
             ...(ws.omgbaseDir ? { omgbaseDir: ws.omgbaseDir } : {}),
             ...(values.actor ? { actor: values.actor } : {}),
         };
-        ({ opset, result } = docsUpdate(ws.store, ctx, doc, bytes, {
+        ({ opset, result } = surfaceDocsUpdate(docsUpdate(ws.store, ctx, doc, bytes, {
             dryRun,
             ...(values.reason ? { reason: values.reason } : {}),
-        }));
+        })));
     }
     if (cli.flags.mode !== "human") {
         cli.io.out(JSON.stringify({ opset, result }));

package/package.json

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