omgbase 0.1.0

package/dist/src/commands.js

@@ -0,0 +1,112 @@
+import { CliUsageError } from "./output.js";
+import { cmdInit, cmdRepos } from "./cmd/bootstrap.js";
+import { cmdStatus } from "./cmd/status.js";
+import { cmdLs } from "./cmd/ls.js";
+import { cmdOutline } from "./cmd/outline.js";
+import { cmdCat } from "./cmd/cat.js";
+import { cmdShow } from "./cmd/show.js";
+import { cmdFind } from "./cmd/find.js";
+import { cmdOqx } from "./cmd/oqx.js";
+import { cmdLog } from "./cmd/log.js";
+import { cmdHist } from "./cmd/hist.js";
+import { cmdDiff } from "./cmd/diff.js";
+import { cmdLinks } from "./cmd/links.js";
+import { cmdSync } from "./cmd/sync.js";
+import { cmdMcp } from "./cmd/mcp.js";
+import { cmdApply, cmdInsert, cmdMove, cmdRm, cmdDone, cmdAppend, cmdSplit, cmdMerge } from "./cmd/mutate.js";
+import { cmdEdit } from "./cmd/edit.js";
+import { cmdRetarget } from "./cmd/retarget.js";
+import { cmdNode } from "./cmd/node.js";
+import { cmdNew, cmdMv, cmdMeta } from "./cmd/docs.js";
+import { cmdUpdateDoc } from "./cmd/update.js";
+import { cmdRun } from "./cmd/run.js";
+import { cmdRebuild, cmdGc, cmdDoctor, cmdConfig, cmdEmbed } from "./cmd/admin.js";
+import { cmdShell } from "./cmd/shell.js";
+import { cmdSource } from "./cmd/source.js";
+import { cmdHelp } from "./cmd/help.js";
+export const COMMANDS = [
+    cmdInit,
+    cmdRepos,
+    cmdStatus,
+    cmdLs,
+    cmdOutline,
+    cmdCat,
+    cmdShow,
+    cmdFind,
+    cmdOqx,
+    cmdLog,
+    cmdHist,
+    cmdDiff,
+    cmdLinks,
+    cmdApply,
+    cmdInsert,
+    cmdUpdateDoc,
+    cmdEdit,
+    cmdMove,
+    cmdRm,
+    cmdDone,
+    cmdAppend,
+    cmdRetarget,
+    cmdNode,
+    cmdSplit,
+    cmdMerge,
+    cmdNew,
+    cmdMv,
+    cmdMeta,
+    cmdRun,
+    cmdShell,
+    cmdSource,
+    cmdSync,
+    cmdMcp,
+    cmdRebuild,
+    cmdGc,
+    cmdDoctor,
+    cmdConfig,
+    cmdEmbed,
+    cmdHelp,
+];
+const BY_NAME = new Map();
+for (const c of COMMANDS) {
+    BY_NAME.set(c.name, c);
+    for (const a of c.aliases ?? [])
+        BY_NAME.set(a, c);
+}
+export function resolveCommand(name) {
+    return BY_NAME.get(name) ?? null;
+}
+/**
+ * The usage error for an unrecognized command: names the typo, points at the
+ * command list (quoting the binary as it was invoked), and — when one listed
+ * command or alias is within two edits — offers it as "did you mean".
+ */
+export function unknownCommandError(prog, name) {
+    const hint = `run '${prog} --help' for the command list`;
+    const guess = didYouMean(name);
+    return new CliUsageError(`unknown command '${name}'`, guess ? `did you mean '${guess}'? ${hint}` : hint);
+}
+function didYouMean(name) {
+    // Two edits for a real word, one for something short — `statsu` → status,
+    // `lz` → ls, but a lone `x` suggests nothing rather than `q`.
+    const maxEdits = name.length <= 3 ? 1 : 2;
+    let best = null;
+    for (const candidate of BY_NAME.keys()) {
+        const d = editDistance(name.toLowerCase(), candidate);
+        if (d <= maxEdits && (!best || d < best.d))
+            best = { name: candidate, d };
+    }
+    return best?.name ?? null;
+}
+// Levenshtein distance; the inputs are short command names, so the plain
+// two-row DP is plenty.
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+//# sourceMappingURL=commands.js.map

package/dist/src/context.d.ts

