omgbase 0.1.0

package/dist/src/cmd/log.js

@@ -0,0 +1,109 @@
+import { parseArgs } from "node:util";
+import { changesSince } from "@omgbase/core";
+import { CliUsageError, truncationFooter, EXIT_OK, renderHelp } from "../output.js";
+import { remoteCall } from "./_remote.js";
+// `omg log` (11 §5.5) — changes_since, one digest summary per line. Relative
+// --since (24h/7d) is resolved to a literal ISO timestamp client-side, then to
+// the commit seq at/just-before that time (the query language stays clock-free).
+function resolveSinceSeq(cli, repoId, since) {
+    if (!since)
+        return 0;
+    const iso = relativeToIso(since);
+    const ws = cli.workspace();
+    const row = ws.store.db
+        .prepare("SELECT MAX(seq) AS seq FROM commits WHERE repo_id = ? AND ts < ?")
+        .get(repoId, iso);
+    return row.seq ?? 0;
+}
+function relativeToIso(since) {
+    const m = /^(\d+)([hdwm])$/.exec(since.trim());
+    if (m) {
+        const n = Number(m[1]);
+        const unit = m[2];
+        const ms = unit === "h" ? 3600e3 : unit === "d" ? 86400e3 : unit === "w" ? 7 * 86400e3 : 30 * 86400e3;
+        return new Date(Date.now() - n * ms).toISOString();
+    }
+    // Absolute timestamp: pass through (Date normalizes).
+    const t = Date.parse(since);
+    return Number.isNaN(t) ? new Date(0).toISOString() : new Date(t).toISOString();
+}
+async function runLog(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            since: { type: "string" },
+            cursor: { type: "string" },
+            origin: { type: "string" },
+            n: { type: "string", short: "n" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "log",
+            summary: "What changed: one digest per commit, newest first",
+            usage: "log [--since <24h|7d|ISO>] [--cursor <n>] [--origin api|observed] [-n <N>]",
+            options: [
+                ["--since <t>", "only commits after a relative age (24h, 7d) or an ISO timestamp"],
+                ["--cursor <n>", "continue from a commit sequence number"],
+                ["--origin <o>", "api (agent/CLI writes) | observed (file edits picked up by sync)"],
+                ["-n <N>", "max commits"],
+            ],
+        });
+    }
+    let result;
+    if (cli.flags.server) {
+        // Remote: changes_since by cursor/limit/origin. `--since` resolves a
+        // timestamp against the local commits table, which a remote client lacks —
+        // use `--cursor` remotely.
+        if (values.since)
+            throw new CliUsageError("--since is not supported with --server; use --cursor <seq>");
+        result = await remoteCall(cli, "changes_since", {
+            ...(values.cursor ? { cursor: Number(values.cursor) } : {}),
+            ...(values.n ? { limit: Number(values.n) } : {}),
+            ...(values.origin ? { origin: values.origin } : {}),
+        });
+    }
+    else {
+        const ws = cli.workspace();
+        const repo = cli.repo(ws);
+        const cursor = values.cursor ? Number(values.cursor) : resolveSinceSeq(cli, repo.repoId, values.since);
+        const opts = { cursor };
+        if (values.n)
+            opts.limit = Number(values.n);
+        if (values.origin)
+            opts.origin = values.origin;
+        result = changesSince(ws.store, repo.repoId, opts);
+    }
+    if (cli.flags.mode === "json") {
+        cli.io.out(JSON.stringify(result));
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "jsonl") {
+        for (const d of result.digests)
+            cli.io.out(JSON.stringify(d));
+        if (result.truncated)
+            truncationFooter(cli.io, cli.style, result.cursor);
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "ids") {
+        for (const d of result.digests)
+            cli.io.out(d.commit);
+        return EXIT_OK;
+    }
+    const { style, io } = cli;
+    if (result.digests.length === 0) {
+        io.err(style.dim("  no changes"));
+        return EXIT_OK;
+    }
+    for (const d of result.digests) {
+        const origin = d.origin === "observed" ? style.accent(d.origin.padEnd(8)) : style.warn(d.origin.padEnd(8));
+        io.out(`${style.dim(`#${d.seq}`)} ${origin} ${d.summary}`);
+    }
+    if (result.truncated)
+        truncationFooter(io, style, result.cursor);
+    return EXIT_OK;
+}
+export const cmdLog = { name: "log", summary: "Commit digests (change feed)", run: (cli, a) => runLog(cli, a) };
+//# sourceMappingURL=log.js.map

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

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

package/dist/src/cmd/ls.js

@@ -0,0 +1,88 @@
+import { parseArgs } from "node:util";
+import { docsList } from "@omgbase/core";
+import { columns } from "../render.js";
+import { EXIT_OK, renderHelp } from "../output.js";
+import { remoteCall } from "./_remote.js";
+// `omg ls [glob]` (11 §5.2) — live documents: path, block count, last-commit
+// time. glob is a simple prefix/suffix match on the path (SQL LIKE with * → %).
+//
+// The engine pages docs_list (uniform truncated+cursor contract, mcp-api §1);
+// a terminal `ls` is complete by definition, so this walks every page — local
+// or `--server` — and renders the concatenation.
+async function runLs(cli, args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "ls",
+            summary: "List live documents: path, block count, last-commit time (always the complete listing)",
+            usage: "ls [<glob>] [--ids|--json|--jsonl]",
+            options: [
+                ["<glob>", "path filter; `*` matches any run of characters (`notes/*.md`)"],
+                ["--ids", "paths only, one per line (pipe fuel)"],
+            ],
+        });
+    }
+    const glob = positionals[0];
+    const rows = [];
+    let cursor = null;
+    do {
+        let page;
+        if (cli.flags.server) {
+            page = await remoteCall(cli, "docs_list", { ...(glob ? { path_glob: glob } : {}), ...(cursor ? { cursor } : {}) });
+        }
+        else {
+            const ws = cli.workspace();
+            const repo = cli.repo(ws);
+            page = docsList(ws.store, repo.repoId, { ...(glob ? { pathGlob: glob } : {}), ...(cursor ? { cursor } : {}) });
+        }
+        rows.push(...page.items);
+        cursor = page.truncated ? page.cursor : null;
+    } while (cursor);
+    cli.capture?.(rows); // shell: docs become the addressable frame (ref = path)
+    if (cli.flags.mode === "ids") {
+        for (const r of rows)
+            cli.io.out(r.path);
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "json") {
+        cli.io.out(JSON.stringify(rows));
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "jsonl") {
+        for (const r of rows)
+            cli.io.out(JSON.stringify(r));
+        return EXIT_OK;
+    }
+    const { style, io } = cli;
+    if (rows.length === 0) {
+        io.err(style.dim("  no documents"));
+        return EXIT_OK;
+    }
+    const table = rows.map((r) => [
+        style.accent(r.path),
+        style.dim(`${r.blocks} blocks`),
+        style.dim(relTime(r.ts)),
+    ]);
+    for (const line of columns(table, [{}, { align: "right" }, { align: "right" }]))
+        io.out(line);
+    return EXIT_OK;
+}
+function relTime(ts) {
+    if (!ts)
+        return "—";
+    const then = Date.parse(ts);
+    if (Number.isNaN(then))
+        return ts;
+    const secs = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.floor(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hrs = Math.floor(mins / 60);
+    if (hrs < 24)
+        return `${hrs}h ago`;
+    return `${Math.floor(hrs / 24)}d ago`;
+}
+export const cmdLs = { name: "ls", summary: "List live documents", run: (cli, a) => runLs(cli, a) };
+//# sourceMappingURL=ls.js.map

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

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

package/dist/src/cmd/mcp.js

@@ -0,0 +1,192 @@
+import { parseArgs } from "node:util";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, EmbedDrainer, EngineError } from "@omgbase/core";
+import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { loadEmbedding } from "./_embed.js";
+import { openRepoSource } from "./_source.js";
+// `omg mcp [--no-watch]` (11 §5.8) — MCP server on stdio; the host owns the
+// process lifetime. Runs an in-process watcher by default so a lone session is
+// always fresh, auto-disabled when another live watch lease exists; --no-watch
+// forces it off.
+//
+// CRITICAL: on stdio, stdout is the MCP protocol channel. Nothing may write to
+// stdout here — every diagnostic goes to stderr (cli.io.err).
+async function runMcp(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { "no-watch": { type: "boolean" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "mcp",
+            summary: "Serve the MCP tool surface on stdio for an MCP host (Claude Code, Cursor, …); the host owns the process lifetime",
+            usage: "mcp [-C <workspace-dir>] [--repo <slug>] [--no-watch]",
+            options: [
+                ["-C <dir>", "the workspace to serve — a directory at or below one containing .omgbase/ (the host rarely starts you inside it)"],
+                ["--repo <slug>", "which repo, when the workspace has several"],
+                ["--no-watch", "don't run the in-process file watcher (it is auto-off when another live watcher holds the lease)"],
+            ],
+            notes: [`host config: {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]}`],
+        });
+    }
+    // The host launches us from its own cwd, so a missing workspace here almost
+    // always means the host config lacks `-C <dir>` — say so, rather than the
+    // generic "run init" hint (which would create an empty workspace in the wrong place).
+    let ws;
+    try {
+        ws = cli.workspace();
+    }
+    catch (err) {
+        if (err instanceof EngineErrorLike && err.code === "repo_not_found") {
+            throw new EngineErrorLike("repo_not_found", err.message, {
+                hint: `\`${cli.prog} mcp\` serves one workspace: point it there with -C, e.g. {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]} in the MCP host config — or create one first with \`${cli.prog} init <dir>\` and \`${cli.prog} -C <dir> source add .\``,
+            });
+        }
+        throw err;
+    }
+    const repo = cli.repo(ws);
+    // Connect the configured embedder once (if any) so the query tool's
+    // `semantic` mode has a vectorizer for the session. Unset ⇒ semantic queries
+    // return semantic_unavailable. The spawned process lives for the session and
+    // is released on shutdown.
+    //
+    // A CONFIGURED-but-broken embedder must never be mistaken for "no embedder":
+    // we don't take the whole server down over it (non-semantic tools work fine),
+    // but we complain loudly at startup and make every semantic access fail with a
+    // clear `embedder_failed` (see the throwing embedQuery below), so the fault is
+    // impossible to miss instead of silently degrading to keyword-only search.
+    let embedding = null;
+    let embedderError = null;
+    try {
+        embedding = await loadEmbedding(ws, repo.repoId);
+        if (embedding)
+            cli.io.err(cli.style.dim(`[mcp] semantic query enabled via ${embedding.providerName}`));
+    }
+    catch (err) {
+        embedderError = err instanceof EngineError && err.code === "embedder_failed" ? err : null;
+        if (!embedderError)
+            throw err; // an unexpected failure is still fatal
+        const d = (embedderError.data ?? {});
+        cli.io.err(cli.style.err("[mcp] ✖ EMBEDDER NONFUNCTIONAL — semantic search + auto-embed disabled"));
+        cli.io.err(cli.style.err(`      provider: ${d.provider ?? "?"}`));
+        cli.io.err(cli.style.err(`      reason:   ${d.reason ?? embedderError.message}`));
+        cli.io.err(cli.style.err("      semantic queries will fail with embedder_failed until this is fixed."));
+    }
+    // Keep embeddings timely: a background drainer embeds blocks touched by a
+    // mutation (or a watcher checkpoint) without blocking the tool's response.
+    // Only meaningful when a provider is configured.
+    const drainer = embedding
+        ? new EmbedDrainer(ws.store, repo.repoId, embedding.worker, {
+            onDrain: ({ embedded }) => cli.io.err(cli.style.dim(`[mcp] embedded ${embedded} block(s)`)),
+            onError: (err) => cli.io.err(cli.style.dim(`[mcp] embed drain failed: ${String(err)}`)),
+        })
+        : null;
+    // Decide whether to run the in-process watcher. Off if --no-watch, or if a
+    // live watcher already holds the lease (another `omg watch`/`omg mcp`).
+    const leaseHeld = watchLeaseLive(ws.omgbaseDir);
+    const wantWatch = !values["no-watch"] && !leaseHeld;
+    let lease = null;
+    let watcher = null;
+    let source = null;
+    if (wantWatch) {
+        lease = WatchLease.tryAcquire(ws.omgbaseDir);
+        if (lease) {
+            // Prime with a one-shot sweep so the session starts fresh, then watch via
+            // the external fs-adapter process (chokidar lives there, not in-engine).
+            if (repo.rootPath)
+                freshnessSweep(ws.store, repo.repoId, repo.rootPath);
+            source = await openRepoSource(ws.store, repo);
+            if (source) {
+                watcher = new Watcher(ws.store, repo.repoId, source, {
+                    onCheckpoint: (r) => {
+                        if (r.ingested.length > 0 || r.deleted.length > 0) {
+                            cli.io.err(cli.style.dim(`[watch] checkpoint: +${r.ingested.length} -${r.deleted.length}`));
+                            // A file change the watcher ingested may also need (re-)embedding.
+                            drainer?.schedule();
+                        }
+                    },
+                    onError: (err) => cli.io.err(cli.style.dim(`[watch] error: ${String(err)}`)),
+                });
+                await watcher.start();
+                cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · watcher live`));
+            }
+            else {
+                cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · sourceless (no watch)`));
+            }
+        }
+        else {
+            // Lost the race for the lease; another watcher is live — serve without one.
+            cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · watcher elsewhere`));
+        }
+    }
+    else {
+        const why = values["no-watch"] ? "watcher off (--no-watch)" : "watcher elsewhere";
+        cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · ${why}`));
+    }
+    if (drainer)
+        cli.io.err(cli.style.dim(`[mcp] auto-embed on mutation enabled`));
+    // The query surface's `embedQuery`: a live vectorizer when the embedder loaded,
+    // or — when it's configured-but-broken — a hook that throws `embedder_failed`
+    // so semantic access fails loudly and specifically (not the misleading
+    // `semantic_unavailable`, which the server emits only when embedQuery is
+    // absent, i.e. genuinely no provider configured). `const` captures satisfy
+    // closure narrowing over the `let`-bound state above.
+    const loaded = embedding;
+    const failed = embedderError;
+    const embedQuery = loaded
+        ? async (text) => ({ model: loaded.provider.model, vec: await loaded.worker.embedQuery(text) })
+        : failed
+            ? (_text) => Promise.reject(failed)
+            : undefined;
+    const handle = await serveStdio({
+        store: ws.store,
+        repoId: repo.repoId,
+        ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
+        ...(drainer ? { onMutation: () => drainer.schedule() } : {}),
+        ...(embedQuery ? { embedQuery } : {}),
+    });
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        if (watcher)
+            await watcher.stop();
+        if (source)
+            await source.close();
+        lease?.release();
+        // Drain any pending embeds before killing the provider process. flush()
+        // runs a debounced-but-not-yet-fired drain; close() then awaits in-flight.
+        if (drainer) {
+            try {
+                await drainer.flush();
+            }
+            catch { /* reported via onError */ }
+            await drainer.close();
+        }
+        if (embedding)
+            await embedding.close();
+        await handle.close();
+        ws.close();
+    };
+    // Host-owned lifetime: end on client disconnect or a signal. The in-process
+    // watcher keeps the event loop alive, so we can't rely on the loop draining —
+    // exit explicitly once cleanup completes. Three end triggers: the transport's
+    // onclose (handle.closed), stdin EOF, and SIGINT/SIGTERM.
+    const finish = () => {
+        void shutdown().finally(() => process.exit(0));
+    };
+    process.once("SIGINT", finish);
+    process.once("SIGTERM", finish);
+    process.stdin.once("end", finish);
+    process.stdin.once("close", finish);
+    handle.closed.then(finish, finish);
+    await handle.closed;
+    return EXIT_OK;
+}
+export const cmdMcp = {
+    name: "mcp",
+    summary: "Serve the MCP tool surface on stdio",
+    run: (cli, a) => runMcp(cli, a),
+};
+//# sourceMappingURL=mcp.js.map

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

@@ -0,0 +1,10 @@
+import type { Command } from "../commands.js";
+export declare const cmdApply: Command;
+export declare const cmdInsert: Command;
+export declare const cmdUpdate: Command;
+export declare const cmdMove: Command;
+export declare const cmdRm: Command;
+export declare const cmdDone: Command;
+export declare const cmdAppend: Command;
+export declare const cmdSplit: Command;
+export declare const cmdMerge: Command;