omgbase 0.4.0 → 0.5.0

package/dist/src/cmd/source.js

@@ -6,7 +6,7 @@ import { createSource, deleteSource, listSources, getSourceByName, attachSourceT
 import { columns } from "../render.js";
 import { drainEmbeddings } from "./_embed.js";
 import { ensureFsAdapter, FS_ADAPTER } from "./_source.js";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // `omg source` (ADR-014) — the source registry: where a repo's bytes come from
 // (a filesystem directory today; git/S3/etc. via adapters later). A repo owns
 // identity + history; adding a filesystem source points it at a directory and
@@ -101,14 +101,16 @@ async function runAdd(cli, args) {
     if (getSourceByName(ws.store, sourceName))
         throw new EngineErrorLike("path_taken", `a source named '${sourceName}' already exists`);
     // Consent gate: -y proceeds; a TTY prompts with a live file count; a non-TTY
-    // without -y refuses rather than absorbing the tree silently.
+    // without -y is a usage error (the script forgot the flag; exit 2) rather
+    // than a silent absorption of the tree — or a silent success.
     if (!values.yes) {
+        if (!process.stdin.isTTY || !cli.io.stdoutTTY) {
+            throw new CliUsageError(`refusing without -y (would ingest files under ${shortenHome(abs)})`, "there is no TTY to confirm on; pass -y to consent to the ingest");
+        }
         const { ok } = await confirmIngestWithCount(cli, abs, slug);
-        if (cli.io.stdoutTTY)
-            process.stderr.write("\n");
+        process.stderr.write("\n");
         if (!ok) {
-            const why = !process.stdin.isTTY || !cli.io.stdoutTTY ? `refusing without -y (would ingest files under ${shortenHome(abs)})` : "cancelled";
-            cli.io.err(cli.style.dim(`  ${why}`));
+            cli.io.err(cli.style.dim("  cancelled"));
             return EXIT_OK;
         }
     }
@@ -133,10 +135,8 @@ async function runAdd(cli, args) {
             return confirmTTY(cli, `embed ${pending} block(s) now via ${where}?`);
         },
     });
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ repo: slug, repoId, source: sourceName, root: abs, ingested: swept.ingested.length, ...(drained ? { embedded: drained.embedded } : {}) }));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { repo: slug, repoId, source: sourceName, root: abs, ingested: swept.ingested.length, ...(drained ? { embedded: drained.embedded } : {}) });
     const { render, style, io } = cli;
     io.out(`  ${render.g.diamond} ${style.accent(slug)} ← ${style.path(shortenHome(abs))}  ${style.dim(`${swept.ingested.length} files`)}`);
     if (drained)
@@ -146,23 +146,13 @@ async function runAdd(cli, args) {
 function runList(cli) {
     const ws = cli.workspace();
     const sources = listSources(ws.store).map((s) => ({ ...s, repos: attachedRepoSlugs(cli, ws, s.sourceId) }));
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(sources.map((s) => ({ name: s.name, adapter: s.adapter, config: s.config, repos: s.repos }))));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "jsonl") {
-        for (const s of sources)
-            cli.io.out(JSON.stringify({ name: s.name, adapter: s.adapter, config: s.config, repos: s.repos }));
-        return EXIT_OK;
-    }
-    if (cli.flags.mode === "ids") {
-        for (const s of sources)
-            cli.io.out(s.name);
-        return EXIT_OK;
+    if (cli.flags.mode !== "human") {
+        const rows = sources.map((s) => ({ name: s.name, adapter: s.adapter, config: s.config, repos: s.repos }));
+        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r.name) });
     }
     const { style, io } = cli;
     if (sources.length === 0) {
-        io.out(style.dim("  no sources registered"));
+        io.err(style.dim("  no sources registered"));
         return EXIT_OK;
     }
     const rows = sources.map((s) => [
@@ -189,10 +179,8 @@ function runAttachDetach(cli, args, verb) {
         attachSourceToRepo(ws.store, repo.repoId, source.sourceId);
     else
         detachSourceFromRepo(ws.store, repo.repoId, source.sourceId);
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ source: name, repo: repo.slug, attached: verb === "attach" }));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { source: name, repo: repo.slug, attached: verb === "attach" });
     cli.io.out(`  ${cli.render.g.ok} ${verb === "attach" ? "attached" : "detached"} ${cli.style.accent(name)} ${verb === "attach" ? "→" : "⇸"} ${cli.style.accent(repo.slug)}`);
     return EXIT_OK;
 }
