omgbase 0.3.0 → 0.4.1

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;

package/dist/src/output.js

@@ -1,3 +1,4 @@
+import { errorBody } from "@omgbase/core";
 import { columns, visibleWidth } from "./render.js";
 // Output contract + error rendering (11 §2.4, §4).
 //
@@ -20,6 +21,34 @@ export class CliUsageError extends Error {
         this.name = "CliUsageError";
     }
 }
+/**
+ * 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 function usageFromParseArgs(err, prog, command) {
+    const e = err;
+    if (!e || typeof e !== "object" || typeof e.code !== "string" || !e.code.startsWith("ERR_PARSE_ARGS_") || typeof e.message !== "string")
+        return err;
+    const hint = `run '${prog} ${command} --help' for the options`;
+    const unknown = /^Unknown option '([^']+)'/.exec(e.message);
+    if (unknown)
+        return new CliUsageError(`unknown option '${unknown[1]}'`, hint);
+    const missing = /^Option '([^']+?)(?: <value>)?' argument missing/.exec(e.message);
+    if (missing)
+        return new CliUsageError(`option '${lastSpelling(missing[1])}' requires a value`, hint);
+    const extra = /^Option '([^']+)' does not take an argument/.exec(e.message);
+    if (extra)
+        return new CliUsageError(`option '${lastSpelling(extra[1])}' does not take a value`, hint);
+    return new CliUsageError(e.message, hint);
+}
+/** Node names an option with a short alias as `-n, --name`; quote the long form. */
+function lastSpelling(spellings) {
+    const parts = spellings.split(",").map((p) => p.trim()).filter(Boolean);
+    return parts[parts.length - 1] ?? spellings;
+}
 export function renderHelp(cli, spec) {
     const { io, style, prog } = cli;
     io.out(`  ${style.bold(spec.name)} — ${spec.summary}`);
@@ -60,7 +89,14 @@ export class EngineErrorLike extends Error {
         };
     }
 }
