omgbase 0.3.0 → 0.4.1

package/dist/src/cmd/hist.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { resolveRef, historyNode } 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";
 // `omg hist <node>` (11 §5.5) — history_node: a block's biography.
 async function runHist(cli, args) {
@@ -34,15 +34,9 @@ async function runHist(cli, args) {
             throw new EngineErrorLike("block_missing", `hist needs a block id; got ${ref}`);
         changes = historyNode(ws.store, resolved.blockId, values.n ? { limit: Number(values.n) } : {});
     }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(changes));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const c of changes)
-            cli.io.out(JSON.stringify(c));
-        return EXIT_OK;
-    }
+    // A change carries no id of its own, so `--ids` is the `--json` document.
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, changes, { items: changes });
     const { style, io } = cli;
     if (changes.length === 0) {
         io.err(style.dim("  no history"));

package/dist/src/cmd/links.js

@@ -1,9 +1,9 @@
 import { parseArgs } from "node:util";
 import { resolveRef, docLinks } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // `omg links <node>` (11 §5.4) — open edges touching the node; default both
-// directions, grouped; doc-grain by default, --blocks for block-grain.
-// Backlinks = --in.
+// directions, grouped; doc-grain by default, --blocks for block-grain (one row
+// per edge, naming the source block). Backlinks = --in.
 function runLinks(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -45,30 +45,35 @@ function runLinks(cli, args) {
         opts.blocks = true;
     const result = docLinks(ws.store, resolved.docId, opts);
     cli.capture?.(result); // shell: edges (out+in) become the addressable frame
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "ids") {
-        for (const e of [...result.out, ...result.in])
-            cli.io.out(e.node);
-        return EXIT_OK;
-    }
+    // `{ out, in }` is not a list: `--jsonl` prints the document; `--ids` the far nodes.
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result, { ids: [...result.out, ...result.in].map((e) => e.node) });
     const { render, style, io } = cli;
     const g = render.g;
     if (result.out.length === 0 && result.in.length === 0) {
         io.err(style.dim("  no links"));
         return EXIT_OK;
     }
+    // Doc-grain: one row per (predicate, node) with its rollup count. Block-grain:
+    // one row per edge, the source block beside the far node.
+    const src = (e) => style.dim(`(${e.block ?? "frontmatter"})`);
     if (result.out.length > 0) {
         io.out(style.dim("  out"));
-        for (const e of result.out)
-            io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.node)} ${style.dim(`×${e.count}`)}`);
+        for (const e of result.out) {
+            if (values.blocks)
+                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.node)} ${src(e)}`);
+            else
+                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.node)} ${style.dim(`×${e.count}`)}`);
+        }
     }
     if (result.in.length > 0) {
         io.out(style.dim("  in (backlinks)"));
-        for (const e of result.in)
-            io.out(`    ${style.id(e.node)} ${style.dim(g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+        for (const e of result.in) {
+            if (values.blocks)
+                io.out(`    ${style.id(e.node)} ${src(e)} ${style.dim(g.arrow)} ${style.accent(e.predicate)}`);
+            else
+                io.out(`    ${style.id(e.node)} ${style.dim(g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+        }
     }
     return EXIT_OK;
 }

package/dist/src/cmd/log.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { changesSince } from "@omgbase/core";
-import { CliUsageError, truncationFooter, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, truncationFooter, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 // `omg log` (11 §5.5) — changes_since, one digest summary per line. Relative
 // --since (24h/7d) is resolved to a literal ISO timestamp client-side, then to
@@ -23,9 +23,12 @@ function relativeToIso(since) {
         const ms = unit === "h" ? 3600e3 : unit === "d" ? 86400e3 : unit === "w" ? 7 * 86400e3 : 30 * 86400e3;
         return new Date(Date.now() - n * ms).toISOString();
     }
-    // Absolute timestamp: pass through (Date normalizes).
+    // Absolute timestamp: pass through (Date normalizes). Anything else is the
+    // user's mistake, not "the epoch" (spec/cli §6 `log`).
     const t = Date.parse(since);
-    return Number.isNaN(t) ? new Date(0).toISOString() : new Date(t).toISOString();
+    if (Number.isNaN(t))
+        throw new CliUsageError(`bad --since '${since}' (use a relative age like 24h or 7d, or an ISO timestamp)`);
+    return new Date(t).toISOString();
 }
 async function runLog(cli, args) {
     const { values } = parseArgs({
@@ -76,21 +79,8 @@ async function runLog(cli, args) {
             opts.origin = values.origin;
         result = changesSince(ws.store, repo.repoId, opts);
     }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const d of result.digests)
-            cli.io.out(JSON.stringify(d));
-        if (result.truncated)
-            truncationFooter(cli.io, cli.style, result.cursor);
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "ids") {
-        for (const d of result.digests)
-            cli.io.out(d.commit);
-        return EXIT_OK;
+    if (cli.flags.mode !== "human") {
+        return emitMachine(cli, result, { items: result.digests, ids: result.digests.map((d) => d.commit), cursor: result.truncated ? result.cursor : null });
     }
     const { style, io } = cli;
     if (result.digests.length === 0) {

package/dist/src/cmd/ls.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { docsList } from "@omgbase/core";
 import { columns } from "../render.js";
-import { EXIT_OK, renderHelp } from "../output.js";
+import { EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 // `omg ls [glob]` (11 §5.2) — live documents: path, block count, last-commit
 // time. glob is a simple prefix/suffix match on the path (SQL LIKE with * → %).
@@ -39,20 +39,8 @@ async function runLs(cli, args) {
         cursor = page.truncated ? page.cursor : null;
     } while (cursor);
     cli.capture?.(rows); // shell: docs become the addressable frame (ref = path)
-    if (cli.flags.mode === "ids") {
-        for (const r of rows)
-            cli.io.out(r.path);
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(rows));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const r of rows)
-            cli.io.out(JSON.stringify(r));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r.path) });
     const { style, io } = cli;
     if (rows.length === 0) {
         io.err(style.dim("  no documents"));

package/dist/src/cmd/mcp.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, EmbedDrainer, EngineError, pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError } from "@omgbase/core";
+import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { installSpecSeams } from "../seams.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
@@ -11,38 +12,18 @@ 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).
+ * Announce the two conformance seams of spec/surface §7.1 on stderr (stdout is
+ * the protocol channel). They are installed for every verb at the entry point
+ * (`seams.ts`, spec/cli §2.6) — `mcp` only reports them, so a conformance run
+ * is visibly not a production one.
  */
-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());
+function announceSpecSeams(cli) {
+    const seams = installSpecSeams();
+    if (seams.minter) {
         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`));
+    if (seams.clock !== null) {
+        cli.io.err(cli.style.dim(`[mcp] spec seam: clock pinned to ${seams.clock} (OMGBASE_SPEC_CLOCK) — conformance run, not for production`));
     }
 }
 async function runMcp(cli, args) {
@@ -64,7 +45,7 @@ async function runMcp(cli, args) {
             notes: [`host config: {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]}`],
         });
     }