@@ -206,10 +194,8 @@ function runRm(cli, args) {
     if (!source)
         throw new EngineErrorLike("target_missing", `no source named '${name}'`);
     deleteSource(ws.store, source.sourceId);
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ source: name, deleted: true }));
-        return EXIT_OK;
-    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { source: name, deleted: true });
     cli.io.out(`  ${cli.render.g.ok} deleted source ${cli.style.accent(name)}`);
     return EXIT_OK;
 }

package/dist/src/cmd/status.js

@@ -1,8 +1,10 @@
 import { parseArgs } from "node:util";
-import { reposStatus, syncStatus, watchLeaseLive } from "@omgbase/core";
-import { EXIT_OK, renderHelp } from "../output.js";
+import { reposStatus, syncStatus, watchLeaseLive, staleEmbedCount, resolveSettings, embeddingSettings } from "@omgbase/core";
+import { EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // `omg status` (11 §5.2): repos_status + sync_status + watch-lease probe +
-// embedding queue depth. The "where am I" command — the visual showcase.
+// embedding queue depth. The "where am I" command — the visual showcase. The
+// machine shape is the two tools' results, nested as they are on the wire
+// (spec/cli §6): `{ ...repos_status, sync: sync_status, watcher, embedQueue }`.
 function runStatus(cli, args) {
     const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
     if (values.help) {
@@ -10,7 +12,7 @@ function runStatus(cli, args) {
             name: "status",
             summary: "Where am I: the active repo, doc/block/commit counts, sync convergence, watcher, embed queue",
             usage: "status [--repo <slug>] [--json]",
-            options: [["--json", "a flat object: repo, root, docs, blocks, commits, openEdges, convergent, disk, watcher, embedQueue"]],
+            options: [["--json", "the repos_status result, plus `sync` (the sync_status result), `watcher` (live|none) and `embedQueue` (stale embeddable blocks)"]],
         });
     }
     const ws = cli.workspace();
@@ -18,27 +20,13 @@ function runStatus(cli, args) {
     const rs = reposStatus(ws.store, repo.repoId, repo.rootPath ?? undefined);
     const ss = syncStatus(ws.store, repo.repoId, repo.rootPath ?? undefined);
     const watcher = watchLeaseLive(ws.omgbaseDir);
-    // Embedding queue depth: count blocks whose embeddings are missing is a v1
-    // approximation; the queue table isn't wired yet, so report 0 (05 §6 stub).
-    const queued = 0;
-    const payload = {
-        repo: repo.slug,
-        root: repo.rootPath,
-        docs: rs.docs,
-        blocks: rs.blocks,
-        commits: rs.commits,
-        openEdges: rs.openEdges,
-        unconverged: rs.unconverged,
-        convergent: ss.convergent,
-        disk: ss.disk,
-        lastCommitSeq: ss.lastCommitSeq,
-        watcher: watcher ? "live" : "none",
-        embedQueue: queued,
-    };
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(payload));
-        return EXIT_OK;
-    }
+    // Embedding queue depth (spec/search §2.3): the embeddable blocks whose
+    // current context has no cached vector — for the configured model when one is
+    // named, else for any. Counted from the cache alone: no provider is spawned.
+    const queued = staleEmbedCount(ws.store, repo.repoId, embeddingSettings(resolveSettings(ws.store, repo.repoId)).model);
+    const payload = { ...rs, sync: ss, watcher: watcher ? "live" : "none", embedQueue: queued };
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, payload);
     const { render, style, io } = cli;
     const g = render.g;
     io.out(render.wordmark(repo.slug));