-/** Coerce any thrown value into a typed error body for rendering. */
+/**
+ * Coerce any thrown value into a typed error body for rendering. The CLI's own
+ * `EngineErrorLike` carries its code and hint; everything else goes through the
+ * engine's one mapping (`errorBody`, the same the MCP server renders — spec/cli
+ * §3.5): typed errors keep their code, OQX errors and a bad cursor are
+ * `filter_invalid`, an unknown revision `target_missing`, and anything else the
+ * catch-all `repo_not_found`.
+ */
 function toBody(err) {
     if (err instanceof EngineErrorLike) {
         const b = err.body();
@@ -71,27 +107,22 @@ function toBody(err) {
             ...(err.extra.hint ? { hint: err.extra.hint } : {}),
         };
     }
-    // core EngineError / MutationError / FilterInvalid all carry a code + message
-    // (and often a body()); duck-type them.
-    const anyErr = err;
-    if (typeof anyErr?.body === "function") {
-        const b = anyErr.body();
-        return { code: b.error ?? b.code ?? "error", message: b.message ?? String(err), data: b.data };
-    }
-    if (anyErr?.code) {
-        return {
-            code: anyErr.code,
-            message: anyErr.message ?? String(err),
-            ...(anyErr.data !== undefined ? { data: anyErr.data } : {}),
-            ...(anyErr.hint ? { hint: anyErr.hint } : {}),
-        };
-    }
-    return { code: "error", message: anyErr?.message ?? String(err) };
+    const b = errorBody(err);
+    return { code: b.error, message: b.message, ...(b.data !== undefined ? { data: b.data } : {}) };
+}
+/** A payload worth printing: anything but `undefined`, `null` and an empty record. */
+function hasPayload(data) {
+    if (data === undefined || data === null)
+        return false;
+    if (typeof data === "object" && !Array.isArray(data) && Object.keys(data).length === 0)
+        return false;
+    return true;
 }
 /**
  * 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 function renderError(err, io, style, json) {
     if (err instanceof CliUsageError) {
@@ -106,7 +137,7 @@ export function renderError(err, io, style, json) {
     }
     const body = toBody(err);
     if (json) {
-        io.err(JSON.stringify({ error: body.code, message: body.message, ...(body.data !== undefined ? { data: body.data } : {}), retriable: false }));
+        io.err(JSON.stringify({ error: body.code, message: body.message, ...(hasPayload(body.data) ? { data: body.data } : {}), ...(body.hint ? { hint: body.hint } : {}), retriable: false }));
         return EXIT_ERROR;
     }
     io.err(`${style.err(`error[${body.code}]`)}: ${body.message}`);
@@ -114,11 +145,26 @@ export function renderError(err, io, style, json) {
         io.err(style.dim(`  hint: ${body.hint}`));
     // Conflict objects carry current truth (04 §4) — print all of it; the retry
     // is built from it.
-    if (body.data !== undefined && body.data !== null) {
+    if (hasPayload(body.data)) {
         io.err(style.dim(indent(JSON.stringify(body.data, null, 2), "  ")));
     }
     return EXIT_ERROR;
 }
+/** Print `doc` in the current machine mode (`--json`/`--jsonl`/`--ids`); returns EXIT_OK. */
+export function emitMachine(cli, doc, shape = {}) {
+    const { io, style, flags } = cli;
+    if (flags.mode === "jsonl" && shape.items)
+        for (const item of shape.items)
+            io.out(JSON.stringify(item));
+    else if (flags.mode === "ids" && shape.ids)
+        for (const id of shape.ids)
+            io.out(id);
+    else
+        io.out(JSON.stringify(doc));
+    if (flags.mode !== "json" && shape.cursor !== undefined && shape.cursor !== null)
+        truncationFooter(io, style, shape.cursor);
+    return EXIT_OK;
+}
 function indent(s, pad) {
     return s
         .split("\n")

package/dist/src/seams.d.ts

@@ -0,0 +1,13 @@
+export interface SpecSeams {
+    /** the sequential minter is installed */
+    minter: boolean;
+    /** the pinned instant (canonical ISO form), when the clock is pinned */
+    clock: string | null;
+}
+/**
+ * Read + install the seams (idempotent: a second call returns what the first
+ * installed). Throws `CliUsageError` on an invalid value; the caller renders it.
+ */
+export declare function installSpecSeams(env?: NodeJS.ProcessEnv): SpecSeams;
+/** The seams installed by `installSpecSeams` (none when it has not run). */
+export declare function activeSpecSeams(): SpecSeams;

package/dist/src/seams.js

@@ -0,0 +1,37 @@
+import { pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
+import { CliUsageError } from "./output.js";
+let installed = null;
+/**
+ * Read + install the seams (idempotent: a second call returns what the first
+ * installed). Throws `CliUsageError` on an invalid value; the caller renders it.
+ */
+export function installSpecSeams(env = process.env) {
+    if (installed)
+        return installed;
+    const seams = { minter: false, clock: null };
+    const minter = env.OMGBASE_SPEC_MINTER;
+    if (minter !== undefined && minter !== "") {
+        if (minter !== "sequential") {
+            throw new CliUsageError(`OMGBASE_SPEC_MINTER=${JSON.stringify(minter)}: the only value is "sequential" (spec/surface §7.1)`, "unset it, or set OMGBASE_SPEC_MINTER=sequential for a conformance run");
+        }
+        setIdMinter(sequentialMinter());
+        seams.minter = true;
+    }
+    const clock = env.OMGBASE_SPEC_CLOCK;
+    if (clock !== undefined && clock !== "") {
+        try {
+            pinClock(clock);
+        }
+        catch {
+            throw new CliUsageError(`OMGBASE_SPEC_CLOCK=${JSON.stringify(clock)}: not an RFC 3339 instant (spec/surface §7.1)`, "e.g. OMGBASE_SPEC_CLOCK=2026-09-27T00:00:00.000Z");
+        }
+        seams.clock = new Date().toISOString();
+    }
+    installed = seams;
+    return seams;
+}
+/** The seams installed by `installSpecSeams` (none when it has not run). */
+export function activeSpecSeams() {
+    return installed ?? { minter: false, clock: null };
+}
+//# sourceMappingURL=seams.js.map

package/dist/src/shell/session.js

@@ -142,7 +142,7 @@ export class ShellSession {
         line(`${style.accent("@1 @2 …")}   ${style.dim("rows of the last displayed collection")}`);
         line(`${style.accent("@_")}         ${style.dim("the previous command's result")}`);
         line(`${style.accent("@name")}      ${style.dim("a named binding (also @name[i], @name.field)")}`);
-        line("");
+        io.out("");
         line(`${style.accent("@x = <cmd|@ref>")}      ${style.dim("bind a snapshot of a result")}`);
         line(`${style.accent("unset x")}              ${style.dim("drop a binding")}`);
         line(`${style.accent("bindings")}             ${style.dim("list bindings")}`);
@@ -162,7 +162,9 @@ export class ShellSession {
      * (used by `let`, which snapshots rather than displays).
      */
     async dispatch(tokens, sink, quiet) {
-        const { flags, command, rest } = parseGlobals(tokens);
+        const { flags, command, rest, error } = parseGlobals(tokens);
+        if (error)
+            throw error;
         if (!command)
             return EXIT_OK;
         // In a remote session, thread the server address into every line (unless the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.3.0",
-    "@omgbase/fs-adapter": "^0.1.0",
-    "@omgbase/sync": "^0.3.0",
+    "@omgbase/core": "^0.4.1",
+    "@omgbase/fs-adapter": "^0.2.0",
+    "@omgbase/sync": "^0.4.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {