omgbase 0.1.0

package/dist/src/cmd/mutate.js

@@ -0,0 +1,352 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { resolveRef, tasksComplete, sectionsAppend, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, renderHelp } from "../output.js";
+import { runOps, runOpsRemote, readContent, readStdin, expandBlockArgs, extractContentOpts } from "./_mutate.js";
+import { runRmDoc } from "./docs.js";
+// Write sugar (11 §5.6): each command builds kernel Ops and applies them as one
+// changeset via the shared runOps helper (writer flock, actor default, dry-run,
+// conflict rendering). `apply` is the primitive; the rest are sugar.
+function block(cli, ws, repoId, ref) {
+    const r = resolveRef(ws.store, repoId, ref);
+    if (!r || r.kind !== "block")
+        throw new EngineErrorLike("block_missing", `not a block: ${ref}`);
+    return r.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")
+        .get(blockId);
+    return row?.h ?? null;
+}
+// Parse an `--at` spec: end|start|before X|after X (default end).
+function parseAt(values) {
+    const at = values.at?.trim();
+    if (!at || at === "end")
+        return "end";
+    if (at === "start")
+        return "start";
+    const m = /^(before|after)\s+(.+)$/.exec(at);
+    if (m)
+        return m[1] === "before" ? { before: m[2] } : { after: m[2] };
+    throw new CliUsageError(`bad --at '${at}' (use end|start|before <id>|after <id>)`);
+}
+// ---- apply (primitive) ------------------------------------------------------
+async function runApply(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { f: { type: "string", short: "f" }, reason: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "apply",
+            summary: "Apply a raw changeset (`{ ops: [...] }`, the six-op kernel) — the primitive every other mutator expands to",
+            usage: "apply [-f <changeset.json|->] [--reason <s>] [--actor <s>] [--dry-run]",
+            options: [
+                ["-f <file|->", "changeset JSON from a file or stdin (default: stdin)"],
+                ["--reason <s>", "commit reason recorded in history"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+                ["--dry-run", "validate + render the diff, commit nothing"],
+            ],
+        });
+    }
+    const raw = values.f ? (values.f === "-" ? readStdin() : readFileSync(values.f, "utf8")) : readStdin();
+    const parsed = JSON.parse(raw);
+    if (!parsed.ops || !Array.isArray(parsed.ops))
+        throw new CliUsageError("changeset must have an `ops` array");
+    if (cli.flags.server)
+        return runOpsRemote(cli, "apply", { ops: parsed.ops, ...(values.reason ? { reason: values.reason } : {}) });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    return runOps(cli, ws, repo, parsed.ops, { ...(values.reason ? { reason: values.reason } : {}), ...(values.actor ? { actor: values.actor } : {}) });
+}
+// ---- insert -----------------------------------------------------------------
+async function runInsert(cli, args) {
+    const content = extractContentOpts(args);
+    const { values, positionals } = parseArgs({
+        args: content.rest,
+        allowPositionals: true,
+        options: { at: { 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]",
+            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>"],
+                ["--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)");
+    const markdown = readContent(content);
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_insert", { to, markdown, at: parseAt(values) });
+    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 };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+// ---- update -----------------------------------------------------------------
+async function runUpdate(cli, args) {
+    const content = extractContentOpts(args);
+    const { values, positionals } = parseArgs({
+        args: content.rest,
+        allowPositionals: true,
+        options: { expect: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "update",
+            summary: "Replace a block's markdown, with compare-and-swap against the block's current hash",
+            usage: "update <block> (-m <markdown> | -f <file> | -) [--expect <hash>] [--actor <s>] [--dry-run]",
+            options: [
+                ["-m <markdown>", "content inline"],
+                ["-f <file>", "content from a file"],
+                ["-", "content from stdin"],
+                ["--expect <hash>", "fail with stale_expectation unless the block's hash still matches"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("update requires a <block>");
+    const markdown = readContent(content);
+    // Remote: the server pins CAS from current bytes when --expect is absent.
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_update", { block: ref, markdown, ...(values.expect ? { expect: { content_hash: values.expect } } : {}) });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const blockId = block(cli, ws, repo.repoId, ref);
+    // CAS (§5.7): scripted callers pass --expect; interactive callers omit it and
+    // we pin the just-read hash (protects against concurrent edits, not against
+    // edits since a read the caller never made).
+    const expect = values.expect ?? rawHashOf(ws, blockId);
+    if (!values.expect) {
+        cli.io.err(cli.style.dim(`  updating ${ref} (CAS pinned from current bytes)`));
+    }
+    const op = { op: "update", block: blockId, markdown, ...(expect ? { expect: { content_hash: expect } } : {}) };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+// ---- move -------------------------------------------------------------------
+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" } },
+    });
+    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]",
+            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>"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    if (!values.to)
+        throw new CliUsageError("move requires --to <parent>");
+    const refs = expandBlockArgs(positionals);
+    if (refs.length === 0)
+        throw new CliUsageError("move requires one or more blocks (or - for stdin)");
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_move", { blocks: refs, to: values.to, at: parseAt(values) });
+    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) } };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+// ---- rm (blocks; --doc handled by the doc-level command) --------------------
+async function runRm(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { doc: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "rm",
+            summary: "Remove block(s) (the resurrection pool catches regret), or delete a whole document with --doc",
+            usage: ["rm <blocks…|-> [--actor <s>] [--dry-run]", "rm --doc <doc> [--actor <s>] [--dry-run]"],
+            options: [
+                ["<blocks…>", "block ids; `-` reads them from stdin, one per line"],
+                ["--doc <doc>", "delete a whole document (id or path) — always explicit"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    if (values.doc !== undefined) {
+        // Doc deletion always requires the explicit --doc (11 §5.6).
+        return runRmDoc(cli, values.doc, values.actor);
+    }
+    const refs = expandBlockArgs(positionals);
+    if (refs.length === 0)
+        throw new CliUsageError("rm requires one or more blocks (or - for stdin), or --doc");
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_remove", { blocks: refs });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
+    const op = { op: "remove", blocks };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+// ---- done (tasks_complete) --------------------------------------------------
+async function runDone(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { undo: { type: "boolean" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "done",
+            summary: "Check (or uncheck) task blocks",
+            usage: "done <blocks…|-> [--undo] [--actor <s>] [--dry-run]",
+            options: [
+                ["<blocks…>", `task block ids; \`-\` reads them from stdin (\`${cli.prog} q … --ids | ${cli.prog} done -\`)`],
+                ["--undo", "uncheck instead"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const refs = expandBlockArgs(positionals);
+    if (refs.length === 0)
+        throw new CliUsageError("done requires one or more task blocks (or - for stdin)");
+    if (cli.flags.server)
+        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 ops = values.undo
+        ? blocks.map((b) => ({ op: "update", block: b, attrs: { checked: false }, expect: pinned(ws, b) }))
+        : tasksComplete(ws.store, blocks);
+    return runOps(cli, ws, repo, ops, actorOf(values));
+}
+// ---- append (sections_append) -----------------------------------------------
+async function runAppend(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: "append",
+            summary: "Append markdown at the end of a heading's section",
+            usage: "append <heading> (-m <markdown> | -f <file> | -) [--actor <s>] [--dry-run]",
+            options: [
+                ["<heading>", "the heading block (id or locator) whose section receives the content"],
+                ["-m <markdown>", "content inline"],
+                ["-f <file>", "content from a file"],
+                ["-", "content from stdin"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const heading = positionals[0];
+    if (!heading)
+        throw new CliUsageError("append requires a <heading> block");
+    const markdown = readContent(content);
+    // Remote: sections_append resolves the heading ref (id OR text) server-side.
+    if (cli.flags.server)
+        return runOpsRemote(cli, "sections_append", { heading, markdown });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const headingId = block(cli, ws, repo.repoId, heading);
+    return runOps(cli, ws, repo, sectionsAppend(headingId, markdown), actorOf(values));
+}
+// ---- split / merge ----------------------------------------------------------
+async function runSplit(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { at: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "split",
+            summary: "Split a block at character offset(s) into sibling blocks",
+            usage: "split <block> --at <n[,n…]> [--actor <s>] [--dry-run]",
+            options: [
+                ["--at <n[,n…]>", "character offset(s) within the block's markdown"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const ref = positionals[0];
+    if (!ref)
+        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()));
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_split", { block: ref, at });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const blockId = block(cli, ws, repo.repoId, ref);
+    const op = { op: "split", block: blockId, at, expect: { content_hash: rawHashOf(ws, blockId) ?? "" } };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+async function runMerge(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { sep: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "merge",
+            summary: "Merge adjacent blocks into the first (the first block's identity survives)",
+            usage: "merge <blocks…|-> [--sep <s>] [--actor <s>] [--dry-run]",
+            options: [
+                ["<blocks…>", "two or more adjacent block ids; `-` reads them from stdin"],
+                ["--sep <s>", "separator placed between the merged texts"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const refs = expandBlockArgs(positionals);
+    if (refs.length < 2)
+        throw new CliUsageError("merge requires at least two blocks");
+    if (cli.flags.server)
+        return runOpsRemote(cli, "blocks_merge", { blocks: refs, ...(values.sep !== undefined ? { separator: values.sep } : {}) });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
+    const op = { op: "merge", blocks, ...(values.sep !== undefined ? { separator: values.sep } : {}) };
+    return runOps(cli, ws, repo, [op], actorOf(values));
+}
+// helpers ---------------------------------------------------------------------
+function pinned(ws, blockId) {
+    return { content_hash: rawHashOf(ws, blockId) ?? "" };
+}
+function actorOf(values) {
+    return values.actor ? { actor: values.actor } : {};
+}
+export const cmdApply = { name: "apply", summary: "Apply a raw changeset (the primitive)", run: (c, a) => runApply(c, a) };
+export const cmdInsert = { name: "insert", summary: "Insert blocks under a parent", run: (c, a) => runInsert(c, a) };
+export const cmdUpdate = { name: "update", summary: "Replace a block's markdown (CAS)", run: (c, a) => runUpdate(c, a) };
+export const cmdMove = { name: "move", summary: "Move blocks under a new parent", run: (c, a) => runMove(c, a) };
+export const cmdRm = { name: "rm", summary: "Remove blocks (or --doc a document)", run: (c, a) => runRm(c, a) };
+export const cmdDone = { name: "done", summary: "Check/uncheck task blocks", run: (c, a) => runDone(c, a) };
+export const cmdAppend = { name: "append", summary: "Append into a heading's section", run: (c, a) => runAppend(c, a) };
+export const cmdSplit = { name: "split", summary: "Split a block at offsets", run: (c, a) => runSplit(c, a) };
+export const cmdMerge = { name: "merge", summary: "Merge adjacent blocks", run: (c, a) => runMerge(c, a) };
+//# sourceMappingURL=mutate.js.map

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

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

package/dist/src/cmd/node.js

@@ -0,0 +1,66 @@
+import { parseArgs } from "node:util";
+import { nodeSet, editablePropsFor } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { runOps, runOpsRemote } from "./_mutate.js";
+// `omg node set <nodeId> <prop> <value>` (node-editability) — surgically set an
+// editable property of a projected node (e.g. a link's text/target, a task's
+// checked). Resolves node → block via the adapter's registered editor and
+// applies one update op. `omg node props <nodeId>` reports what's editable.
+function nodeKindFormat(cli, nodeId) {
+    const ws = cli.workspace();
+    const row = ws.store.db.prepare("SELECT n.kind AS kind, d.format AS format FROM nodes n JOIN docs d ON d.doc_id = n.doc_id WHERE n.node_id = ?").get(nodeId);
+    if (!row)
+        throw new EngineErrorLike("block_missing", `no node ${nodeId}`);
+    return row;
+}
+async function runNode(cli, args) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || sub === "help" || args.includes("--help")) {
+        return renderHelp(cli, {
+            name: "node",
+            summary: "Edit a projected node's editable properties surgically (a link's target, a task's checked, …)",
+            usage: ["node set <nodeId> <prop> <value> [--actor <s>] [--dry-run]", "node props <nodeId>"],
+            options: [
+                ["set", "rewrite one property; the adapter maps it back onto the source block"],
+                ["props", "list which properties of this node's kind are editable"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    if (sub === "set") {
+        parseArgs({ args: rest, allowPositionals: true, options: { actor: { type: "string" } } });
+        const [nodeId, prop, ...valueParts] = rest.filter((a) => !a.startsWith("--"));
+        if (!nodeId || !prop || valueParts.length === 0)
+            throw new CliUsageError("node set <nodeId> <prop> <value>");
+        const value = valueParts.join(" ");
+        // Remote: node_set resolves node → block + rewrites the span server-side.
+        if (cli.flags.server)
+            return runOpsRemote(cli, "node_set", { node: nodeId, prop, value });
+        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}` });
+    }
+    if (sub === "props") {
+        // `props` is a local editability lookup with no remote tool (a niche read).
+        if (cli.flags.server)
+            throw new CliUsageError("node props is local-only; run it against a local workspace");
+        const nodeId = rest[0];
+        if (!nodeId)
+            throw new CliUsageError("node props <nodeId>");
+        const { kind, format } = nodeKindFormat(cli, nodeId);
+        const props = editablePropsFor(format, kind);
+        if (cli.flags.mode !== "human") {
+            cli.io.out(JSON.stringify({ node: nodeId, kind, editable: props }));
+            return EXIT_OK;
+        }
+        if (props.length === 0)
+            cli.io.err(cli.style.dim(`  ${kind} has no editable properties`));
+        else
+            cli.io.out(`  ${cli.style.accent(kind)} ${cli.style.dim("editable:")} ${props.join(", ")}`);
+        return EXIT_OK;
+    }
+    throw new CliUsageError(`unknown node subcommand '${sub}' (set|props)`);
+}
+export const cmdNode = { name: "node", summary: "Edit a node's editable properties (surgical)", run: (c, a) => runNode(c, a) };
+//# sourceMappingURL=node.js.map

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

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

package/dist/src/cmd/oqx.js

@@ -0,0 +1,193 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
+import { truncationFooter, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { loadEmbedding } from "./_embed.js";
+import { remoteCall } from "./_remote.js";
+import { readStdin } from "./_mutate.js";
+// `omg query <source>` — OQX composable query. Dot navigation belongs to the host
+// object model (`doc.layer`, `section.blocks`); whitespace query directives
+// belong to OQX (`<receiver> collect|exists|count|first|single { <block> }`).
+// `from E` selects + flattens a relation relative to the current source scope
+// (top-level `from docs` = the repository's docs; `$repo.docs collect { from
+// nodes … }` re-projects each doc through its nodes). Inside a block the
+// `where`/`select` keyword may be omitted: a leading predicate-shaped expression
+// is an implicit `where` (`nodes exists { kind == "md:task" }`), a bare
+// reference / `name: value` list is an implicit `select` (`nodes collect
+// { attrs.text }`); a bare boolean property still projects (filter with
+// `where active` or `active == true`). Features: a boolean where
+// tree over scalar predicates and consumer directives, count comparisons
+// (`nodes count { … } >= 2`), nestable collect, one-scope lifts (^name:) that
+// filter + capture, one-scope-outward references (^name) that correlate a nested
+// query to a parent binding, explicit root relations $repo.docs/nodes/blocks for
+// join-equivalents, first/single lookups, full-text text(...) + embedding-score
+// semantic(...) predicates, `order by <expr> [asc|desc]` ranking, and recursive
+// `follow [distinct] <rel> [{ where … frontier … depth n by … }]` traversal over
+// a type-preserving relation with $depth/$stop/$ordinal recursion metadata +
+// post-walk filtering. A top-level consumer directive changes the result shape:
+// `$repo.docs count { … }` / `$repo.docs exists { … }` reduce to a scalar,
+// `$repo.docs first { … }` / `$repo.docs single { … }` to zero-or-one row (bare
+// `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
+// string or -f file|-. Human output: one hit per line (id + path), or the scalar
+// for count/exists; --json/--jsonl/--ids.
+async function runOqx(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            n: { type: "string", short: "n" },
+            cursor: { type: "string" },
+            file: { type: "string", short: "f" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        renderHelp(cli, {
+            name: "query",
+            summary: "Composable OQX query: from <docs|blocks|nodes|edges> where … select … [order by …] [follow …] (alias: q)",
+            usage: ["query <source> [-n <N>] [--cursor <c>] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>]"],
+            options: [
+                ["<source>", "the OQX query text (quote it); `from` may be omitted inside blocks"],
+                ["-f <file|->", "read the query from a file, or stdin with `-`"],
+                ["-n <N>", "page size"],
+                ["--cursor <c>", "continue a truncated result"],
+                ["--ids", `bare ids, one per line — pipe fuel (\`… --ids | ${cli.prog} cat -\`)`],
+            ],
+            notes: [
+                `semantic ranking: \`order by semantic("phrase") desc\` or \`where semantic("phrase") > 0.6\` (needs embedding.provider; see \`${cli.prog} embed --help\`).`,
+                "full syntax: the examples below, the MCP `query_syntax` tool, and docs/query-language.md.",
+                "examples:",
+            ],
+        });
+        cli.io.out("  e.g. query 'from docs where nodes count { where kind == \"md:task\" } >= 2'");
+        cli.io.out("       query 'from nodes where kind == \"md:section\" select items: section.blocks collect { where type == \"list_item\" }'");
+        cli.io.out("       query 'from docs where nodes collect { ^open: value where kind == \"md:task\" && !attrs.checked } select $path, open'");
+        cli.io.out("       query 'from docs select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }'");
+        cli.io.out("       query '$repo.docs count { where layer == \"canon\" }'   # scalar; also $repo.<target> exists/none/first/single { … }");
+        cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" && !checked }'   # none = zero rows (≡ !exists; \"every\" = none over the complement)");
+        cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc limit 2 offset 1'   # limit/offset bound the set (after order/distinct, before the consumer)");
+        cli.io.out("       query 'from docs where $path == \"x.md\" select fm: entries(frontmatter) collect { k: $key, v: $value }'   # a record as a collection ($key/$value); also entries(attrs), entries(inline)");
+        cli.io.out("       query 'from docs where layer == \"canon\" select $path values'   # `values`: bare values, no {id,path} hits (one item only)");
+        cli.io.out("       query 'from docs select $path, tags: tags collect { $value values where $value != \"draft\" }'   # $value = the current item (here: each tag)");
+        cli.io.out("       query '$repo.docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
+        cli.io.out("       query 'from docs where text(\"philosophers stone\") && layer == \"canon\"'   # full-text prune");
+        cli.io.out("       query 'from blocks where semantic(\"the great work\") > 0.6 select s: semantic(\"the great work\")'  # embedding score (needs a provider)");
+        cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc'   # order by <expr> [asc|desc]");
+        cli.io.out("       query 'from blocks where $id == \"b_x\" select t: text, d: $depth, s: $stop follow block.children'   # recursive walk ($depth/$stop metadata)");
+        cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <rel> [{ where … frontier … depth n by … }]");
+        cli.io.out("       query 'from docs where $path == \"index.md\" select p: $path, d: $depth, s: $stop follow doc.out'   # citation graph (cyclic-safe: $stop=cycle)");
+        cli.io.out("       query 'from blocks where type == \"list_item\" && $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
+        cli.io.out("       query 'from edges where predicate == \"depends_on\" select src: $src, to: $dst_path'   # the edges target: predicate/provenance/dst_kind + $src/$dst_path/$dst_uri");
+        cli.io.out("       query 'from docs where $path == \"a.md\" follow doc.out { via predicate == \"cites\" }'   # predicate-filtered traversal (via = the licensing edge)");
+        return EXIT_OK;
+    }
+    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;
+    }
+    const opts = {};
+    if (values.n)
+        opts.limit = Number(values.n);
+    if (values.cursor)
+        opts.cursor = values.cursor;
+    let result;
+    if (cli.flags.server) {
+        // Remote: the `query` MCP tool returns the same OqxResult; render unchanged.
+        result = await remoteCall(cli, "query", {
+            query: source,
+            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+            ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+        });
+    }
+    else {
+        const ws = cli.workspace();
+        const repo = cli.repo(ws);
+        // A query using semantic("…") needs the embedding provider to turn each
+        // phrase into a query vector; everything else runs on the sync core with no
+        // provider loaded. loadEmbedding is only touched when a phrase is present.
+        const phrases = collectSemanticPhrases(source);
+        if (phrases.length > 0) {
+            const loaded = await loadEmbedding(ws, repo.repoId);
+            if (!loaded) {
+                throw new EngineErrorLike("semantic_unavailable", "semantic(...) needs an embedding provider", {
+                    hint: "omg config set embedding.provider <command|url>",
+                });
+            }
+            try {
+                const embed = async (t) => ({ model: loaded.provider.model, vec: await loaded.worker.embedQuery(t) });
+                result = await oqxRunAsync(ws.store, repo.repoId, source, opts, embed);
+            }
+            finally {
+                await loaded.close();
+            }
+        }
+        else {
+            result = oqxRun(ws.store, repo.repoId, source, opts);
+        }
+    }
+    // Shell capture (typed result before formatting): a scalar for count/exists,
+    // else the whole result (its .hits become the addressable frame).
+    cli.capture?.(result.consumer === "count" ? result.count
+        : 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;
+    }
+    // Scalar consumers (count/exists/none) have no hits — render the reduction itself.
+    if (result.consumer === "count" || result.consumer === "exists" || result.consumer === "none") {
+        const scalar = result.consumer === "count" ? String(result.count) : result.consumer === "exists" ? String(result.exists) : String(result.none);
+        cli.io.out(scalar);
+        return EXIT_OK;
+    }
+    // A `values` projection has no hits — one bare value per line (strings
+    // verbatim, anything else as JSON; `--jsonl` is JSON throughout).
+    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 ?? "");
+        return EXIT_OK;
+    }
+    const { style, io } = cli;
+    if (result.hits.length === 0) {
+        io.err(style.dim("  no hits"));
+        return EXIT_OK;
+    }
+    for (const h of result.hits) {
+        io.out(`${style.id(h.id)}  ${style.accent(h.path)}`.trimEnd());
+    }
+    if (result.truncated)
+        truncationFooter(io, style, result.cursor ?? "");
+    return EXIT_OK;
+}
+// `query` (alias `q`) is the single, default query surface — the OQX engine.
+// (The `oqx` alias was removed: OQX *is* the query experience, so `query`/`q`
+// name it. The impl lives in this file, still named oqx.ts after the engine.)
+export const cmdOqx = {
+    name: "query",
+    aliases: ["q"],
+    summary: "Composable query (OQX: from/where/select + collection ops)",
+    run: (cli, a) => runOqx(cli, a),
+};
+//# sourceMappingURL=oqx.js.map

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

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