omgbase 0.1.0

package/dist/src/output.js

@@ -0,0 +1,131 @@
+// Output contract + error rendering (11 §2.4, §4).
+//
+// Exit codes:  0 success (incl. truncated)  ·  1 typed engine error / conflict
+//              2 CLI usage error (unknown flag, missing arg)
+//
+// Errors always go to stderr. Human form: `error[code]: message` + any
+// current-truth payload pretty-printed. With --json: the typed error object as
+// JSON on stderr, nothing on stdout.
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USAGE = 2;
+/** A CLI-level usage error (bad flag, missing argument) → exit 2. An optional
+ *  `hint` is a one-line pointer at the fix (e.g. "run 'omg --help' …"). */
+export class CliUsageError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = "CliUsageError";
+    }
+}
+export function renderHelp(cli, spec) {
+    const { io, style, prog } = cli;
+    io.out(`  ${style.bold(spec.name)} — ${spec.summary}`);
+    const usages = Array.isArray(spec.usage) ? spec.usage : [spec.usage];
+    usages.forEach((u, i) => io.out(`  ${style.dim(i === 0 ? "usage:" : "      ")} ${prog} ${u}`));
+    const options = [...(spec.options ?? []), ["-h, --help", "show this help"]];
+    const width = Math.max(...options.map(([f]) => f.length));
+    io.out(`  ${style.dim("options:")}`);
+    for (const [flag, desc] of options)
+        io.out(`    ${style.accent(flag.padEnd(width))}  ${desc}`);
+    if (spec.notes && spec.notes.length > 0) {
+        io.out("");
+        for (const n of spec.notes)
+            io.out(`  ${n}`);
+    }
+    return EXIT_OK;
+}
+/**
+ * An engine-style typed error the CLI raises directly (mirrors core's
+ * EngineError body shape, 06 §5) — used for repo_not_found, ambiguous repo,
+ * etc., that originate in the CLI layer rather than the engine.
+ */
+export class EngineErrorLike extends Error {
+    code;
+    extra;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.code = code;
+        this.extra = extra;
+        this.name = "EngineErrorLike";
+    }
+    body() {
+        return {
+            error: this.code,
+            message: this.message,
+            ...(this.extra.data !== undefined ? { data: this.extra.data } : {}),
+            retriable: this.extra.retriable ?? false,
+        };
+    }
+}
+/** Coerce any thrown value into a typed error body for rendering. */
+function toBody(err) {
+    if (err instanceof EngineErrorLike) {
+        const b = err.body();
+        return {
+            code: b.error,
+            message: b.message,
+            ...(b.data !== undefined ? { data: b.data } : {}),
+            ...(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) };
+}
+/**
+ * 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.
+ */
+export function renderError(err, io, style, json) {
+    if (err instanceof CliUsageError) {
+        if (json)
+            io.err(JSON.stringify({ error: "usage", message: err.message, ...(err.hint ? { hint: err.hint } : {}), retriable: false }));
+        else {
+            io.err(`${style.err("usage")}: ${err.message}`);
+            if (err.hint)
+                io.err(style.dim(`  hint: ${err.hint}`));
+        }
+        return EXIT_USAGE;
+    }
+    const body = toBody(err);
+    if (json) {
+        io.err(JSON.stringify({ error: body.code, message: body.message, ...(body.data !== undefined ? { data: body.data } : {}), retriable: false }));
+        return EXIT_ERROR;
+    }
+    io.err(`${style.err(`error[${body.code}]`)}: ${body.message}`);
+    if (body.hint)
+        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) {
+        io.err(style.dim(indent(JSON.stringify(body.data, null, 2), "  ")));
+    }
+    return EXIT_ERROR;
+}
+function indent(s, pad) {
+    return s
+        .split("\n")
+        .map((l) => pad + l)
+        .join("\n");
+}
+/** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
+export function truncationFooter(io, style, cursor) {
+    io.err(style.dim(`… truncated; continue with --cursor ${cursor}`));
+}
+//# sourceMappingURL=output.js.map

package/dist/src/render.d.ts

@@ -0,0 +1,44 @@
+import { Style, type Glyphs, type Tier } from "./style.js";
+/** Visible width of a string, ignoring ANSI SGR sequences. */
+export declare function visibleWidth(s: string): number;
+export declare function stripAnsi(s: string): string;
+export interface Column {
+    /** "left" (default) or "right" alignment. */
+    align?: "left" | "right";
+}
+/** Align a matrix of already-styled cells into padded columns joined by gap. */
+export declare function columns(rows: string[][], cols?: Column[], gap?: string): string[];
+export declare class Renderer {
+    readonly style: Style;
+    readonly g: Glyphs;
+    readonly tier: Tier;
+    constructor(style: Style);
+    /** The branded wordmark line: gradient "omgbase" + accent arrow + subject. */
+    wordmark(subject?: string): string;
+    /** A full-width gradient underline for the header (rich only; else a rule). */
+    rule(width?: number): string;
+    /** A colored status dot + label, e.g. ● live / ○ none. */
+    statusDot(state: "live" | "none" | "ok" | "warn" | "err", label: string): string;
+    /** Glyph for a node/block type (used in outlines and hit lists). */
+    typeGlyph(type: string): string;
+    /** id (dim) paired with locator (accent) — the §4.2 pairing. */
+    idLocator(id: string, locator: string): string;
+}
+export interface IO {
+    out(s: string): void;
+    err(s: string): void;
+    readonly stdoutTTY: boolean;
+    readonly stderrTTY: boolean;
+}
+export declare const processIO: IO;
+/** Collecting IO for tests: captures out/err lines. */
+export declare class CaptureIO implements IO {
+    outLines: string[];
+    errLines: string[];
+    stdoutTTY: boolean;
+    stderrTTY: boolean;
+    out(s: string): void;
+    err(s: string): void;
+    get stdout(): string;
+    get stderr(): string;
+}