package/dist/src/cmd/sync.js

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EngineError } from "@omgbase/core";
 import { runFsMirror } from "@omgbase/sync";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteSpec } from "./_remote.js";
 import { openRepoSource } from "./_source.js";
@@ -62,17 +62,16 @@ async function runSync(cli, args) {
 }
 function runOneShot(cli, ws, repo) {
     if (!repo.rootPath) {
-        if (cli.flags.mode === "human")
-            cli.io.out(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
-        else
-            cli.io.out(JSON.stringify({ scanned: 0, ingested: [], deleted: [], conflicted: [], changed: false }));
+        // Nothing to sweep: an empty-result note (stderr, §3.1), or the empty sweep shape.
+        if (cli.flags.mode !== "human")
+            return emitMachine(cli, { scanned: 0, ingested: [], deleted: [], conflicted: [], changed: false });
+        cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
         return EXIT_OK;
     }
     const result = freshnessSweep(ws.store, repo.repoId, repo.rootPath);
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
+    // A `SweepResult` is a record (its lists are per-kind): every machine mode is the document.
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result);
     const { render, style, io } = cli;
     const g = render.g;
     io.out(render.wordmark("sync"));

package/dist/src/cmd/update.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { docsUpdate, renderOpsetPlan, isValidId } from "@omgbase/core";
+import { docsUpdate, renderOpsetPlan } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
@@ -13,11 +13,13 @@ import { remoteCall } from "./_remote.js";
 // --dry-run (or --plan) prints the plan (identity effects + summary), commits
 // nothing.
 function runUpdate(cli, args) {
-    // Peek at the target to dispatch: a b_ id is a block replace; anything else
-    // (d_ id or path) is a whole-document update. The block path re-parses args.
+    // Peek at the target to dispatch: a `b_` token is a block replace — a token
+    // that names no live block fails there as block_missing (spec/cli §6), never
+    // as a document path; anything else (d_ id or path) is a whole-document
+    // update. The block path re-parses args.
     const peek = extractContentOpts(args);
     const target = peek.rest.find((a) => !a.startsWith("-"));
-    if (target && isValidId(target, "b"))
+    if (target && target.startsWith("b_"))
         return cmdUpdateBlock.run(cli, args);
     return runDocUpdate(cli, args);
 }
@@ -92,7 +94,10 @@ async function runDocUpdate(cli, args) {
     }
     const g = cli.render.g;
     cli.io.err(cli.style.dim(`  ${cli.style.ok(g.ok)} updated ${cli.style.accent(opset.target.path)} · ${opset.summary.preserved} preserved, ${opset.summary.updated} updated, ${opset.summary.moved} moved, ${opset.summary.created} created, ${opset.summary.removed} removed`));
-    for (const id of result.results.flatMap((r) => r.ids))
+    // Every id the opset touched, once each: a block appears in several ops'
+    // results (an update then a retile of the same block), the confirmation
+    // lists it a single time.
+    for (const id of new Set(result.results.flatMap((r) => r.ids)))
         cli.io.out(id);
     return EXIT_OK;
 }

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

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

package/dist/src/cmd/version.js

@@ -0,0 +1,68 @@
+import { parseArgs } from "node:util";
+import { versionInfo } from "@omgbase/core";
+import { EXIT_OK, emitMachine, renderHelp } from "../output.js";
+import { hostInfo } from "../build.js";
+import { remoteCall } from "./_remote.js";
+// `omg version` (spec/cli §6, 1.1): the surface's `version` tool, rendered.
+// Which engine and which component versions a host or a shell is talking to —
+// with `--server` it is the REMOTE engine's answer, which is exactly how you
+// tell a TypeScript `omg mcp` from a Rust `omgbase mcp`. Needs no repo; the
+// workspace is opened only for `schema` (`—` without one). `--version` (§2.5)
+// stays the one-line form.
+async function runVersion(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "version",
+            summary: "Which engine and which versions: the binary, its components, the specs it implements, the schema, MCP protocol, runtime, build",
+            usage: "version [--json]",
+            options: [["--json", "the `version` tool result verbatim"]],
+            notes: ["with --server, the remote engine's answer (typescript or rust)"],
+        });
+    }
+    let info;
+    if (cli.flags.server !== undefined) {
+        info = await remoteCall(cli, "version", {});
+    }
+    else {
+        // `schema` is the open database's user_version; without a workspace the
+        // command still answers (spec/cli §3.7: version ∈ NO_WORKSPACE_OK).
+        let store = null;
+        try {
+            store = cli.workspace().store;
+        }
+        catch {
+            store = null;
+        }
+        info = versionInfo(store, hostInfo());
+    }
+    cli.capture?.(info);
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, info);
+    const { io, style } = cli;
+    const dash = "—";
+    const keys = ["engine", "version", "specs", "schema", "mcp", "runtime", "commit", "built"];
+    const width = Math.max(...keys.map((k) => k.length));
+    const line = (key, value) => {
+        io.out(`${style.dim(key.padEnd(width))}  ${value === null ? style.dim(dash) : String(value)}`);
+    };
+    line("engine", info.engine);
+    line("version", info.version);
+    const names = Object.keys(info.components);
+    const nameWidth = Math.max(0, ...names.map((n) => n.length));
+    for (const name of names)
+        io.out(`  ${style.accent(name.padEnd(nameWidth))}  ${info.components[name]}`);
+    line("specs", Object.entries(info.specs).map(([k, v]) => `${k} ${v}`).join(" · "));
+    line("schema", info.schema);
+    line("mcp", info.mcp.sdk !== undefined ? `${info.mcp.protocol} (sdk ${info.mcp.sdk})` : info.mcp.protocol);
+    line("runtime", info.runtime);
+    line("commit", info.commit);
+    line("built", info.built);
+    return EXIT_OK;
+}
+export const cmdVersion = {
+    name: "version",
+    summary: "Which engine and which versions (binary, components, specs, schema, MCP, runtime, build)",
+    run: (cli, a) => runVersion(cli, a),
+};
+//# sourceMappingURL=version.js.map

package/dist/src/commands.js

@@ -24,6 +24,7 @@ import { cmdRebuild, cmdGc, cmdDoctor, cmdConfig, cmdEmbed } from "./cmd/admin.j
 import { cmdShell } from "./cmd/shell.js";
 import { cmdSource } from "./cmd/source.js";
 import { cmdHelp } from "./cmd/help.js";