@@ -0,0 +1,73 @@
+import { Workspace, type RepoRow } from "@omgbase/core";
+import { Style } from "./style.js";
+import { Renderer, type IO } from "./render.js";
+import { CliUsageError } from "./output.js";
+export type OutputMode = "human" | "json" | "jsonl" | "ids";
+export interface GlobalFlags {
+    directory?: string;
+    repo?: string;
+    mode: OutputMode;
+    stale: boolean;
+    noColor: boolean;
+    dryRun: boolean;
+    /**
+     * --server <cmd|url>: run the command against a remote engine over MCP instead
+     * of the embedded local store (ADR-014). Global by design — the surface is
+     * uniform and commands adopt remote mode one at a time (REMOTE_OK). Reads,
+     * doc-level mutators, block-level sugar (via server-side ref resolution + CAS),
+     * sync, and shell all implement it; the handful of genuinely local-only ops
+     * (e.g. `status`'s watcher state, `node props`) error rather than run locally.
+     */
+    server?: string;
+    /**
+     * -H / --header "Name: value": extra HTTP headers, repeatable, sent on every
+     * request when `--server` is an http(s) URL (auth beyond a secret path). Kept
+     * in flag order; ignored for stdio `--server` commands.
+     */
+    headers?: string[];
+    help: boolean;
+    version: boolean;
+}
+export interface Cli {
+    flags: GlobalFlags;
+    io: IO;
+    style: Style;
+    render: Renderer;
+    cwd: string;
+    /**
+     * The name the binary was invoked as (`omg` or `omgbase` — the two `bin`
+     * entries), used wherever help/hints quote a command back to the user so the
+     * text matches what they actually typed. Defaults to `omg`.
+     */
+    prog: string;
+    /**
+     * Optional typed-result sink (11 shell). When present, a command calls it with
+     * its structured library result — the same object `--json` would emit — before
+     * terminal formatting. The interactive shell installs a sink to capture typed
+     * bindings (`@_`, `@1`, `let x = …`); one-shot CLI leaves it undefined (no-op).
+     */
+    capture?: (value: unknown) => void;
+    /** Resolve the workspace (walk up from cwd/-C). Throws repo_not_found if none. */
+    workspace(): Workspace;
+    /** Resolve the active repo within the workspace, honoring --repo. */
+    repo(ws: Workspace): RepoRow;
+}
+/** Optional overrides for makeCli — the shell reuses one open Workspace across
+ *  commands and installs a capture sink; one-shot CLI passes nothing. */
+export interface CliOptions {
+    workspace?: Workspace;
+    capture?: (value: unknown) => void;
+    cwd?: string;
+    prog?: string;
+}
+/**
+ * The name to quote the binary as, from `process.argv[1]`: the basename when
+ * invoked through a `bin` shim (`omg`, `omgbase`), else `omg` — a direct
+ * `node dist/src/main.js` run would otherwise print "main.js".
+ */
+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 SKIP_FRESHNESS: Set<string>;
+export declare const REMOTE_OK: Set<string>;
+export { CliUsageError };

package/dist/src/context.js