-    installSpecSeams(cli);
+    announceSpecSeams(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).
@@ -127,10 +108,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 +125,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

@@ -13,6 +13,20 @@ function block(cli, ws, repoId, ref) {
         throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
     return r.blockId;
 }
+// `done` addresses task blocks only (spec/cli §6): any other live block type is
+// a type_mismatch before an op is built — the macro itself would record a no-op
+// `edited` commit (its `attrs.checked` only rewrites a task's marker).
+function taskBlock(ws, ref, blockId) {
+    const row = ws.store.db
+        .prepare("SELECT type FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+        .get(blockId);
+    if (!row)
+        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+    if (row.type !== "task") {
+        throw new EngineErrorLike("type_mismatch", `not a task: ${ref} is a ${row.type}`, { data: { block: blockId, type: row.type } });
+    }
+    return blockId;
+}
 function rawHashOf(ws, blockId) {
     const row = ws.store.db
         .prepare("SELECT lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
@@ -67,33 +81,36 @@ 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)"],
             ],
         });
     }
     const to = positionals[0];
     if (!to)
-        throw new CliUsageError("insert requires a <to> parent (block id, or a heading id for section append)");
+        throw new CliUsageError("insert requires a <to> parent (a container block id, or a doc id/path for the top level)");
     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 +160,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 +181,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) --------------------
