omgbase 0.3.0 → 0.4.1

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

@@ -44,4 +44,16 @@ export declare function runOps(cli: Cli, ws: Workspace, repo: RepoRow, ops: Op[]
  * tool's dry_run so the preview comes back without committing.
  */
 export declare function runOpsRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>): Promise<number>;
+/**
+ * The dry-run rendering every write verb shares (spec/cli §3.6): the note on
+ * stderr, then per changed file the path, the unified diff of before → after
+ * (`spec/surface` §3) and an empty line. Document verbs hand their
+ * `DocOpResult.diffs` here; block verbs their `ApplyResult.diffs`.
+ */
+export declare function renderDiffs(cli: Cli, diffs: Record<string, {
+    before: string;
+    after: string;
+}>): void;
+/** The unified diff of before → after (`spec/surface` §3), one styled line per entry. */
+export declare function unifiedDiffLines(cli: Cli, before: string, after: string): string[];
 export { EXIT_OK, EXIT_ERROR };

package/dist/src/cmd/_mutate.js

@@ -162,22 +162,35 @@ function renderApply(cli, result) {
     return cli.flags.dryRun ? renderDryRun(cli, result) : renderCommitted(cli, result);
 }
 function renderDryRun(cli, result) {
-    const { render, style, io } = cli;
-    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 ?? {})) {
+    renderDiffs(cli, result.diffs ?? {});
+    return EXIT_OK;
+}
+/**
+ * The dry-run rendering every write verb shares (spec/cli §3.6): the note on
+ * stderr, then per changed file the path, the unified diff of before → after
+ * (`spec/surface` §3) and an empty line. Document verbs hand their
+ * `DocOpResult.diffs` here; block verbs their `ApplyResult.diffs`.
+ */
+export function renderDiffs(cli, diffs) {
+    const { style, io } = cli;
+    io.err(style.dim(`  dry run — ${Object.keys(diffs).length} file(s) would change, nothing committed`));
+    for (const [path, { before, after }] of Object.entries(diffs)) {
         io.out(`${style.bold(path)}`);
-        for (const line of unifiedDiff(before, after).split("\n")) {
-            if (line.startsWith("+"))
-                io.out(style.ok(line));
-            else if (line.startsWith("-"))
-                io.out(style.err(line));
-            else
-                io.out(style.dim(line));
-        }
+        for (const line of unifiedDiffLines(cli, before, after))
+            io.out(line);
         io.out("");
     }
-    void render;
-    return EXIT_OK;
+}
+/** The unified diff of before → after (`spec/surface` §3), one styled line per entry. */
+export function unifiedDiffLines(cli, before, after) {
+    const { style } = cli;
+    return unifiedDiff(before, after).split("\n").map((line) => {
+        if (line.startsWith("+"))
+            return style.ok(line);
+        if (line.startsWith("-"))
+            return style.err(line);
+        return style.dim(line);
+    });
 }
 function renderCommitted(cli, result) {
     const { render, style, io } = cli;

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/admin.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
-import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, RepoSelectionError, } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, renderHelp } from "../output.js";
+import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding, drainEmbeddings } from "./_embed.js";
 // admin/maintenance (11 §5.8–5.9). The live watcher moved to `omg sync --watch`.
 // ---- rebuild-index ----------------------------------------------------------
@@ -27,6 +27,9 @@ function runRebuild(cli, args) {
     const target = values.sections ? "sections" : values.edges ? "edges" : values.fts ? "fts" : values["block-changes"] ? "block_changes" : "all";
     const ws = cli.workspace();
     rebuildIndex(ws.store, target);
+    // The library call returns nothing; the machine result names what was rebuilt.
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { rebuilt: target });
     cli.io.err(cli.style.dim(`  ${cli.style.ok(cli.render.g.ok)} rebuilt ${target}`));
     return EXIT_OK;
 }
@@ -52,9 +55,8 @@ function runGcCmd(cli, args) {
     }
     const result = runGc(ws.store, { enabled: enabled || dryRun });
     if (cli.flags.mode !== "human")