@@ -0,0 +1,80 @@
+import { basename, resolve } from "node:path";
+import { Workspace, RepoSelectionError } from "@omgbase/core";
+import { Style } from "./style.js";
+import { Renderer } from "./render.js";
+import { CliUsageError, EngineErrorLike } from "./output.js";
+/**
+ * The name to quote the binary as, from `process.argv[1]`: the basename when
+ * invoked through a `bin` shim (`omg`, `omgbase`), else `omg` — a direct
+ * `node dist/src/main.js` run would otherwise print "main.js".
+ */
+export function progName(argv1) {
+    if (!argv1)
+        return "omg";
+    const b = basename(argv1);
+    return /\.(c|m)?js$/.test(b) || b.length === 0 ? "omg" : b;
+}
+export function makeCli(flags, io, opts = {}) {
+    const cwd = opts.cwd ?? (flags.directory ? resolveDir(flags.directory) : process.cwd());
+    const noColor = flags.noColor || !io.stdoutTTY || process.env.NO_COLOR != null;
+    const style = new Style({ noColor, isTTY: io.stdoutTTY });
+    const render = new Renderer(style);
+    const prog = opts.prog ?? "omg";
+    let cachedWs = opts.workspace ?? null;
+    return {
+        flags,
+        io,
+        style,
+        render,
+        cwd,
+        prog,
+        ...(opts.capture ? { capture: opts.capture } : {}),
+        workspace() {
+            if (cachedWs)
+                return cachedWs;
+            const ws = Workspace.find(cwd);
+            if (!ws) {
+                throw new EngineErrorLike("repo_not_found", `no omgbase workspace found at or above ${cwd}`, { hint: `run \`${prog} init\` to create one here, or \`${prog} -C <dir> …\` to run inside an existing workspace` });
+            }
+            cachedWs = ws;
+            return ws;
+        },
+        repo(ws) {
+            try {
+                return ws.selectRepo(cwd, flags.repo);
+            }
+            catch (err) {
+                if (err instanceof RepoSelectionError) {
+                    throw new EngineErrorLike(err.code, err.message, { data: { candidates: err.candidates } });
+                }
+                throw err;
+            }
+        },
+    };
+}
+function resolveDir(dir) {
+    return resolve(dir);
+}
+// Which commands may run without a workspace (11 §2.1).
+export const NO_WORKSPACE_OK = new Set(["init", "help", "version"]);
+// 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.
+export const SKIP_FRESHNESS = new Set(["sync", "mcp", "init", "source", "help", "version", "shell"]);
+// Commands that implement the global `--server` remote (MCP-client) mode
+// (ADR-014). Others error on `--server` rather than silently running locally.
+// Covers reads, doc-level mutators, block-level sugar, sync, and shell — the
+// block sugar resolves refs + pins CAS server-side via the blocks_* tools.
+export const REMOTE_OK = new Set([
+    // reads
+    "sync", "query", "outline", "hist", "cat", "ls", "diff", "find", "log",
+    // doc-level mutators
+    "new", "mv", "meta", "rm", "update", "retarget",
+    // block-level sugar (server-side ref resolution + CAS via the blocks_* /
+    // tasks_complete / sections_append / node_set / apply tools)
+    "apply", "insert", "move", "split", "merge", "done", "append", "node",
+    // shell accepts --server itself, then threads it into every line it runs.
+    "shell",
+]);
+export { CliUsageError };
+//# sourceMappingURL=context.js.map

package/dist/src/dispatch.d.ts

@@ -0,0 +1,8 @@
+import { type Cli, type GlobalFlags } from "./context.js";
+export interface Parsed {
+    flags: GlobalFlags;
+    command: string | null;
+    rest: string[];
+}
+export declare function parseGlobals(argv: string[]): Parsed;
+export declare function runCommand(cli: Cli, command: string, rest: string[]): Promise<number>;

package/dist/src/dispatch.js