@@ -232,7 +252,7 @@ async function runDone(cli, args) {
         return runOpsRemote(cli, "tasks_complete", { blocks: refs, ...(values.undo ? { checked: false } : {}) });
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
+    const blocks = refs.map((r) => taskBlock(ws, r, block(cli, ws, repo.repoId, r)));
     const ops = values.undo
         ? blocks.map((b) => ({ op: "update", block: b, attrs: { checked: false }, expect: pinned(ws, b) }))
         : tasksComplete(ws.store, blocks);
@@ -295,7 +315,14 @@ async function runSplit(cli, args) {
         throw new CliUsageError("split requires a <block>");
     if (!values.at)
         throw new CliUsageError("split requires --at n[,n…]");
-    const at = values.at.split(",").map((s) => Number(s.trim()));
+    // Offsets are integers (spec/mutate §2.5); anything else is a usage error
+    // here, not a NaN that reaches the kernel.
+    const at = values.at.split(",").map((s) => {
+        const n = Number(s.trim());
+        if (s.trim() === "" || !Number.isInteger(n))
+            throw new CliUsageError(`bad --at '${values.at}' (offsets must be integers: n[,n…])`);
+        return n;
+    });
     if (cli.flags.server)
         return runOpsRemote(cli, "blocks_split", { block: ref, at });
     const ws = cli.workspace();

package/dist/src/cmd/node.js

@@ -28,8 +28,12 @@ async function runNode(cli, args) {
         });
     }
     if (sub === "set") {
-        parseArgs({ args: rest, allowPositionals: true, options: { actor: { type: "string" } } });
-        const [nodeId, prop, ...valueParts] = rest.filter((a) => !a.startsWith("--"));
+        // The value is every positional after <prop>, joined by a space; --actor
+        // (an option WITH a value) is taken out by the parser, never by a prefix
+        // filter — that filter used to leave the actor's value inside the property
+        // value (`checked "true human:spec"`), which the task editor read as false.
+        const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { actor: { type: "string" } } });
+        const [nodeId, prop, ...valueParts] = positionals;
         if (!nodeId || !prop || valueParts.length === 0)
             throw new CliUsageError("node set <nodeId> <prop> <value>");
         const value = valueParts.join(" ");