package/dist/src/render.js

@@ -0,0 +1,116 @@
+import { Style, glyphs } from "./style.js";
+// Human-facing renderer (11 §4). Columns, the branded header/box, status lines,
+// hit lists — all TTY-only pizzazz. Width math strips ANSI so colored cells
+// still align. Nothing here touches the machine paths (--json/--jsonl/--ids),
+// which emit library objects verbatim from the command layer.
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Visible width of a string, ignoring ANSI SGR sequences. */
+export function visibleWidth(s) {
+    return stripAnsi(s).length;
+}
+export function stripAnsi(s) {
+    return s.replace(ANSI_RE, "");
+}
+function padEndVisible(s, width) {
+    const pad = width - visibleWidth(s);
+    return pad > 0 ? s + " ".repeat(pad) : s;
+}
+function padStartVisible(s, width) {
+    const pad = width - visibleWidth(s);
+    return pad > 0 ? " ".repeat(pad) + s : s;
+}
+/** Align a matrix of already-styled cells into padded columns joined by gap. */
+export function columns(rows, cols = [], gap = "  ") {
+    const widths = [];
+    for (const row of rows) {
+        row.forEach((cell, i) => {
+            widths[i] = Math.max(widths[i] ?? 0, visibleWidth(cell));
+        });
+    }
+    return rows.map((row) => row
+        .map((cell, i) => {
+        const w = widths[i] ?? 0;
+        // Don't pad the final column (avoids trailing whitespace).
+        if (i === row.length - 1)
+            return cell;
+        return (cols[i]?.align === "right" ? padStartVisible : padEndVisible)(cell, w);
+    })
+        .join(gap)
+        .replace(/\s+$/, ""));
+}
+export class Renderer {
+    style;
+    g;
+    tier;
+    constructor(style) {
+        this.style = style;
+        this.tier = style.tier;
+        this.g = glyphs(style.tier);
+    }
+    /** The branded wordmark line: gradient "omgbase" + accent arrow + subject. */
+    wordmark(subject) {
+        const mark = this.style.gradient("omgbase");
+        if (!subject)
+            return `  ${mark}`;
+        return `  ${mark}  ${this.style.dim(this.g.arrow)}  ${this.style.bold(subject)}`;
+    }
+    /** A full-width gradient underline for the header (rich only; else a rule). */
+    rule(width = 40) {
+        return "  " + this.style.gradientBar(width);
+    }
+    /** A colored status dot + label, e.g. ● live / ○ none. */
+    statusDot(state, label) {
+        switch (state) {
+            case "live":
+                return `${this.style.ok(this.g.live)} ${label}`;
+            case "none":
+                return `${this.style.dim(this.g.dead)} ${label}`;
+            case "ok":
+                return `${this.style.ok(this.g.ok)} ${label}`;
+            case "warn":
+                return `${this.style.warn(this.g.warn)} ${label}`;
+            case "err":
+                return `${this.style.err(this.g.err)} ${label}`;
+        }
+    }
+    /** Glyph for a node/block type (used in outlines and hit lists). */
+    typeGlyph(type) {
+        if (type === "heading")
+            return this.style.accent(this.g.heading);
+        if (type === "task")
+            return this.g.taskOpen;
+        if (type.startsWith("doc"))
+            return this.style.path(this.g.doc);
+        return this.style.dim(this.g.block);
+    }
+    /** id (dim) paired with locator (accent) — the §4.2 pairing. */
+    idLocator(id, locator) {
+        return `${this.style.id(id)}  ${this.style.accent(locator)}`;
+    }
+}
+export const processIO = {
+    out: (s) => process.stdout.write(s.endsWith("\n") ? s : s + "\n"),
+    err: (s) => process.stderr.write(s.endsWith("\n") ? s : s + "\n"),
+    stdoutTTY: Boolean(process.stdout.isTTY),
+    stderrTTY: Boolean(process.stderr.isTTY),
+};
+/** Collecting IO for tests: captures out/err lines. */
+export class CaptureIO {
+    outLines = [];
+    errLines = [];
+    stdoutTTY = false;
+    stderrTTY = false;
+    out(s) {
+        this.outLines.push(s);
+    }
+    err(s) {
+        this.errLines.push(s);
+    }
+    get stdout() {
+        return this.outLines.join("\n");
+    }
+    get stderr() {
+        return this.errLines.join("\n");
+    }
+}
+//# sourceMappingURL=render.js.map

