omgbase 0.3.0 → 0.4.1

package/dist/src/cmd/run.js

@@ -1,7 +1,8 @@
 import { parseArgs } from "node:util";
 import { resolveRef, findDoc, loadDocBlocks, blockRaw, oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, truncationFooter, EXIT_OK, renderHelp, renderHits } from "../output.js";
+import { CliUsageError, EngineErrorLike, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
+import { renderOqxResult } from "./oqx.js";
 // `omg run <locator|path>` (11 §5.3) — evaluate the first ```omg fence in a doc
 // (or the fence at a block locator) and print its results. The fence body is an
 // OQX source string (the same language `omg query` runs). Strictly read-and-print:
@@ -98,37 +99,9 @@ async function runRun(cli, args) {
     else {
         result = oqxRun(ws.store, repo.repoId, source);
     }
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
-    if (result.consumer === "count" || result.consumer === "exists" || result.consumer === "none") {
-        cli.io.out(result.consumer === "count" ? String(result.count) : result.consumer === "exists" ? String(result.exists) : String(result.none));
-        return EXIT_OK;
-    }
-    if (result.values) {
-        for (const v of result.values)
-            cli.io.out(typeof v === "string" ? 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);
-        return EXIT_OK;
-    }
-    const { style, io } = cli;
-    if (result.hits.length === 0) {
-        io.err(style.dim("  no hits"));
-        return EXIT_OK;
-    }
-    // Same renderer as `omg query`: `<id>  <path>` lines, or a column table when
-    // the fence projects (a selected `text` shows as its first line).
-    renderHits(cli, result.hits);
-    if (result.truncated)
-        truncationFooter(io, style, result.cursor ?? "");
-    return EXIT_OK;
+    // Same renderer as `omg query`, in every mode: `<id>  <path>` lines, or a
+    // column table when the fence projects (a selected `text` shows as its first line).
+    return renderOqxResult(cli, result);
 }
 export const cmdRun = { name: "run", summary: "Evaluate an ```omg fence (OQX, inert, read-only)", run: (c, a) => runRun(c, a) };
 //# sourceMappingURL=run.js.map

package/dist/src/cmd/show.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
-import { resolveRef, nodesGet, findDoc, docLinks, historyNode, docPropertiesMerged } from "@omgbase/core";
-import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { resolveRef, nodesGet, docsRead, docLinks, historyNode, docPropertiesMerged } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { expandBlockArgs } from "./_mutate.js";
 function showOne(cli, ref, include) {
     const ws = cli.workspace();
@@ -9,11 +9,15 @@ function showOne(cli, ref, include) {
     if (!resolved)
         throw new EngineErrorLike("doc_missing", `no node ${ref}`);
     if (resolved.kind === "document") {
-        const info = findDoc(ws.store, { docId: resolved.docId });
+        // The card reads the merged properties + open edges; `--json` is the
+        // `read_ref` result for a document (`{ kind: "document", ...docs_read }`).
+        const res = docsRead(ws.store, resolved.docId);
+        if (!res)
+            throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         const links = docLinks(ws.store, resolved.docId, { direction: "both" });
         const properties = docPropertiesMerged(ws.store.db, resolved.docId);
-        const payload = { kind: "document", id: info.docId, path: info.path, properties, edges: links };
-        return { payload, render: () => renderDocCard(cli, info.path, properties, links) };
+        const payload = { kind: "document", ...res };
+        return { payload, render: () => renderDocCard(cli, res.path, properties, links) };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution: "full" });
     if (!node)
@@ -47,14 +51,9 @@ function runShow(cli, args) {
     // One ref keeps the single-entity shape (→ @_, frame intact); several become a list.
     const single = cards.length === 1 ? cards[0] : null;
     cli.capture?.(single ? single.payload : cards.map((c) => c.payload));
-    if (cli.flags.mode === "json") {
-        cli.io.out(JSON.stringify(single ? single.payload : cards.map((c) => c.payload)));
-        return EXIT_OK;
-    }
     if (cli.flags.mode !== "human") {
-        for (const c of cards)
-            cli.io.out(JSON.stringify(c.payload));
-        return EXIT_OK;
+        const docs = cards.map((c) => c.payload);
+        return single ? emitMachine(cli, single.payload) : emitMachine(cli, docs, { items: docs });
     }
     for (const c of cards)
         c.render();

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

@@ -1,8 +1,8 @@
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, EngineError } from "@omgbase/core";
+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"));
@@ -97,8 +96,11 @@ function runOneShot(cli, ws, repo) {
         io.out(`  ${style.dim("already up to date")}`);
     return EXIT_OK;
 }
-// Local live watcher (the former `omg watch`): prime with a sweep, then run the
-// external fs-adapter watcher until a signal, keeping embeddings warm.
+// Local live watcher (the former `omg watch`), in the order of spec/sync §5:
+// take the lease, open the source, `watch`, wait for `ready` (bounded), THEN the
+// priming sweep, then report live — so an edit landing before the feed is primed
+// is caught by the sweep and one landing after it by the feed. Runs until a
+// signal, keeping embeddings warm.
 async function runLocalWatch(cli, ws, repo) {
     const lease = WatchLease.tryAcquire(ws.omgbaseDir);
     if (!lease)
@@ -124,8 +126,6 @@ async function runLocalWatch(cli, ws, repo) {
             onError: (err) => cli.io.err(cli.style.dim(`  embed drain failed: ${String(err)}`)),
         })
         : null;
-    if (repo.rootPath)
-        freshnessSweep(ws.store, repo.repoId, repo.rootPath); // start fresh
     const source = await openRepoSource(ws.store, repo);
     if (!source) {
         cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to watch`));
@@ -146,6 +146,11 @@ async function runLocalWatch(cli, ws, repo) {
         onError: (err) => cli.io.err(cli.style.err(`  watch error: ${String(err)}`)),
     });
     await watcher.start();
+    if (!(await awaitReady(watcher.ready(), WATCH_READY_PATIENCE_MS))) {
+        cli.io.err(cli.style.dim(`  the fs adapter did not report ready within ${WATCH_READY_PATIENCE_MS / 1000}s — proceeding as if ready (an edit made before now may be missed until the next sweep)`));
+    }
+    if (repo.rootPath)
+        freshnessSweep(ws.store, repo.repoId, repo.rootPath); // prime: anything that landed before the feed was ready
     drainer?.schedule(); // embed anything already stale at startup, in the background
     cli.io.err(cli.style.dim(`  watching ${repo.slug} — Ctrl-C to stop${drainer ? " · auto-embed on" : ""}`));
     await new Promise((resolveWait) => {

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

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,10 @@
 #!/usr/bin/env node
 import { type IO } from "./render.js";
+/**
+ * `--version` prints THIS package's version (spec/cli §2.5), read from the
+ * nearest `package.json` named `omgbase` above the running module (the source
+ * tree and the built `dist/src/` sit at different depths). The engine's own
+ * `VERSION` is the fallback only if the package file cannot be found.
+ */
+export declare function cliVersion(): string;
 export declare function run(argv: string[], io?: IO, prog?: string): Promise<number>;

package/dist/src/main.js

@@ -1,30 +1,52 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 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";
 // 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 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;
+/**
+ * `--version` prints THIS package's version (spec/cli §2.5), read from the
+ * nearest `package.json` named `omgbase` above the running module (the source
+ * tree and the built `dist/src/` sit at different depths). The engine's own
+ * `VERSION` is the fallback only if the package file cannot be found.
+ */
+export function cliVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === "omgbase" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                /* keep walking */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return VERSION;
+        dir = parent;
     }
+}
+export async function run(argv, io = processIO, prog = "omg") {
+    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 +54,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");
     }