@@ -39,7 +43,7 @@ async function runNode(cli, args) {
         const ws = cli.workspace();
         const repo = cli.repo(ws);
         const ops = nodeSet(ws.store, nodeId, prop, value);
-        return runOps(cli, ws, repo, ops, { reason: `node_set ${prop}` });
+        return runOps(cli, ws, repo, ops, { reason: `node_set ${prop}`, ...(values.actor ? { actor: values.actor } : {}) });
     }
     if (sub === "props") {
         // `props` is a local editability lookup with no remote tool (a niche read).

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

@@ -1,2 +1,12 @@
+import { type OqxResult } from "@omgbase/core";
 import type { Command } from "../commands.js";
+import type { Cli } from "../context.js";
+/**
+ * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
+ * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
+ * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
+ * `--ids` the hit ids — a scalar result has neither, so those modes print the
+ * document. The truncation footer prints in every mode but `--json`.
+ */
+export declare function renderOqxResult(cli: Cli, result: OqxResult): number;
 export declare const cmdOqx: Command;

package/dist/src/cmd/oqx.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
 import { oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { truncationFooter, EngineErrorLike, EXIT_OK, renderHelp, renderHits } from "../output.js";
+import { truncationFooter, CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp, renderHits } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 import { readStdin } from "./_mutate.js";
@@ -85,10 +85,8 @@ async function runOqx(cli, args) {
     const source = values.file
         ? (values.file === "-" ? readStdin() : readFileSync(values.file, "utf8"))
         : positionals.join(" ").trim();
-    if (!source) {
-        cli.io.err(cli.style.dim("  usage: query <source>  (or -f file|-)"));
-        return EXIT_OK;
-    }
+    if (!source)
+        throw new CliUsageError("query requires a <source> (or -f file|-)");
     const opts = {};
     if (values.n)
         opts.limit = Number(values.n);
@@ -135,11 +133,24 @@ async function runOqx(cli, args) {
         : result.consumer === "exists" ? result.exists
             : result.consumer === "none" ? result.none
                 : result.values ?? result);
-    // JSON emits the whole result verbatim (incl. consumer + any scalar), so
-    // count/exists round-trip without special-casing.
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
+    return renderOqxResult(cli, result);
+}
+/**
+ * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
+ * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
+ * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
+ * `--ids` the hit ids — a scalar result has neither, so those modes print the
+ * document. The truncation footer prints in every mode but `--json`.
+ */
+export function renderOqxResult(cli, result) {
+    const cursor = result.truncated ? result.cursor ?? "" : null;
+    if (cli.flags.mode !== "human") {
+        const list = result.values ?? (result.consumer === "collect" || result.consumer === "first" || result.consumer === "single" ? result.hits : undefined);
+        return emitMachine(cli, result, {
+            ...(list ? { items: list } : {}),
+            ...(list && !result.values ? { ids: result.hits.map((h) => h.id) } : {}),
+            cursor,
+        });
     }
     // Scalar consumers (count/exists/none) have no hits — render the reduction itself.
     if (result.consumer === "count" || result.consumer === "exists" || result.consumer === "none") {
@@ -148,26 +159,12 @@ async function runOqx(cli, args) {
         return EXIT_OK;
     }
     // A `values` projection has no hits — one bare value per line (strings
-    // verbatim, anything else as JSON; `--jsonl` is JSON throughout).
+    // verbatim, anything else as JSON).
     if (result.values) {
         for (const v of result.values)
-            cli.io.out(typeof v === "string" && cli.flags.mode !== "jsonl" ? v : JSON.stringify(v));
-        if (result.truncated)
-            truncationFooter(cli.io, cli.style, result.cursor ?? "");
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "ids") {
-        for (const h of result.hits)
-            cli.io.out(h.id);
-        if (result.truncated)
-            truncationFooter(cli.io, cli.style, result.cursor ?? "");
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const h of result.hits)
-            cli.io.out(JSON.stringify(h));
-        if (result.truncated)
-            truncationFooter(cli.io, cli.style, result.cursor ?? "");
+            cli.io.out(typeof v === "string" ? v : JSON.stringify(v));
+        if (cursor !== null)
+            truncationFooter(cli.io, cli.style, cursor);
         return EXIT_OK;
     }
     const { style, io } = cli;

package/dist/src/cmd/outline.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { findDoc, docsOutline } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, renderHelp } from "../output.js";
+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
 // prints the outline text with full block ids inline; --json emits the
@@ -11,7 +11,6 @@ async function runOutline(cli, args) {
         allowPositionals: true,
         options: {
             depth: { type: "string" },
-            section: { type: "string" },
             skeleton: { type: "boolean" },
             help: { type: "boolean" },
         },
@@ -20,10 +19,9 @@ async function runOutline(cli, args) {
         return renderHelp(cli, {
             name: "outline",
             summary: "A document's outline with block ids inline (frozen wire format) — the orientation view",
-            usage: "outline <doc|path> [--depth <n>] [--section <locator>] [--skeleton]",
+            usage: "outline <doc|path> [--depth <n>] [--skeleton]",
             options: [
                 ["--depth <n>", "limit heading depth"],
-                ["--section <locator>", "outline only the section at a locator"],
                 ["--skeleton", "structure only, no text"],
             ],
         });
@@ -57,10 +55,9 @@ async function runOutline(cli, args) {
         result = docsOutline(ws.store, info.docId, opts);
         header = info.path;
     }
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
+    // `{ text, truncated }` carries neither a list nor ids: every machine mode is the document.
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result, { cursor: result.truncated ? "budget" : null });
     const { render, style, io } = cli;
     io.out(render.wordmark(header));
     io.out(render.rule(40));

package/dist/src/cmd/retarget.js

@@ -1,11 +1,12 @@
 import { parseArgs } from "node:util";
 import { linksRetarget } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
-import { runOps } from "./_mutate.js";
+import { runOps, unifiedDiffLines } from "./_mutate.js";
 import { remoteCall } from "./_remote.js";
 // `omg retarget <from> <to> [--scope glob] [--apply]` (11 §5.6) — plan-by-default.
-// Without --apply it runs the dry-run and prints the per-block diffs (the 06 §4
-// "always dry-run first" contract, encoded as the default). --apply commits.
+// Without --apply it runs the dry-run and prints, per hit block, the unified
+// diff of its raw (the same diff every other preview prints — the 06 §4 "always
+// dry-run first" contract, encoded as the default). --apply commits.
 async function runRetarget(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -65,27 +66,11 @@ function renderPlan(cli, from, to, hits) {
     io.err(style.dim(`  plan — ${hits.length} block(s) would change; re-run with --apply to commit`));
     for (const h of hits) {
         io.out(style.id(h.block));
-        for (const line of lineDiff(h.oldRaw, h.newRaw)) {
-            io.out(line.startsWith("+") ? style.ok(line) : line.startsWith("-") ? style.err(line) : style.dim(line));
-        }
+        for (const line of unifiedDiffLines(cli, h.oldRaw, h.newRaw))
+            io.out(line);
         io.out("");
     }
     return EXIT_OK;
 }
-function lineDiff(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 const cmdRetarget = { name: "retarget", summary: "Rewrite a link target (plan-by-default)", run: (c, a) => runRetarget(c, a) };
 //# sourceMappingURL=retarget.js.map