package/dist/src/shell/refs.d.ts

@@ -0,0 +1,37 @@
+export declare class RefError extends Error {
+}
+/** A selectable item within a displayed collection or a bound collection. */
+export interface Row {
+    /** The argv string this row substitutes to (an id, locator, path, or scalar). */
+    ref: string;
+    /** Human label for `bindings` / frame listings. */
+    label: string;
+    /** The underlying typed value (for `.field` access). */
+    value: unknown;
+}
+/** A captured command result: the whole typed value plus any selectable rows. */
+export interface Captured {
+    value: unknown;
+    /** Non-null ⇒ this result is a selectable collection (replaces the frame). */
+    rows: Row[] | null;
+}
+export interface ParsedRef {
+    base: string;
+    index?: number;
+    field?: string;
+}
+/** Parse a whole-token reference; null if the token isn't a reference. */
+export declare function parseRef(token: string): ParsedRef | null;
+/**
+ * Derive the selectable rows of a captured value. Returns null when the value
+ * is a card / scalar / text (no collection) — the caller then leaves the
+ * numbered frame intact (the note's "showing one thing shouldn't destroy the
+ * frame"). Returns an array (possibly empty) when the value IS a collection.
+ */
+export declare function deriveRows(value: unknown): Row[] | null;
+/**
+ * Coerce a resolved value to a single argv string. Entities collapse to their
+ * id/locator; scalars stringify; a bare collection is an error (the caller must
+ * pick a row with `[i]`) — the shell never flattens a collection into one arg.
+ */
+export declare function coerce(value: unknown): string;

