omgbase 0.1.0

package/dist/src/cmd/diff.js

@@ -0,0 +1,76 @@
+import { parseArgs } from "node:util";
+import { findDoc, diffUnified } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, 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").
+async function runDiff(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { from: { type: "string" }, to: { type: "string" }, 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>]",
+            options: [
+                ["--from <rev>", "older revision id (default: the one before --to)"],
+                ["--to <rev>", "newer revision id (default: current)"],
+            ],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("diff requires a <doc>");
+    let docId, path, fromRev, toRev, text;
+    if (cli.flags.server) {
+        const r = 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();
+        const repo = cli.repo(ws);
+        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);
+    }
+    if (cli.flags.mode === "json") {
+        cli.io.out(JSON.stringify({ doc: docId, path, from: fromRev, to: toRev, diff: text }));
+        return EXIT_OK;
+    }
+    const { style, io } = cli;
+    if (!text) {
+        io.err(style.dim("  no changes"));
+        return EXIT_OK;
+    }
+    for (const line of text.split("\n")) {
+        if (line.startsWith("+"))
+            io.out(style.ok(line));
+        else if (line.startsWith("-"))
+            io.out(style.err(line));
+        else
+            io.out(line);
+    }
+    return EXIT_OK;
+}
+export const cmdDiff = { name: "diff", summary: "Unified diff of a document", run: (cli, a) => runDiff(cli, a) };
+//# sourceMappingURL=diff.js.map

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

@@ -0,0 +1,6 @@
+import type { Cli } from "../context.js";
+import type { Command } from "../commands.js";
+export declare function runRmDoc(cli: Cli, doc: string, actor?: string): Promise<number>;
+export declare const cmdNew: Command;
+export declare const cmdMv: Command;
+export declare const cmdMeta: Command;

package/dist/src/cmd/docs.js

@@ -0,0 +1,154 @@
+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 { 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.
+function ctxOf(cli, ws, repoId, rootPath, actor) {
+    return { repoId, ...(rootPath ? { rootPath } : {}), omgbaseDir: ws.omgbaseDir, ...(actor ? { actor } : {}) };
+}
+function report(cli, verb, res) {
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify(res));
+        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;
+}
+// ---- new --------------------------------------------------------------------
+async function runNew(cli, args) {
+    const content = extractContentOpts(args);
+    const { values, positionals } = parseArgs({
+        args: content.rest,
+        allowPositionals: true,
+        options: { actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "new",
+            summary: "Create a document at <path> from complete file bytes (frontmatter included)",
+            usage: "new <path> (-m <markdown> | -f <file> | -) [--actor <s>] [--dry-run]",
+            options: [
+                ["-m <markdown>", "content inline"],
+                ["-f <file>", "content from a file"],
+                ["-", "content from stdin"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const path = positionals[0];
+    if (!path)
+        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 }));
+    }
+    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);
+    return report(cli, "created", res);
+}
+// ---- mv ---------------------------------------------------------------------
+async function runMv(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "mv",
+            summary: "Rename/move a document to a new path; its identity and history are preserved",
+            usage: "mv <doc> <new-path> [--actor <s>] [--dry-run]",
+            options: [["--actor <s>", "commit actor (default human:$USER)"]],
+        });
+    }
+    const doc = positionals[0];
+    const toPath = positionals[1];
+    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 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);
+}
+// ---- 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 }));
+    }
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const res = docsDelete(ws.store, ctxOf(cli, ws, repo.repoId, repo.rootPath, actor), doc);
+    return report(cli, "deleted", res);
+}
+// ---- meta -------------------------------------------------------------------
+async function runMeta(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            set: { type: "string", multiple: true },
+            "set-json": { type: "string", multiple: true },
+            unset: { type: "string", multiple: true },
+            actor: { type: "string" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "meta",
+            summary: "Surgical frontmatter patch: set/unset keys without touching the body",
+            usage: "meta <doc> [--set k=v]… [--set-json k=<json>]… [--unset k]… [--actor <s>] [--dry-run]",
+            options: [
+                ["--set k=v", "set a string value (repeatable)"],
+                ["--set-json k=<json>", "set a typed value from JSON (repeatable)"],
+                ["--unset k", "remove a key (repeatable)"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const doc = positionals[0];
+    if (!doc)
+        throw new CliUsageError("meta requires a <doc>");
+    const set = {};
+    for (const kv of values.set ?? []) {
+        const eq = kv.indexOf("=");
+        if (eq < 0)
+            throw new CliUsageError(`--set expects k=v, got '${kv}'`);
+        const key = kv.slice(0, eq);
+        const val = kv.slice(eq + 1);
+        // YAML scalar parse: numbers/bools/null become typed, strings stay strings.
+        set[key] = parseYamlScalar(val);
+    }
+    for (const kv of values["set-json"] ?? []) {
+        const eq = kv.indexOf("=");
+        if (eq < 0)
+            throw new CliUsageError(`--set-json expects k=json, got '${kv}'`);
+        set[kv.slice(0, eq)] = JSON.parse(kv.slice(eq + 1));
+    }
+    const unset = values.unset ?? [];
+    if (Object.keys(set).length === 0 && unset.length === 0)
+        throw new CliUsageError("meta requires --set or --unset");
+    if (cli.flags.server) {
+        return report(cli, "patched", await remoteCall(cli, "docs_set_meta", {
+            doc,
+            ...(Object.keys(set).length ? { set } : {}),
+            ...(unset.length ? { unset } : {}),
+        }));
+    }
+    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 });
+    return report(cli, "patched", res);
+}
+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) };
+//# sourceMappingURL=docs.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdEdit: Command;

package/dist/src/cmd/edit.js

@@ -0,0 +1,74 @@
+import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { writeFileSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveRef, nodesGet } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { runOps } from "./_mutate.js";
+// `omg edit <block>` (11 §5.6, §5.7): read the block's raw markdown → open it in
+// $EDITOR → update with the PRE-READ hash pinned as CAS. A mid-edit change by
+// someone else lands as a clean stale_expectation (with current truth), never a
+// lost write. The human structural-edit loop.
+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")
+        .get(blockId);
+    return row?.h ?? null;
+}
+function runEdit(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "edit",
+            summary: "Open a block's markdown in $EDITOR and write it back with compare-and-swap pinned to what you saw",
+            usage: "edit <block> [--actor <s>] [--dry-run]",
+            options: [["--actor <s>", "commit actor (default human:$USER)"]],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("edit requires a <block>");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const resolved = resolveRef(ws.store, repo.repoId, ref);
+    if (!resolved || resolved.kind !== "block")
+        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+    const blockId = resolved.blockId;
+    const node = nodesGet(ws.store, resolved.docId, blockId, { resolution: "raw" });
+    const before = node?.raw ?? "";
+    const preHash = rawHashOf(ws, blockId); // pin BEFORE the editor opens
+    const editor = process.env.OMG_EDITOR ?? process.env.VISUAL ?? process.env.EDITOR;
+    if (!editor)
+        throw new EngineErrorLike("target_missing", "no $EDITOR set (or $VISUAL/$OMG_EDITOR)");
+    if (!cli.io.stdoutTTY && !process.env.OMG_EDITOR) {
+        // Interactive editors need a terminal; OMG_EDITOR (e.g. a script) is the
+        // scripted/test escape hatch.
+        throw new EngineErrorLike("target_missing", "edit needs a TTY; set OMG_EDITOR to a non-interactive editor for scripts");
+    }
+    const dir = mkdtempSync(join(tmpdir(), "omg-edit-"));
+    const file = join(dir, "block.md");
+    try {
+        writeFileSync(file, before);
+        const [cmd, ...preArgs] = editor.split(/\s+/);
+        const res = spawnSync(cmd, [...preArgs, file], { stdio: "inherit" });
+        if (res.status !== 0)
+            throw new EngineErrorLike("target_missing", `editor exited ${res.status ?? "abnormally"}`);
+        const after = readFileSync(file, "utf8");
+        if (after === before) {
+            cli.io.err(cli.style.dim("  no changes"));
+            return EXIT_OK;
+        }
+        const op = { op: "update", block: blockId, markdown: after, ...(preHash ? { expect: { content_hash: preHash } } : {}) };
+        return runOps(cli, ws, repo, [op], values.actor ? { actor: values.actor } : {});
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export const cmdEdit = { name: "edit", summary: "Edit a block in $EDITOR (CAS pinned)", run: (c, a) => runEdit(c, a) };
+//# sourceMappingURL=edit.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdFind: Command;

package/dist/src/cmd/find.js

@@ -0,0 +1,98 @@
+import { parseArgs } from "node:util";
+import { resolve as resolveThing } from "@omgbase/core";
+import { CliUsageError, EXIT_OK, 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,
+// evidence}. `-1` prints the top hit's id alone (pipe fuel: omg cat $(omg find … -1)).
+async function runFind(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            n: { type: "string", short: "n" },
+            one: { type: "boolean", short: "1" },
+            verbose: { type: "boolean", short: "v" },
+            "no-semantic": { type: "boolean" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "find",
+            summary: "Resolve a name/title/concept to ranked hits — full-text, fused with the embedding index when a provider is configured",
+            usage: "find <text> [-n <N>] [-1] [-v] [--no-semantic]",
+            options: [
+                ["-n <N>", "max hits (default 10)"],
+                ["-1", `print only the top hit's id (\`${cli.prog} cat $(${cli.prog} find "risks" -1)\`)`],
+                ["-v, --verbose", "print per-hit evidence"],
+                ["--no-semantic", "full-text only; skip the embedding provider even if one is configured"],
+            ],
+        });
+    }
+    const text = positionals.join(" ").trim();
+    if (!text)
+        throw new CliUsageError("find requires <text>");
+    const limit = values.one ? 1 : values.n ? Number(values.n) : 10;
+    let hits;
+    if (cli.flags.server) {
+        // Remote: the `resolve` tool does the hybrid ranking server-side (using the
+        // server's embedder if configured). Same ranked-hit shape → render unchanged.
+        hits = await remoteCall(cli, "resolve", { query: text, limit });
+    }
+    else {
+        const ws = cli.workspace();
+        const repo = cli.repo(ws);
+        // Hybrid by default: if a provider is configured, fuse the query vector into
+        // the ranking (--no-semantic forces FTS-only). resolve() blends when a vector
+        // is supplied.
+        const input = { repoId: repo.repoId, query: text, limit };
+        if (!values["no-semantic"]) {
+            const loaded = await loadEmbedding(ws, repo.repoId);
+            if (loaded) {
+                try {
+                    const vec = await loaded.worker.embedQuery(text);
+                    input.vector = { model: loaded.provider.model, vec };
+                }
+                finally {
+                    await loaded.close();
+                }
+            }
+        }
+        hits = resolveThing(ws.store, input);
+    }
+    cli.capture?.(hits); // shell: the ranked hits become the addressable frame
+    // -1: bare top id.
+    if (values.one) {
+        if (hits[0])
+            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;
+    }
+    const { style, io } = cli;
+    if (hits.length === 0) {
+        io.err(style.dim("  no matches"));
+        return EXIT_OK;
+    }
+    for (const h of hits) {
+        io.out(`${style.id(h.id)}  ${style.accent(h.locator)}  ${h.preview}`);
+        if (values.verbose)
+            io.err(style.dim(`    ${JSON.stringify(h.evidence)}`));
+    }
+    return EXIT_OK;
+}
+export const cmdFind = { name: "find", summary: "Ranked hybrid search for the id of a thing", run: (cli, a) => runFind(cli, a) };
+//# sourceMappingURL=find.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdHelp: Command;

package/dist/src/cmd/help.js

@@ -0,0 +1,47 @@
+import { EXIT_OK } from "../output.js";
+// `omg help` / bare invocation / --help. Renders the branded header + the
+// command catalog grouped by area. The catalog is data (11 §8); help reads it
+// from the registry lazily to avoid an import cycle.
+const GROUPS = [
+    { title: "bootstrap", names: ["init", "source", "repos"] },
+    { title: "orient & read", names: ["status", "ls", "outline", "cat", "show", "find"] },
+    { title: "query", names: ["query", "run"] },
+    { title: "history & links", names: ["log", "hist", "diff", "links"] },
+    { title: "mutate", names: ["apply", "insert", "update", "edit", "move", "rm", "done", "append", "retarget", "split", "merge", "node"] },
+    { title: "documents", names: ["new", "mv", "meta"] },
+    { title: "session", names: ["shell"] },
+    { title: "sync & serve", names: ["sync", "mcp"] },
+    { title: "admin", names: ["rebuild-index", "gc", "doctor", "config", "embed"] },
+];
+async function runHelp(cli) {
+    const { render, style, io, prog } = cli;
+    const { COMMANDS } = await import("../commands.js");
+    const byName = new Map(COMMANDS.map((c) => [c.name, c]));
+    io.out(render.wordmark("Open Markdown Graph Base"));
+    io.out(render.rule(40));
+    io.out("");
+    io.out(`  ${style.dim("usage:")} ${prog} ${style.dim("[--json|--jsonl|--ids] [-C dir] [--repo slug]")} <command> ${style.dim("[args]")}`);
+    io.out("");
+    for (const group of GROUPS) {
+        io.out(`  ${style.bold(group.title)}`);
+        const rows = group.names
+            .map((n) => byName.get(n))
+            .filter((c) => Boolean(c))
+            .map((c) => {
+            const names = [c.name, ...(c.aliases ?? [])].join(", ");
+            return `    ${style.accent(names.padEnd(22))}${style.dim(c.summary)}`;
+        });
+        for (const r of rows)
+            io.out(r);
+        io.out("");
+    }
+    io.out(`  ${style.dim("run")} ${prog} <command> --help ${style.dim("for details")}`);
+    return EXIT_OK;
+}
+export const cmdHelp = {
+    name: "help",
+    summary: "Show this help",
+    listed: false,
+    run: (cli) => runHelp(cli),
+};
+//# sourceMappingURL=help.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdHist: Command;

package/dist/src/cmd/hist.js

@@ -0,0 +1,58 @@
+import { parseArgs } from "node:util";
+import { resolveRef, historyNode } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, 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) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { n: { type: "string", short: "n" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "hist",
+            summary: "A block's change biography: every commit that touched it",
+            usage: "hist <node> [-n <N>]",
+            options: [["-n <N>", "max changes"]],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("hist requires a <node>");
+    let changes;
+    if (cli.flags.server) {
+        // Remote: history_node keys on a block id (globally unique). Pass the ref
+        // through — a locator would need a local resolve, so remote hist wants an id.
+        changes = await remoteCall(cli, "history_node", { id: ref, ...(values.n ? { limit: Number(values.n) } : {}) });
+    }
+    else {
+        const ws = cli.workspace();
+        const repo = cli.repo(ws);
+        const resolved = resolveRef(ws.store, repo.repoId, ref);
+        if (!resolved || resolved.kind !== "block")
+            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;
+    }
+    const { style, io } = cli;
+    if (changes.length === 0) {
+        io.err(style.dim("  no history"));
+        return EXIT_OK;
+    }
+    for (const c of changes) {
+        const conf = c.confidence != null ? style.dim(` (${c.confidence.toFixed(2)})`) : "";
+        io.out(`${style.dim(`#${c.seq}`)} ${style.accent(c.kind)}${conf} ${style.dim(c.origin)} ${style.dim(c.ts)}`);
+    }
+    return EXIT_OK;
+}
+export const cmdHist = { name: "hist", summary: "A block's change biography", run: (cli, a) => runHist(cli, a) };
+//# sourceMappingURL=hist.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdLinks: Command;

package/dist/src/cmd/links.js

@@ -0,0 +1,76 @@
+import { parseArgs } from "node:util";
+import { resolveRef, docLinks } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, 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.
+function runLinks(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            in: { type: "boolean" },
+            out: { type: "boolean" },
+            pred: { type: "string" },
+            blocks: { type: "boolean" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "links",
+            summary: "Open edges touching a node, grouped by predicate (both directions by default)",
+            usage: "links <node> [--in|--out] [--pred <p,p>] [--blocks]",
+            options: [
+                ["--in", "incoming edges only (backlinks)"],
+                ["--out", "outgoing edges only"],
+                ["--pred <p,p>", "keep only these predicates"],
+                ["--blocks", "block-grain edges (default: doc-grain)"],
+            ],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("links requires a <node>");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const resolved = resolveRef(ws.store, repo.repoId, ref);
+    if (!resolved)
+        throw new EngineErrorLike("doc_missing", `no node ${ref}`);
+    const direction = values.in && !values.out ? "in" : values.out && !values.in ? "out" : "both";
+    const opts = { direction };
+    if (values.pred)
+        opts.predicates = values.pred.split(",").map((s) => s.trim());
+    if (values.blocks)
+        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;
+    }
+    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;
+    }
+    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}`)}`);
+    }
+    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}`)}`);
+    }
+    return EXIT_OK;
+}
+export const cmdLinks = { name: "links", summary: "Open edges touching a node", run: (cli, a) => runLinks(cli, a) };
+//# sourceMappingURL=links.js.map

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdLog: Command;