@@ -0,0 +1,148 @@
+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 { resolveCommand, unknownCommandError } from "./commands.js";
+export function parseGlobals(argv) {
+    const flags = {
+        mode: "human",
+        stale: false,
+        noColor: false,
+        dryRun: false,
+        help: false,
+        version: false,
+    };
+    let command = null;
+    const rest = [];
+    let passthrough = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (passthrough) {
+            rest.push(a);
+            continue;
+        }
+        if (a === "--") {
+            passthrough = true;
+            if (command)
+                rest.push(a);
+            continue;
+        }
+        switch (a) {
+            case "-C":
+            case "--directory": {
+                const dir = argv[++i];
+                if (dir === undefined)
+                    throw new CliUsageError(`${a} requires a directory`);
+                flags.directory = dir;
+                continue;
+            }
+            case "--repo": {
+                const slug = argv[++i];
+                if (slug === undefined)
+                    throw new CliUsageError("--repo requires a slug");
+                flags.repo = slug;
+                continue;
+            }
+            case "--server": {
+                const s = argv[++i];
+                if (s === undefined)
+                    throw new CliUsageError("--server requires a command or url");
+                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);
+                continue;
+            }
+            case "--json":
+                flags.mode = "json";
+                continue;
+            case "--jsonl":
+                flags.mode = "jsonl";
+                continue;
+            case "--ids":
+                flags.mode = "ids";
+                continue;
+            case "--stale":
+                flags.stale = true;
+                continue;
+            case "--no-color":
+                flags.noColor = true;
+                continue;
+            case "--dry-run":
+                flags.dryRun = true;
+                continue;
+            case "--help":
+            case "-h":
+                flags.help = true;
+                continue;
+            case "--version":
+            case "-V":
+                flags.version = true;
+                continue;
+            default:
+                if (!command && !a.startsWith("-")) {
+                    command = a;
+                    continue;
+                }
+                // 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}`);
+                rest.push(a);
+        }
+    }
+    return { flags, command, rest };
+}
+// 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
+// its residual argv, this runs the freshness sweep (11 §3.3), dispatches the
+// command, and maps thrown errors to exit codes via the output contract. The
+// shell reuses this so a shell line behaves exactly like a one-shot invocation.
+export async function runCommand(cli, command, rest) {
+    const resolved = resolveCommand(command);
+    if (!resolved) {
+        return renderError(unknownCommandError(cli.prog, command), cli.io, cli.style, cli.flags.mode !== "human");
+    }
+    // `--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/`).
+    const args = cli.flags.help ? ["--help", ...rest] : 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)) {
+        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)) {
+            const ws = cli.workspace();
+            if (!watchLeaseLive(ws.omgbaseDir)) {
+                // Best-effort: a workspace with no attached repo (or an unresolvable
+                // cwd) has nothing to sweep. That's not an error for the command
+                // itself — only the sweep is skipped; the command surfaces its own
+                // repo_not_found if it truly needs a repo.
+                try {
+                    const repo = cli.repo(ws);
+                    if (repo.rootPath)
+                        freshnessSweep(ws.store, repo.repoId, repo.rootPath);
+                }
+                catch (err) {
+                    if (!(err instanceof EngineErrorLike && err.code === "repo_not_found"))
+                        throw err;
+                }
+            }
+        }
+        return await resolved.run(cli, args);
+    }
+    catch (err) {
+        return renderError(err, cli.io, cli.style, cli.flags.mode !== "human");
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/src/main.d.ts

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

package/dist/src/main.js

@@ -0,0 +1,67 @@
+#!/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 { resolveCommand, unknownCommandError } from "./commands.js";
+import { runCommand, parseGlobals } from "./dispatch.js";
+import { closeRemote } from "./cmd/_remote.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;
+    }
+    const { flags } = parsed;
+    let command = parsed.command;
+    // --version / --help without a command.
+    if (flags.version && !command) {
+        io.out(VERSION);
+        return EXIT_OK;
+    }
+    if (flags.help && !command)
+        command = "help";
+    if (!command)
+        command = "help";
+    const cli = makeCli(flags, io, { prog });
+    if (!resolveCommand(command)) {
+        return renderError(unknownCommandError(prog, command), io, cli.style, flags.mode !== "human");
+    }
+    try {
+        return await runCommand(cli, command, parsed.rest);
+    }
+    finally {
+        // Tear down the remote (`--server`) MCP connection if the command opened one.
+        await closeRemote();
+    }
+}
+// Entry point.
+//
+// Exit quietly when a downstream consumer closes our stdout early (`omg … | head`,
+// or `… --ids | omg done -` where `done` stops reading): a broken-pipe write
+// otherwise surfaces as an unhandled 'error' event and crashes with a stack
+// trace. Standard pipe-friendly behavior for a CLI that advertises composing
+// with grep/head/xargs (§1).
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (err) => {
+        if (err.code === "EPIPE")
+            process.exit(0);
+        throw err;
+    });
+}
+// Quote the binary back to the user as they invoked it (`omg` vs `omgbase`).
+run(process.argv.slice(2), processIO, progName(process.argv[1])).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(String(err?.stack ?? err) + "\n");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=main.js.map

package/dist/src/output.d.ts

@@ -0,0 +1,60 @@
+import type { IO } from "./render.js";
+import type { Style } from "./style.js";
+export declare const EXIT_OK = 0;
+export declare const EXIT_ERROR = 1;
+export declare 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 declare class CliUsageError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+export interface HelpSpec {
+    name: string;
+    summary: string;
+    /** Usage form(s) WITHOUT the program name (`cat <node…|-> [--resolution r]`). */
+    usage: string | string[];
+    /** `[flag, description]` rows; `-h, --help` is appended automatically. */
+    options?: [string, string][];
+    /** Extra lines printed verbatim under the options (examples, sub-commands). */
+    notes?: string[];
+}
+interface HelpIO {
+    io: IO;
+    style: Style;
+    prog: string;
+}
+export declare function renderHelp(cli: HelpIO, spec: HelpSpec): number;
+/**
+ * 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 declare class EngineErrorLike extends Error {
+    readonly code: string;
+    readonly extra: {
+        data?: unknown;
+        hint?: string;
+        retriable?: boolean;
+    };
+    constructor(code: string, message: string, extra?: {
+        data?: unknown;
+        hint?: string;
+        retriable?: boolean;
+    });
+    body(): {
+        error: string;
+        message: string;
+        data?: unknown;
+        retriable: boolean;
+    };
+}
+/**
+ * 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 declare function renderError(err: unknown, io: IO, style: Style, json: boolean): number;
+/** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
+export declare function truncationFooter(io: IO, style: Style, cursor: number | string): void;
+export {};