package/dist/src/shell/refs.js

@@ -0,0 +1,111 @@
+// Session references (11 shell). The shell stores typed command results and
+// dereferences them; it does NOT filter/map/traverse — that stays OQX's job.
+//
+// Three reference roots, all written with `@` (OQX already owns `$…`):
+//   @N        row N (1-based) of the most recent displayed collection frame
+//   @_        the previous command's typed result
+//   @name     a named binding (`@name = …`)
+// Each may carry a shallow tail: an optional `[i]` (1-based collection index)
+// then an optional `.field`. That is the whole grammar — deeper access is a
+// signal to use OQX instead.
+export class RefError extends Error {
+}
+const REF_RE = /^@(\d+|_|[A-Za-z][\w-]*)(?:\[(\d+)\])?(?:\.([A-Za-z_]\w*))?$/;
+/** Parse a whole-token reference; null if the token isn't a reference. */
+export function parseRef(token) {
+    if (!token.startsWith("@"))
+        return null;
+    const m = REF_RE.exec(token);
+    if (!m)
+        throw new RefError(`bad reference '${token}' (use @N, @_, @name, optional [i] and .field)`);
+    const out = { base: m[1] };
+    if (m[2] !== undefined)
+        out.index = Number(m[2]);
+    if (m[3] !== undefined)
+        out.field = m[3];
+    return out;
+}
+/**
+ * Derive the selectable rows of a captured value. Returns null when the value
+ * is a card / scalar / text (no collection) — the caller then leaves the
+ * numbered frame intact (the note's "showing one thing shouldn't destroy the
+ * frame"). Returns an array (possibly empty) when the value IS a collection.
+ */
+export function deriveRows(value) {
+    if (Array.isArray(value))
+        return value.map(rowOf);
+    if (value && typeof value === "object") {
+        const o = value;
+        if (Array.isArray(o.hits))
+            return o.hits.map(rowOf); // query/oqx
+        if (Array.isArray(o.digests))
+            return o.digests.map(rowOf); // log
+        if (Array.isArray(o.results) && Array.isArray(o.revisions)) {
+            // ApplyResult: the minted/affected ids, flattened (one row per id).
+            const ids = [];
+            for (const r of o.results) {
+                if (Array.isArray(r.ids))
+                    for (const id of r.ids)
+                        if (typeof id === "string")
+                            ids.push(id);
+            }
+            return ids.map((id) => ({ ref: id, label: id, value: id }));
+        }
+        if (Array.isArray(o.in) || Array.isArray(o.out)) {
+            // links: both directions, each edge's far node is the selectable ref.
+            const edges = [...(o.out ?? []), ...(o.in ?? [])];
+            return edges.map(rowOf);
+        }
+    }
+    return null;
+}
+function rowOf(el) {
+    if (typeof el === "string")
+        return { ref: el, label: el, value: el };
+    if (el && typeof el === "object") {
+        const o = el;
+        const ref = firstString(o, ["id", "node", "block", "locator", "path"]);
+        const label = firstString(o, ["path", "locator", "name", "id", "node"]) ?? ref ?? preview(o);
+        return { ref: ref ?? label ?? "", label: label ?? "", value: el };
+    }
+    const s = String(el);
+    return { ref: s, label: s, value: el };
+}
+function firstString(o, keys) {
+    for (const k of keys)
+        if (typeof o[k] === "string")
+            return o[k];
+    return undefined;
+}
+function preview(o) {
+    const s = JSON.stringify(o);
+    return s.length > 60 ? s.slice(0, 57) + "…" : s;
+}
+/**
+ * Coerce a resolved value to a single argv string. Entities collapse to their
+ * id/locator; scalars stringify; a bare collection is an error (the caller must
+ * pick a row with `[i]`) — the shell never flattens a collection into one arg.
+ */
+export function coerce(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value == null)
+        throw new RefError("reference is empty");
+    if (Array.isArray(value)) {
+        throw new RefError(`reference is a collection of ${value.length}; select one with [i]`);
+    }
+    if (typeof value === "object") {
+        const o = value;
+        const ref = firstString(o, ["id", "node", "block", "locator", "path"]);
+        if (ref)
+            return ref;
+        // A collection-shaped result object (e.g. {hits:[…]}) can't be one arg.
+        if (deriveRows(value))
+            throw new RefError("reference is a collection; select one with [i]");
+        throw new RefError("reference has no id/locator to use as an argument");
+    }
+    throw new RefError("reference is not usable as an argument");
+}
+//# sourceMappingURL=refs.js.map