-        cli.io.out(JSON.stringify(result));
-    else
-        cli.io.err(cli.style.dim(`  swept ${result.blobsSwept} blobs, ${result.treeNodesSwept} tree nodes`));
+        return emitMachine(cli, result);
+    cli.io.err(cli.style.dim(`  swept ${result.blobsSwept} blobs, ${result.treeNodesSwept} tree nodes`));
     return EXIT_OK;
 }
 // ---- doctor -----------------------------------------------------------------
@@ -63,7 +65,7 @@ function runDoctor(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "doctor",
-            summary: "Invariant sweep: convergence, FTS rows vs live blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
+            summary: "Invariant sweep: convergence, FTS rows vs live leaf blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
             usage: "doctor [--json]",
             options: [["--json", "`{ ok, checks: [{ name, ok, detail }] }`"]],
         });
@@ -74,16 +76,19 @@ function runDoctor(cli, args) {
     const checks = [];
     const status = reposStatus(ws.store, repo.repoId);
     checks.push({ name: "convergence", ok: status.unconverged === 0, detail: `${status.unconverged} unconverged` });
-    const ftsCount = db.prepare("SELECT count(*) c FROM blocks_fts").get().c;
-    const liveBlocks = db.prepare("SELECT count(*) c FROM blocks WHERE deleted_commit IS NULL").get().c;
-    checks.push({ name: "fts rows == live blocks", ok: ftsCount === liveBlocks, detail: `fts=${ftsCount} live=${liveBlocks}` });
+    // The index holds exactly the live LEAF blocks (spec/search §1.1): a container
+    // has no row, a tombstone none. Counted from the index's shadow table — a plain
+    // count(*) on an external-content FTS table answers from `blocks` instead.
+    const ftsCount = ftsIndexedRowCount(db);
+    const leaves = liveLeafCount(db);
+    checks.push({ name: "fts rows == live leaf blocks", ok: ftsCount === leaves, detail: `fts=${ftsCount} leaves=${leaves}` });
     const dangling = db.prepare("SELECT count(*) c FROM docs d WHERE d.deleted_commit IS NULL AND d.current_rev IS NOT NULL AND NOT EXISTS (SELECT 1 FROM revisions r WHERE r.rev_id = d.current_rev)").get().c;
     checks.push({ name: "no dangling current_rev", ok: dangling === 0, detail: `${dangling} dangling` });
     const integrity = db.pragma("integrity_check", { simple: true });
     checks.push({ name: "sqlite integrity", ok: integrity === "ok", detail: integrity });
     const allOk = checks.every((c) => c.ok);
     if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ ok: allOk, checks }));
+        emitMachine(cli, { ok: allOk, checks });
         return allOk ? EXIT_OK : EXIT_ERROR;
     }
     const { style, io, render } = cli;
@@ -104,9 +109,10 @@ function resolveConfigScope(cli, ws) {
         // An explicit --repo <slug> that doesn't resolve is a real error. A bare
         // (cwd-based) selection that's ambiguous or empty just means "workspace
         // layer" — the workspace is what you mean when not clearly inside a repo.
+        // (`Cli.repo` has already wrapped the RepoSelectionError as repo_not_found.)
         if (cli.flags.repo)
             throw err;
-        if (err instanceof RepoSelectionError)
+        if (err instanceof EngineErrorLike && err.code === "repo_not_found")
             return { kind: "workspace" };
         throw err;
     }