+import { cmdVersion } from "./cmd/version.js";
 export const COMMANDS = [
     cmdInit,
     cmdRepos,
@@ -63,6 +64,7 @@ export const COMMANDS = [
     cmdDoctor,
     cmdConfig,
     cmdEmbed,
+    cmdVersion,
     cmdHelp,
 ];
 const BY_NAME = new Map();

package/dist/src/context.d.ts

@@ -68,6 +68,10 @@ export interface CliOptions {
 export declare function progName(argv1: string | undefined): string;
 export declare function makeCli(flags: GlobalFlags, io: IO, opts?: CliOptions): Cli;
 export declare const NO_WORKSPACE_OK: Set<string>;
+export declare const HELP_WORD_OK: Set<string>;
+export declare const BARE_IS_HELP: Set<string>;
+/** Does this invocation ask for a command's help card? (the flag, the word, or a bare card-only command) */
+export declare function asksForHelp(flags: GlobalFlags, name: string, args: string[]): boolean;
 export declare const SKIP_FRESHNESS: Set<string>;
 export declare const REMOTE_OK: Set<string>;
 export { CliUsageError };

package/dist/src/context.js

@@ -57,6 +57,20 @@ function resolveDir(dir) {
 }
 // Which commands may run without a workspace (11 §2.1).
 export const NO_WORKSPACE_OK = new Set(["init", "help", "version"]);
+// Commands whose first argument may be the word `help` (their card), and those
+// whose card is also their bare invocation (spec/cli §5): help is documentation,
+// not work, so these route to the card before any workspace is opened or swept —
+// exactly like the `--help` flag.
+export const HELP_WORD_OK = new Set(["config", "embed", "node", "source"]);
+export const BARE_IS_HELP = new Set(["node", "source"]);
+/** Does this invocation ask for a command's help card? (the flag, the word, or a bare card-only command) */
+export function asksForHelp(flags, name, args) {
+    if (flags.help)
+        return true;
+    if (HELP_WORD_OK.has(name) && args[0] === "help")
+        return true;
+    return BARE_IS_HELP.has(name) && args.length === 0;
+}
 // Commands that manage sync themselves — skip the freshness sweep (11 §3.3).
 // `shell` is exempt because each line it runs sweeps on its own. `source`
 // creates/binds sources and runs its own initial sync, so it skips the pre-sweep.
@@ -75,6 +89,8 @@ export const REMOTE_OK = new Set([
     "apply", "insert", "move", "split", "merge", "done", "append", "node",
     // shell accepts --server itself, then threads it into every line it runs.
     "shell",
+    // version asks the REMOTE engine which engine/versions it is (spec/cli §6).
+    "version",
 ]);
 export { CliUsageError };
 //# sourceMappingURL=context.js.map

package/dist/src/dispatch.d.ts

@@ -1,8 +1,11 @@
 import { type Cli, type GlobalFlags } from "./context.js";
+import { CliUsageError } from "./output.js";
 export interface Parsed {
     flags: GlobalFlags;
     command: string | null;
     rest: string[];
+    /** the first malformed global flag, when any (exit 2) */
+    error?: CliUsageError;
 }
 export declare function parseGlobals(argv: string[]): Parsed;
 export declare function runCommand(cli: Cli, command: string, rest: string[]): Promise<number>;

package/dist/src/dispatch.js

@@ -1,6 +1,6 @@
 import { freshnessSweep, watchLeaseLive } from "@omgbase/core";
-import { NO_WORKSPACE_OK, SKIP_FRESHNESS, REMOTE_OK } from "./context.js";
-import { CliUsageError, EngineErrorLike, renderError } from "./output.js";
+import { NO_WORKSPACE_OK, SKIP_FRESHNESS, REMOTE_OK, asksForHelp } from "./context.js";
+import { CliUsageError, EngineErrorLike, renderError, usageFromParseArgs } from "./output.js";
 import { resolveCommand, unknownCommandError } from "./commands.js";
 export function parseGlobals(argv) {
     const flags = {
@@ -14,6 +14,12 @@ export function parseGlobals(argv) {
     let command = null;
     const rest = [];
     let passthrough = false;
+    let error;
+    // Record the first malformed flag and keep parsing (a later `--json` still
+    // selects the mode the error is rendered in).
+    const fail = (message) => {
+        error ??= new CliUsageError(message);
+    };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (passthrough) {
@@ -31,30 +37,35 @@ export function parseGlobals(argv) {
             case "--directory": {
                 const dir = argv[++i];
                 if (dir === undefined)
-                    throw new CliUsageError(`${a} requires a directory`);
-                flags.directory = dir;
+                    fail(`${a} requires a directory`);
+                else
+                    flags.directory = dir;
                 continue;
             }
             case "--repo": {
                 const slug = argv[++i];
                 if (slug === undefined)
-                    throw new CliUsageError("--repo requires a slug");
-                flags.repo = slug;
+                    fail("--repo requires a slug");
+                else
+                    flags.repo = slug;
                 continue;
             }
             case "--server": {
+                // An empty value is a mistake, not "local": the flag was given.
                 const s = argv[++i];
-                if (s === undefined)
-                    throw new CliUsageError("--server requires a command or url");
-                flags.server = s;
+                if (s === undefined || s === "")
+                    fail("--server requires a command or url");
+                else
+                    flags.server = s;
                 continue;
             }
             case "-H":
             case "--header": {
                 const h = argv[++i];
                 if (h === undefined)
-                    throw new CliUsageError(`${a} requires a "Name: value" header`);
-                (flags.headers ??= []).push(h);
+                    fail(`${a} requires a "Name: value" header`);
+                else
+                    (flags.headers ??= []).push(h);
                 continue;
             }
             case "--json":
@@ -90,12 +101,14 @@ export function parseGlobals(argv) {
                 }
                 // Once the command is known, anything unrecognized is its residual;
                 // a stray flag before any command is a usage error.
-                if (!command)
-                    throw new CliUsageError(`unknown flag ${a}`);
+                if (!command) {
+                    fail(`unknown flag ${a}`);
+                    continue;
+                }
                 rest.push(a);
         }
     }
-    return { flags, command, rest };
+    return { flags, command, rest, ...(error ? { error } : {}) };
 }
 // Per-command execution shared by the one-shot entry (main.ts) and the
 // interactive shell (cmd/shell.ts). Given a resolved Cli, a command name, and
@@ -110,18 +123,20 @@ export async function runCommand(cli, command, rest) {
     // `--help` after a command → route to help for that command. Help is
     // documentation, not work: it must never need a workspace, so it also skips
     // the freshness sweep below (which would otherwise fail with repo_not_found
-    // from any directory without a `.omgbase/`).
+    // from any directory without a `.omgbase/`). The help *words* (`config help`,
+    // a bare `node`, …) are the same request spelled differently (spec/cli §5).
     const args = cli.flags.help ? ["--help", ...rest] : rest;
+    const help = asksForHelp(cli.flags, resolved.name, rest);
     // Global `--server` (remote/MCP mode) is only implemented by some commands so
     // far (REMOTE_OK); reject it elsewhere rather than silently running locally.
-    if (cli.flags.server !== undefined && !cli.flags.help && !REMOTE_OK.has(resolved.name)) {
+    if (cli.flags.server !== undefined && !help && !REMOTE_OK.has(resolved.name)) {
         return renderError(new CliUsageError(`--server is not supported for '${resolved.name}' — it needs local ref resolution or a working tree; run it against a local workspace`), cli.io, cli.style, cli.flags.mode !== "human");
     }
     try {
         // Freshness sweep (11 §3.3): current-by-default, unless --stale, a live
         // watcher holds the lease, remote (`--server`) mode (no local tree to sweep),
         // or the command manages sync itself.
-        if (!cli.flags.help && !cli.flags.stale && cli.flags.server === undefined && !SKIP_FRESHNESS.has(resolved.name) && !NO_WORKSPACE_OK.has(resolved.name)) {
+        if (!help && !cli.flags.stale && cli.flags.server === undefined && !SKIP_FRESHNESS.has(resolved.name) && !NO_WORKSPACE_OK.has(resolved.name)) {
             const ws = cli.workspace();
             if (!watchLeaseLive(ws.omgbaseDir)) {
                 // Best-effort: a workspace with no attached repo (or an unresolvable
@@ -142,7 +157,9 @@ export async function runCommand(cli, command, rest) {
         return await resolved.run(cli, args);
     }
     catch (err) {
-        return renderError(err, cli.io, cli.style, cli.flags.mode !== "human");
+        // A command's own `parseArgs` rejecting an option is a usage error (exit 2),
+        // rendered here once for every verb rather than in each parser.
+        return renderError(usageFromParseArgs(err, cli.prog, resolved.name), cli.io, cli.style, cli.flags.mode !== "human");
     }
 }
 //# sourceMappingURL=dispatch.js.map

package/dist/src/main.d.ts

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
 import { type IO } from "./render.js";
+import { cliVersion } from "./build.js";
+export { cliVersion };
 export declare function run(argv: string[], io?: IO, prog?: string): Promise<number>;

package/dist/src/main.js

@@ -1,30 +1,24 @@
 #!/usr/bin/env node
-import { VERSION } from "@omgbase/core";
 import { processIO } from "./render.js";
 import { makeCli, progName } from "./context.js";
-import { renderError, EXIT_OK, EXIT_USAGE } from "./output.js";
+import { renderError, EXIT_OK } from "./output.js";
 import { resolveCommand, unknownCommandError } from "./commands.js";
 import { runCommand, parseGlobals } from "./dispatch.js";
 import { closeRemote } from "./cmd/_remote.js";
+import { installSpecSeams } from "./seams.js";
+import { cliVersion } from "./build.js";
 // Hand-rolled router (11 §8: no commander). Splits global flags from the
 // command + its residual argv (parseGlobals, in dispatch.ts), resolves the
 // command (with aliases), then delegates to runCommand for the freshness sweep +
 // dispatch + error mapping — the same path the shell reuses per line.
+export { cliVersion };
 export async function run(argv, io = processIO, prog = "omg") {
-    let parsed;
-    try {
-        parsed = parseGlobals(argv);
-    }
-    catch (err) {
-        // No Cli/style yet — render minimally.
-        io.err(String(err.message ?? err));
-        return EXIT_USAGE;
-    }
+    const parsed = parseGlobals(argv);
     const { flags } = parsed;
     let command = parsed.command;
     // --version / --help without a command.
-    if (flags.version && !command) {
-        io.out(VERSION);
+    if (flags.version && !command && !parsed.error) {
+        io.out(cliVersion());
         return EXIT_OK;
     }
     if (flags.help && !command)
@@ -32,6 +26,18 @@ export async function run(argv, io = processIO, prog = "omg") {
     if (!command)
         command = "help";
     const cli = makeCli(flags, io, { prog });
+    // A malformed global flag is a usage error like any other (spec/cli §2.2):
+    // rendered with the `usage:` prefix, in the mode the argv selected.
+    if (parsed.error)
+        return renderError(parsed.error, io, cli.style, flags.mode !== "human");
+    // The conformance seams (spec/cli §2.6) apply to every verb: install them
+    // before any command can open the workspace, mint an id or read the clock.
+    try {
+        installSpecSeams();
+    }
+    catch (err) {
+        return renderError(err, io, cli.style, flags.mode !== "human");
+    }
     if (!resolveCommand(command)) {
         return renderError(unknownCommandError(prog, command), io, cli.style, flags.mode !== "human");
     }

package/dist/src/output.d.ts

@@ -1,5 +1,6 @@
 import { type IO } from "./render.js";
 import type { Style } from "./style.js";
+import type { OutputMode } from "./context.js";
 export declare const EXIT_OK = 0;
 export declare const EXIT_ERROR = 1;
 export declare const EXIT_USAGE = 2;
@@ -9,6 +10,14 @@ export declare class CliUsageError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
+/**
+ * Node's `parseArgs` failures are the user's mistake, not the engine's (spec/cli
+ * §2.2): an option the command does not declare, a value-taking option without
+ * its value, a boolean given one. Each becomes a usage error with a portable
+ * message — the wording is ours, so a port need not reproduce Node's — and the
+ * hint points at the command's card. Anything else is returned untouched.
+ */
+export declare function usageFromParseArgs(err: unknown, prog: string, command: string): unknown;
 export interface HelpSpec {
     name: string;
     summary: string;
@@ -52,9 +61,27 @@ export declare class EngineErrorLike extends Error {
 /**
  * Render a thrown error to stderr and return the process exit code. `json`
  * selects machine output (typed object); otherwise the human form with any
- * current-truth payload pretty-printed.
+ * current-truth payload pretty-printed. Both forms carry the hint; an empty
+ * payload (`{}`) prints nothing.
  */
 export declare function renderError(err: unknown, io: IO, style: Style, json: boolean): number;
+export interface MachineShape {
+    /** the list `--jsonl` streams (absent: the result is not list-shaped) */
+    items?: unknown[];
+    /** the ids `--ids` prints (absent: the result carries no id list) */
+    ids?: string[];
+    /** the cursor of a truncated result, for the footer */
+    cursor?: string | number | null;
+}
+interface MachineIO {
+    io: IO;
+    style: Style;
+    flags: {
+        mode: OutputMode;
+    };
+}
+/** Print `doc` in the current machine mode (`--json`/`--jsonl`/`--ids`); returns EXIT_OK. */
+export declare function emitMachine(cli: MachineIO, doc: unknown, shape?: MachineShape): number;
 export interface HitLike {
     id: string;
     path: string;