package/dist/src/shell/session.d.ts

@@ -0,0 +1,71 @@
+import type { Workspace } from "@omgbase/core";
+import type { IO } from "../render.js";
+import { EXIT_OK, EXIT_ERROR } from "../output.js";
+export interface ShellSessionOptions {
+    /** The shared local workspace. Omitted in remote (`--server`) mode: every line
+     *  routes over MCP and never touches a local store. */
+    workspace?: Workspace;
+    cwd: string;
+    io: IO;
+    /** Force plain styling for the shell's own notices (matches the command tier). */
+    noColor?: boolean;
+    /** Remote engine address (`--server <cmd|url>`): threaded into every line so
+     *  each command runs against the remote engine and shares one connection. */
+    server?: string;
+    /** Extra HTTP headers (`-H`) for an http(s) `--server`: threaded alongside it. */
+    headers?: string[];
+}
+export declare class ShellSession {
+    private readonly workspace;
+    private readonly cwd;
+    private readonly io;
+    private readonly style;
+    private readonly server;
+    private readonly headers;
+    private readonly bindings;
+    private frame;
+    private last;
+    /** Set by `exit`/`quit`; the interactive loop watches this. */
+    exited: boolean;
+    constructor(opts: ShellSessionOptions);
+    /** Execute one input line. Returns an exit code (0 ok, 1 error, 2 usage). */
+    exec(line: string): Promise<number>;
+    /**
+     * `@name = <command | @ref>` — bind a snapshot of a result under `name`.
+     * A command runs quietly (stdout suppressed); a bare `@ref` copies its value.
+     * The target must be a plain name (no `[i]`/`.field`, not `@_`/`@N`).
+     */
+    private doAssign;
+    private doUnset;
+    private doBindings;
+    private doShellHelp;
+    /** A normal omg command line: substitute refs, dispatch, record the result. */
+    private runLine;
+    /**
+     * Build a per-line Cli over the shared Workspace and run the command through
+     * the same path as a one-shot invocation (freshness sweep + dispatch + error
+     * mapping). `sink` receives the command's typed result; `quiet` drops stdout
+     * (used by `let`, which snapshots rather than displays).
+     */
+    private dispatch;
+    /** Update @_ and, when the result is a collection, replace the numbered frame. */
+    private record;
+    /** Inspect a bare `@ref` line: print it and, if a collection, make it the frame. */
+    private inspect;
+    /** Replace whole-token `@refs` with their coerced argv strings. */
+    private substitute;
+    /**
+     * Resolve a reference token to its typed value plus, when known, a direct
+     * argv-usable id/locator. Coercion is deferred to the caller (substitution)
+     * so that inspecting a bare collection reference does not error.
+     */
+    resolveRef(token: string): {
+        value: unknown;
+        ref?: string;
+    };
+    private summary;
+    private usage;
+    /** An IO that drops stdout (data) but forwards stderr (diagnostics). */
+    private quietIO;
+}
+export { EXIT_OK, EXIT_ERROR };