@@ -139,7 +145,7 @@ function runConfig(cli, args) {
         if (scope.kind === "workspace") {
             const s = workspaceSettings(ws.store);
             if (cli.flags.mode !== "human")
-                cli.io.out(JSON.stringify(s));
+                return emitMachine(cli, s);
             else {
                 cli.io.err(cli.style.dim(`  workspace defaults`));
                 for (const [k, v] of Object.entries(s))
@@ -149,10 +155,8 @@ function runConfig(cli, args) {
         }
         const effective = resolveSettings(ws.store, scope.repoId);
         const own = repoOwnSettings(ws.store, scope.repoId);
-        if (cli.flags.mode !== "human") {
-            cli.io.out(JSON.stringify(effective));
-            return EXIT_OK;
-        }
+        if (cli.flags.mode !== "human")
+            return emitMachine(cli, effective);
         cli.io.err(cli.style.dim(`  ${label} (effective; ${cli.render.g.diamond} = overrides workspace default)`));
         for (const [k, v] of Object.entries(effective)) {
             const overridden = Object.prototype.hasOwnProperty.call(own, k);
@@ -210,17 +214,16 @@ async function runEmbed(cli, args) {
         // No provider configured (05 §6). Honest report; not an error.
         const hint = 'set one with `omg config set embedding.provider <command|url>` (e.g. omgbase-embedder)';
         if (cli.flags.mode !== "human")
-            cli.io.out(JSON.stringify({ provider: null, queued: 0 }));
-        else
-            cli.io.err(cli.style.dim(`  no embedding provider configured — ${hint}`));
+            return emitMachine(cli, { provider: null, queued: 0 });
+        cli.io.err(cli.style.dim(`  no embedding provider configured — ${hint}`));
         return EXIT_OK;
     }
     if (sub === "drain") {
         await loaded.close(); // drainEmbeddings connects its own provider
         const result = await drainEmbeddings(cli, ws, repo.repoId, { verbose, prune });
         if (cli.flags.mode !== "human")
-            cli.io.out(JSON.stringify({ provider: loaded.providerName, ...(result ?? { embedded: 0, cached: 0 }) }));
-        else if (result)
+            return emitMachine(cli, { provider: loaded.providerName, ...(result ?? { embedded: 0, cached: 0 }) });
+        if (result)
             cli.io.err(`  ${cli.style.ok(cli.render.g.ok)} embedded ${result.embedded}, cached ${result.cached}`);
         return EXIT_OK;
     }
@@ -236,7 +239,7 @@ async function runEmbed(cli, args) {
         // status
         const payload = { provider: loaded.providerName, model: loaded.provider.model, dim: loaded.provider.dim, embeddable: tasks.length, queued: pending.length, docs: docTasks.length, docsQueued: docPending.length, foreignBlocks: foreign.blocks, foreignDocs: foreign.docs };
         if (cli.flags.mode !== "human")
-            cli.io.out(JSON.stringify(payload));
+            return emitMachine(cli, payload);
         else {
             cli.io.out(`  provider  ${cli.style.accent(loaded.providerName)} ${cli.style.dim(`(${loaded.provider.model}, ${loaded.provider.dim}d)`)}`);
             cli.io.out(`  embeddable ${tasks.length}   ${cli.style.dim("queued")} ${payload.queued}`);

package/dist/src/cmd/bootstrap.js

@@ -3,9 +3,9 @@ import { join, resolve, dirname, relative, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline";
 import { spawnSync } from "node:child_process";
-import { Workspace, reposStatus, workspaceSettings, writeWorkspaceSettings } from "@omgbase/core";
+import { Workspace, reposStatus, reposList, workspaceSettings, writeWorkspaceSettings } from "@omgbase/core";
 import { columns as columnsLocal } from "../render.js";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // Bootstrap: init / repos (11 §5.1). Pointing a repo at a directory is
 // `omg source add <dir>` (ADR-014) — a repo owns identity; sources bring bytes.
 async function confirmTTY(cli, question) {
@@ -183,10 +183,8 @@ async function runInit(cli, args) {
     finally {
         ws.close();
     }
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ workspace: dir }));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { workspace: dir });
     const { render, style, io } = cli;
     io.out(render.wordmark("initialized"));
     io.out(render.rule(40));
@@ -209,25 +207,19 @@ function runRepos(cli, args) {
             name: "repos",
             summary: "List the repos in this workspace: slug, root path (from its fs source), doc/block counts",
             usage: "repos [--ids|--json|--jsonl]",
-            options: [["--ids", "slugs only, one per line"]],
+            options: [
+                ["--ids", "slugs only, one per line"],
+                ["--json", "the `repos` tool's result: `{ repos: [{ slug, hasSource }] }` (counts are `status --json`)"],
+            ],
         });
     }
     const ws = cli.workspace();
+    // `--json` is the `repos` tool's result; the human table adds each repo's root
+    // and its `repos_status` counts, which the reader wants at a glance.
+    const list = reposList(ws.store);
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, list, { items: list.repos, ids: list.repos.map((r) => r.slug) });
     const repos = ws.repos().map((r) => ({ ...r, status: reposStatus(ws.store, r.repoId) }));
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(repos.map((r) => ({ slug: r.slug, root: r.rootPath, docs: r.status.docs, blocks: r.status.blocks }))));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const r of repos)
-            cli.io.out(JSON.stringify({ slug: r.slug, root: r.rootPath, docs: r.status.docs, blocks: r.status.blocks }));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "ids") {
-        for (const r of repos)
-            cli.io.out(r.slug);
-        return EXIT_OK;
-    }
     const { render, style, io } = cli;
     const rows = repos.map((r) => [
         `  ${render.g.diamond} ${style.accent(r.slug)}`,
@@ -236,7 +228,7 @@ function runRepos(cli, args) {
         style.dim(`${r.status.blocks} blocks`),
     ]);
     if (rows.length === 0)
-        io.out(style.dim("  no repos attached"));
+        io.err(style.dim("  no repos attached"));
     else
         for (const line of columnsLocal(rows))
             io.out(line);

package/dist/src/cmd/cat.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { resolveRef, nodesGet, docsRead } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 import { expandBlockArgs } from "./_mutate.js";
 /** `--resolution` only means something for a block; say so (stderr) rather than
@@ -16,7 +16,10 @@ async function catOne(cli, ref, resolution) {
         const r = await remoteCall(cli, "read_ref", { ref, ...(resolution !== "raw" ? { resolution } : {}) });
         if (r.kind === "document") {
             warnDocResolution(cli, ref, resolution);
-            return { text: String(r.content ?? ""), json: { doc: r.docId, path: r.path, content: r.content }, capture: r.content };
+            // The `docs_read` result is the `read_ref` document result without `kind`.
+            const { kind: _kind, ...doc } = r;
+            void _kind;
+            return { text: String(r.content ?? ""), json: doc, capture: r.content };
         }
         return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
     }
@@ -35,8 +38,8 @@ async function catOne(cli, ref, resolution) {
         if (!res)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         warnDocResolution(cli, ref, resolution);
-        // shell: the bytes (a string; @_ only)
-        return { text: res.content, json: { doc: res.docId, path: res.path, content: res.content }, capture: res.content };
+        // shell: the bytes (a string; @_ only). `--json` is the `docs_read` result.
+        return { text: res.content, json: res, capture: res.content };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution });
     if (!node)
@@ -72,14 +75,9 @@ async function runCat(cli, args) {
     // One ref keeps the single-entity shape (a string/object); several become a list.
     const single = results.length === 1 ? results[0] : null;
     cli.capture?.(single ? single.capture : results.map((r) => r.capture));
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(single ? single.json : results.map((r) => r.json)));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const r of results)
-            cli.io.out(JSON.stringify(r.json));
-        return EXIT_OK;
+    if (cli.flags.mode !== "human") {
+        const docs = results.map((r) => r.json);
+        return single ? emitMachine(cli, single.json) : emitMachine(cli, docs, { items: docs });
     }
     for (const r of results)
         cli.io.out(r.text);

package/dist/src/cmd/diff.js

@@ -1,37 +1,39 @@
 import { parseArgs } from "node:util";
-import { findDoc, diffUnified } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { findDoc, docDiffUnified, diffBlocks } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
-// `omg diff <doc>` (11 §5.5) — unified diff. With no revisions: current vs
-// previous ("what did the last commit do here").
+// `omg diff <doc>` (11 §5.5) — `diff_unified`: the unified diff, `--json` the
+// tool's `{ doc, path, from, to, diff }`. With no revisions: current vs previous
+// ("what did the last commit do here"). `--blocks` is the block-grain `diff`
+// tool: added/removed/changed blocks between the same two revisions.
 async function runDiff(cli, args) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
-        options: { from: { type: "string" }, to: { type: "string" }, help: { type: "boolean" } },
+        options: { from: { type: "string" }, to: { type: "string" }, blocks: { type: "boolean" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "diff",
             summary: "Unified diff of a document between two revisions (default: previous → current)",
-            usage: "diff <doc> [--from <rev>] [--to <rev>]",
+            usage: "diff <doc> [--from <rev>] [--to <rev>] [--blocks]",
             options: [
                 ["--from <rev>", "older revision id (default: the one before --to)"],
                 ["--to <rev>", "newer revision id (default: current)"],
+                ["--blocks", "block-grain: which blocks were added, removed or changed (the `diff` tool)"],
             ],
         });
     }
     const ref = positionals[0];
     if (!ref)
         throw new CliUsageError("diff requires a <doc>");
-    let docId, path, fromRev, toRev, text;
+    let result;
     if (cli.flags.server) {
-        const r = await remoteCall(cli, "diff_unified", {
+        result = await remoteCall(cli, "diff_unified", {
             doc: ref,
             ...(values.from ? { from_rev: values.from } : {}),
             ...(values.to ? { to_rev: values.to } : {}),
         });
-        ({ doc: docId, path, from: fromRev, to: toRev, diff: text } = r);
     }
     else {
         const ws = cli.workspace();
@@ -39,30 +41,40 @@ async function runDiff(cli, args) {
         const info = ref.startsWith("d_") ? findDoc(ws.store, { docId: ref }) : findDoc(ws.store, { repoId: repo.repoId, path: ref });
         if (!info)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
-        // Resolve from/to revisions: default is (previous, current) by seq desc.
-        const revs = ws.store.db
-            .prepare("SELECT rev_id, seq FROM revisions WHERE doc_id = ? ORDER BY seq DESC LIMIT 2")
-            .all(info.docId);
-        const to = values.to ?? revs[0]?.rev_id;
-        const from = values.from ?? revs[1]?.rev_id ?? revs[0]?.rev_id;
-        if (!to || !from)
-            throw new EngineErrorLike("doc_missing", `no revisions to diff for ${ref}`);
-        docId = info.docId;
-        path = info.path;
-        fromRev = from;
-        toRev = to;
-        text = diffUnified(ws.store, info.docId, from, to);
+        result = docDiffUnified(ws.store, info.docId, {
+            ...(values.from ? { fromRev: values.from } : {}),
+            ...(values.to ? { toRev: values.to } : {}),
+            label: ref,
+        });
     }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify({ doc: docId, path, from: fromRev, to: toRev, diff: text }));
+    const { style, io } = cli;
+    if (values.blocks) {
+        // Block-grain over the same resolved revision pair.
+        let entries;
+        if (cli.flags.server)
+            entries = await remoteCall(cli, "diff", { doc: ref, from_rev: result.from, to_rev: result.to });
+        else
+            entries = diffBlocks(cli.workspace().store, result.doc, result.from, result.to);
+        if (cli.flags.mode !== "human")
+            return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e.blockId) });
+        if (entries.length === 0) {
+            io.err(style.dim("  no changes"));
+            return EXIT_OK;
+        }
+        for (const e of entries) {
+            const mark = e.kind === "added" ? style.ok("+") : e.kind === "removed" ? style.err("-") : style.warn("~");
+            const preview = (e.after ?? e.before ?? "").split("\n")[0] ?? "";
+            io.out(`${mark} ${style.id(e.blockId)}  ${preview}`.trimEnd());
+        }
         return EXIT_OK;
     }
-    const { style, io } = cli;
-    if (!text) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result);
+    if (!result.diff) {
         io.err(style.dim("  no changes"));
         return EXIT_OK;
     }
-    for (const line of text.split("\n")) {
+    for (const line of result.diff.split("\n")) {
         if (line.startsWith("+"))
             io.out(style.ok(line));
         else if (line.startsWith("-"))

package/dist/src/cmd/docs.js

@@ -2,22 +2,48 @@ import { parseArgs } from "node:util";
 import { parse as parseYamlScalar } from "yaml";
 import { docsCreate, docsMove, docsDelete, docsSetMeta } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
-import { readContent, extractContentOpts } from "./_mutate.js";
+import { readContent, extractContentOpts, renderDiffs } from "./_mutate.js";
 import { remoteCall } from "./_remote.js";
 // Document-level commands (11 §5.6): new / mv / rm --doc / meta. Thin wrappers
 // 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.
 function ctxOf(cli, ws, repoId, rootPath, actor) {
-    return { repoId, ...(rootPath ? { rootPath } : {}), omgbaseDir: ws.omgbaseDir, ...(actor ? { actor } : {}) };
+    return {
+        repoId,
+        ...(rootPath ? { rootPath } : {}),
+        omgbaseDir: ws.omgbaseDir,
+        ...(actor ? { actor } : {}),
+        ...(cli.flags.dryRun ? { dryRun: true } : {}),
+    };
 }
 function report(cli, verb, res) {
     if (cli.flags.mode !== "human") {
         cli.io.out(JSON.stringify(res));
         return EXIT_OK;
     }
+    if (cli.flags.dryRun) {
+        renderDiffs(cli, res.diffs ?? {});
+        return EXIT_OK;
+    }
     cli.io.err(cli.style.dim(`  ${cli.style.ok(cli.render.g.ok)} ${verb} ${cli.style.accent(res.path)}`));
     cli.io.out(res.docId);
     return EXIT_OK;
 }
+// `mv` does not rewrite inbound links; say so wherever the move is reported
+// (spec/cli §6 `mv`): the human confirmation carries the same `dangling` list
+// the --json result does, with the retarget that fixes them.
+function reportMove(cli, from, res) {
+    const code = report(cli, "moved to", res);
+    if (cli.flags.mode !== "human" || res.dangling.length === 0)
+        return code;
+    const { style, io } = cli;
+    const where = res.dangling.map((l) => (l.block ? `${l.path} ${l.block}` : `${l.path} (frontmatter)`)).join(", ");
+    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}`));
+    io.err(style.dim(`  fix: ${cli.prog} retarget /${from} /${res.path} --apply`));
+    return code;
+}
 // ---- new --------------------------------------------------------------------
 async function runNew(cli, args) {
     const content = extractContentOpts(args);
@@ -44,7 +70,7 @@ async function runNew(cli, args) {
         throw new CliUsageError("new requires a <path>");
     const bytes = readContent(content);
     if (cli.flags.server) {
-        return report(cli, "created", await remoteCall(cli, "docs_create", { path, markdown: bytes }));
+        return report(cli, "created", await remoteCall(cli, "docs_create", { path, markdown: bytes, ...dryRunArg(cli) }));
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -71,17 +97,18 @@ async function runMv(cli, args) {
     if (!doc || !toPath)
         throw new CliUsageError("mv requires <doc> and <new-path>");
     if (cli.flags.server) {
-        return report(cli, "moved to", await remoteCall(cli, "docs_move", { doc, to_path: toPath }));
+        const res = await remoteCall(cli, "docs_move", { doc, to_path: toPath, ...dryRunArg(cli) });
+        return reportMove(cli, fromPathOf(res, doc), res);
     }
     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);
-    return report(cli, "moved to", res);
+    return reportMove(cli, fromPathOf(res, doc), res);
 }
 // ---- rm --doc (block rm lives in mutate.ts; this handles the --doc branch) --
 export async function runRmDoc(cli, doc, actor) {
     if (cli.flags.server) {
-        return report(cli, "deleted", await remoteCall(cli, "docs_delete", { doc }));
+        return report(cli, "deleted", await remoteCall(cli, "docs_delete", { doc, ...dryRunArg(cli) }));
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -141,6 +168,7 @@ async function runMeta(cli, args) {
             doc,
             ...(Object.keys(set).length ? { set } : {}),
             ...(unset.length ? { unset } : {}),
+            ...dryRunArg(cli),
         }));
     }
     const ws = cli.workspace();
@@ -148,6 +176,16 @@ async function runMeta(cli, args) {
     const res = 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.
+function fromPathOf(res, ref) {
+    const named = res.dangling.find((l) => l.target)?.target;
+    return (named ?? ref).replace(/^\/+/, "");
+}
 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) };
 export const cmdMeta = { name: "meta", summary: "Patch a document's frontmatter", run: (c, a) => runMeta(c, a) };

package/dist/src/cmd/find.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { resolve as resolveThing } from "@omgbase/core";
-import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 // `omg find <text>` (11 §5.2) — resolve: ranked {id, locator, preview,
@@ -68,20 +68,8 @@ async function runFind(cli, args) {
             cli.io.out(hits[0].id);
         return EXIT_OK;
     }
-    if (cli.flags.mode === "ids") {
-        for (const h of hits)
-            cli.io.out(h.id);
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(hits));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const h of hits)
-            cli.io.out(JSON.stringify(h));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, hits, { items: hits, ids: hits.map((h) => h.id) });
     const { style, io } = cli;
     if (hits.length === 0) {
         io.err(style.dim("  no matches"));