omgbase 0.1.0

package/dist/src/cmd/source.js

@@ -0,0 +1,231 @@
+import { resolve, basename } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline";
+import { createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, ensureRepo, freshnessSweep, walkMarkdownAsync, rebuildFileStats, } from "@omgbase/core";
+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";
+// `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
+// runs the initial sync. There is no separate "attach/ingest/load" verb —
+// `source add <dir>` is how content enters, and the initial ingest is just that
+// source's first sync (the same reconcile path every later sync uses).
+function help(cli) {
+    return renderHelp(cli, {
+        name: "source",
+        summary: "Where a repo's bytes come from (a filesystem directory today; git/S3/… via adapters later)",
+        usage: "source <add|list|attach|detach|rm> …",
+        options: [
+            ["add <dir> [--slug <s>] [--name <n>] [-y]", "point a repo at a directory: creates the repo + runs the initial sync (-y skips the consent prompt)"],
+            ["list", "list sources and which repos they feed"],
+            ["attach <name> [--repo <slug>]", "attach an existing source to a repo"],
+            ["detach <name> [--repo <slug>]", "detach a source from a repo"],
+            ["rm <name>", "delete a source (and its attachments)"],
+        ],
+    });
+}
+function attachedRepoSlugs(cli, ws, sourceId) {
+    return ws.repos().filter((r) => sourcesForRepo(ws.store, r.repoId).some((s) => s.sourceId === sourceId)).map((r) => r.slug);
+}
+async function runSource(cli, args) {
+    const sub = args[0];
+    if (!sub || sub === "--help" || sub === "help")
+        return help(cli);
+    const rest = args.slice(1);
+    switch (sub) {
+        case "add":
+            return runAdd(cli, rest);
+        case "list":
+            return runList(cli);
+        case "attach":
+            return runAttachDetach(cli, rest, "attach");
+        case "detach":
+            return runAttachDetach(cli, rest, "detach");
+        case "rm":
+            return runRm(cli, rest);
+        default:
+            throw new CliUsageError(`unknown source subcommand '${sub}'`);
+    }
+}
+// Walk `abs` for markdown while showing a growing count beside a [y/N] prompt.
+// The scan runs concurrently with the question; the count carries a `+` suffix
+// until the walk completes. Returns the answer plus whether the walk finished.
+async function confirmIngestWithCount(cli, abs, slug) {
+    const signal = { aborted: false };
+    let count = 0;
+    let complete = false;
+    const isTTY = cli.io.stdoutTTY && process.stdin.isTTY;
+    const render = () => {
+        if (!isTTY)
+            return;
+        process.stderr.write(`\r  add source for ${slug} — ${count}${complete ? "" : "+"} files  [y/N] `);
+    };
+    const walk = walkMarkdownAsync(abs, (n) => { count = n; render(); }, signal).then(() => { complete = true; render(); });
+    if (!isTTY) {
+        // No TTY to prompt: refuse rather than silently ingesting the tree.
+        signal.aborted = true;
+        await walk;
+        return { ok: false, complete };
+    }
+    render();
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((res) => rl.question("", res));
+    rl.close();
+    signal.aborted = true;
+    await walk;
+    return { ok: /^y(es)?$/i.test(answer.trim()), complete };
+}
+async function runAdd(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { slug: { type: "string" }, name: { type: "string" }, yes: { type: "boolean", short: "y" }, help: { type: "boolean" } },
+    });
+    if (values.help)
+        return help(cli);
+    const dir = positionals[0];
+    if (!dir)
+        throw new CliUsageError("source add requires a <dir>");
+    const abs = resolve(cli.cwd, dir);
+    if (!existsSync(abs) || !statSync(abs).isDirectory())
+        throw new EngineErrorLike("target_missing", `no such directory: ${abs}`);
+    const slug = values.slug ?? (basename(abs) || "vault");
+    const sourceName = values.name ?? `${slug}-fs`;
+    const ws = cli.workspace();
+    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.
+    if (!values.yes) {
+        const { ok } = await confirmIngestWithCount(cli, abs, slug);
+        if (cli.io.stdoutTTY)
+            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}`));
+            return EXIT_OK;
+        }
+    }
+    // A repo owns identity; register its fs source, then run the initial sync
+    // through the ordinary freshness path (the same reconcile every later sync
+    // uses). ensureRepo(…, null) mints identity only — the source is explicit.
+    const repoId = ensureRepo(ws.store, slug, null);
+    ensureFsAdapter(ws.store);
+    const sourceId = createSource(ws.store, { name: sourceName, adapter: FS_ADAPTER, config: { root: abs } });
+    attachSourceToRepo(ws.store, repoId, sourceId);
+    const swept = freshnessSweep(ws.store, repoId, abs);
+    rebuildFileStats(ws.store, repoId, abs);
+    // Offer to embed freshly-ingested blocks now (consent-gated like the ingest).
+    const drained = await drainEmbeddings(cli, ws, repoId, {
+        verbose: true,
+        confirm: async ({ pending, remote, providerName }) => {
+            if (pending === 0)
+                return false;
+            if (values.yes)
+                return true;
+            const where = remote ? `${providerName} (remote — block text leaves your machine)` : `${providerName} (local)`;
+            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;
+    }
+    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)
+        io.err(`  ${style.ok(render.g.ok)} embedded ${drained.embedded}, cached ${drained.cached}`);
+    return EXIT_OK;
+}
+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;
+    }
+    const { style, io } = cli;
+    if (sources.length === 0) {
+        io.out(style.dim("  no sources registered"));
+        return EXIT_OK;
+    }
+    const rows = sources.map((s) => [
+        `  ${style.accent(s.name)}`,
+        style.dim(s.adapter),
+        style.path(String(s.config.root ?? "")),
+        style.dim(s.repos.length > 0 ? `→ ${s.repos.join(", ")}` : "(unattached)"),
+    ]);
+    for (const line of columns(rows))
+        io.out(line);
+    return EXIT_OK;
+}
+function runAttachDetach(cli, args, verb) {
+    const { positionals } = parseArgs({ args, allowPositionals: true, options: {} });
+    const name = positionals[0];
+    if (!name)
+        throw new CliUsageError(`source ${verb} requires a <name>`);
+    const ws = cli.workspace();
+    const source = getSourceByName(ws.store, name);
+    if (!source)
+        throw new EngineErrorLike("target_missing", `no source named '${name}'`);
+    const repo = cli.repo(ws);
+    if (verb === "attach")
+        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;
+    }
+    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;
+}
+function runRm(cli, args) {
+    const { positionals } = parseArgs({ args, allowPositionals: true, options: {} });
+    const name = positionals[0];
+    if (!name)
+        throw new CliUsageError("source rm requires a <name>");
+    const ws = cli.workspace();
+    const source = getSourceByName(ws.store, name);
+    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;
+    }
+    cli.io.out(`  ${cli.render.g.ok} deleted source ${cli.style.accent(name)}`);
+    return EXIT_OK;
+}
+// small local helpers ---------------------------------------------------------
+async function confirmTTY(cli, question) {
+    if (!cli.io.stdoutTTY || !process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((res) => rl.question(`${question} [y/N] `, res));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function shortenHome(p) {
+    const home = process.env.HOME;
+    return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+export const cmdSource = { name: "source", summary: "Where a repo's bytes come from (add/list/attach/detach/rm)", run: (cli, a) => runSource(cli, a) };
+//# sourceMappingURL=source.js.map

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

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

package/dist/src/cmd/status.js

@@ -0,0 +1,95 @@
+import { parseArgs } from "node:util";
+import { reposStatus, syncStatus, watchLeaseLive } from "@omgbase/core";
+import { EXIT_OK, 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.
+function runStatus(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            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"]],
+        });
+    }
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    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;
+    }
+    const { render, style, io } = cli;
+    const g = render.g;
+    io.out(render.wordmark(repo.slug));
+    io.out(`  ${style.path(repo.rootPath ? shortenHome(repo.rootPath) : "(no source — headless)")}`);
+    io.out(render.rule(40));
+    // Two-column figure grid.
+    const left = [
+        [`${style.path(g.doc)} docs`, String(rs.docs)],
+        [`${style.dim(g.block)} blocks`, String(rs.blocks)],
+        [`${g.diamond} commits`, String(rs.commits)],
+        [`${g.arrow} edges`, String(rs.openEdges)],
+    ];
+    const right = [
+        ["watcher", watcher ? render.statusDot("live", "live") : render.statusDot("none", "none")],
+        ["synced", ss.convergent ? render.statusDot("ok", "converged") : render.statusDot("warn", syncedLabel(ss, rs.unconverged))],
+        ["queue", queued === 0 ? style.dim("empty") : style.warn(`${queued} queued`)],
+        ["commit#", style.dim(String(ss.lastCommitSeq))],
+    ];
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const l = left[i];
+        const r = right[i];
+        const lCell = l ? `  ${l[0]}  ${style.bold(l[1])}` : "  ";
+        const rCell = r ? `${style.dim(r[0].padEnd(8))}${r[1]}` : "";
+        io.out(padVisible(lCell, 26) + rCell);
+    }
+    return EXIT_OK;
+}
+// Summarize why the repo isn't convergent: DB-internal lag and/or on-disk drift.
+function syncedLabel(ss, unconverged) {
+    const parts = [];
+    if (unconverged > 0)
+        parts.push(`${unconverged} behind`);
+    if (ss.disk.deleted > 0)
+        parts.push(`${ss.disk.deleted} deleted`);
+    if (ss.disk.changed > 0)
+        parts.push(`${ss.disk.changed} drifted`);
+    if (ss.disk.untracked > 0)
+        parts.push(`${ss.disk.untracked} untracked`);
+    if (!ss.diskChecked)
+        parts.push("disk unverified");
+    return parts.length > 0 ? parts.join(", ") : "unconverged";
+}
+// Local width-aware pad (mirrors render.visibleWidth without importing the class).
+const ANSI = /\x1b\[[0-9;]*m/g;
+function padVisible(s, w) {
+    const vis = s.replace(ANSI, "").length;
+    return vis >= w ? s : s + " ".repeat(w - vis);
+}
+function shortenHome(p) {
+    const home = process.env.HOME;
+    return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+export const cmdStatus = { name: "status", summary: "Where am I: repo, sync, watcher, queue", run: (cli, a) => runStatus(cli, a) };
+//# sourceMappingURL=status.js.map

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

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

package/dist/src/cmd/sync.js

@@ -0,0 +1,176 @@
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, EngineError } from "@omgbase/core";
+import { runFsMirror } from "@omgbase/sync";
+import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { loadEmbedding } from "./_embed.js";
+import { openRepoSource } from "./_source.js";
+// `omg sync` — reconcile a repo with its filesystem source. One verb, three modes:
+//   omg sync                     one-shot local freshness sweep (fs → DB)
+//   omg sync --watch             stay live locally (external fs-adapter watcher)
+//   omg sync --server <cmd> …    the same, but against a remote engine over MCP
+//                                (the coordinator — mirrors `omgbase-sync`)
+// The `--server` form is the global remote flag (context REMOTE_OK); it shares
+// `runFsMirror` with the standalone `omgbase-sync` bin. There is no separate
+// `omg watch` — watching is `omg sync --watch`. The local one-shot IS the
+// explicit form of the freshness sweep every read runs by default.
+function help(cli) {
+    return renderHelp(cli, {
+        name: "sync",
+        summary: "Reconcile a repo with its filesystem source (one-shot by default; the explicit form of the freshness sweep every read runs)",
+        usage: ["sync [--watch]", 'sync --server <cmd|url> [-H "Name: value"]… [--root <dir>] [--out]'],
+        options: [
+            ["--watch", "stay live and reconcile edits as they land"],
+            ["--server <cmd|url>", "mirror a local directory into a remote engine over MCP (spawns <cmd>, or an http(s) url over Streamable HTTP)"],
+            ['-H "Name: value"', "(--server url) extra HTTP header, repeatable"],
+            ["--root <dir>", "(--server) the directory to mirror (default cwd)"],
+            ["--out", "(--server) also export engine-authored changes back to disk"],
+        ],
+    });
+}
+async function runSync(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { watch: { type: "boolean" }, out: { type: "boolean" }, root: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help)
+        return help(cli);
+    // Remote mode: run the coordinator against an MCP server (shared with the
+    // omgbase-sync bin). No local workspace needed — the fs dir is the source.
+    if (cli.flags.server !== undefined) {
+        const root = resolve(cli.cwd, values.root ?? ".");
+        const server = cli.flags.server.split(/\s+/).filter(Boolean);
+        await runFsMirror({
+            server,
+            root,
+            ...(values.watch ? { watch: true } : {}),
+            ...(values.out ? { out: true } : {}),
+            log: (msg) => cli.io.err(cli.style.dim(`  ${msg}`)),
+        });
+        return EXIT_OK;
+    }
+    // Local mode: resolve the workspace + repo and reconcile in-process.
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    return values.watch ? runLocalWatch(cli, ws, repo) : runOneShot(cli, ws, repo);
+}
+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 }));
+        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;
+    }
+    const { render, style, io } = cli;
+    const g = render.g;
+    io.out(render.wordmark("sync"));
+    io.out(render.rule(40));
+    io.out(`  ${style.dim("scanned")}   ${result.scanned} files`);
+    if (result.ingested.length > 0) {
+        io.out(`  ${style.ok(g.ok)} ingested  ${result.ingested.length}`);
+        for (const p of result.ingested)
+            io.out(`      ${style.accent(p)}`);
+    }
+    if (result.deleted.length > 0) {
+        io.out(`  ${style.err(g.err)} deleted   ${result.deleted.length}`);
+        for (const p of result.deleted)
+            io.out(`      ${style.dim(p)}`);
+    }
+    if (result.conflicted.length > 0) {
+        io.out(`  ${style.warn(g.warn)} conflicts ${result.conflicted.length}`);
+        for (const p of result.conflicted)
+            io.out(`      ${style.warn(p)}`);
+    }
+    if (!result.changed)
+        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.
+async function runLocalWatch(cli, ws, repo) {
+    const lease = WatchLease.tryAcquire(ws.omgbaseDir);
+    if (!lease)
+        throw new EngineErrorLike("target_missing", "another watcher already holds the lease for this workspace");
+    // A configured-but-broken embedder disables auto-embed but must not take the
+    // watcher down: warn loudly and keep watching (vectors just go stale until the
+    // embedder is fixed and a drain catches up). An unset provider is silent.
+    let embedding = null;
+    try {
+        embedding = await loadEmbedding(ws, repo.repoId);
+    }
+    catch (err) {
+        if (err instanceof EngineError && err.code === "embedder_failed") {
+            const d = (err.data ?? {});
+            cli.io.err(cli.style.err(`  ✖ EMBEDDER NONFUNCTIONAL — auto-embed disabled (provider: ${d.provider ?? "?"}; reason: ${d.reason ?? err.message})`));
+        }
+        else
+            throw err;
+    }
+    const drainer = embedding
+        ? new EmbedDrainer(ws.store, repo.repoId, embedding.worker, {
+            onDrain: ({ embedded }) => cli.io.err(cli.style.dim(`  embedded ${embedded} block(s)`)),
+            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`));
+        lease.release();
+        if (drainer)
+            await drainer.close();
+        if (embedding)
+            await embedding.close();
+        return EXIT_OK;
+    }
+    const watcher = new Watcher(ws.store, repo.repoId, source, {
+        onCheckpoint: (r) => {
+            if (r.ingested.length || r.deleted.length || r.conflicted.length) {
+                cli.io.err(`${cli.style.ok(cli.render.g.sync)} +${r.ingested.length} -${r.deleted.length}${r.conflicted.length ? ` !${r.conflicted.length}` : ""}`);
+                drainer?.schedule();
+            }
+        },
+        onError: (err) => cli.io.err(cli.style.err(`  watch error: ${String(err)}`)),
+    });
+    await watcher.start();
+    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) => {
+        const stop = () => {
+            const watchdog = setTimeout(() => process.exit(EXIT_OK), 3000);
+            void (async () => {
+                try {
+                    await watcher.stop();
+                    await source.close();
+                    if (drainer) {
+                        try {
+                            await drainer.flush();
+                        }
+                        catch { /* reported via onError */ }
+                        await drainer.close();
+                    }
+                    if (embedding)
+                        await embedding.close();
+                    lease.release();
+                }
+                finally {
+                    clearTimeout(watchdog);
+                    resolveWait();
+                }
+            })();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    return EXIT_OK;
+}
+export const cmdSync = { name: "sync", summary: "Reconcile a repo with its filesystem source (--watch to stay live; --server for remote)", run: (cli, a) => runSync(cli, a) };
+//# sourceMappingURL=sync.js.map

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

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

package/dist/src/cmd/update.js

@@ -0,0 +1,100 @@
+import { parseArgs } from "node:util";
+import { docsUpdate, renderOpsetPlan, isValidId } from "@omgbase/core";
+import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
+import { readContent, extractContentOpts } from "./_mutate.js";
+import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
+import { remoteCall } from "./_remote.js";
+// `omg update <target> (-f file | -)`: a polymorphic-target command (the omgbase
+// north-star — every command accepts any entity ref). A block id (b_…) replaces
+// that block's markdown (CAS-pinned, the low-level op). A doc id or path is the
+// note's docs.update: submit a complete proposed document; the engine reconciles
+// it against the current tree, preserves stable block ids for recognizably-same
+// structure, and commits the derived opset through the kernel write path. Global
+// --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.
+    const peek = extractContentOpts(args);
+    const target = peek.rest.find((a) => !a.startsWith("-"));
+    if (target && isValidId(target, "b"))
+        return cmdUpdateBlock.run(cli, args);
+    return runDocUpdate(cli, args);
+}
+async function runDocUpdate(cli, args) {
+    const content = extractContentOpts(args);
+    const { values, positionals } = parseArgs({
+        args: content.rest,
+        allowPositionals: true,
+        options: { actor: { type: "string" }, reason: { type: "string" }, plan: { type: "boolean" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "update",
+            summary: "Replace a block's markdown (b_… target), or reconcile a whole document from complete new bytes (doc id/path)",
+            usage: "update <block|doc> (-m <markdown> | -f <file> | -) [--plan] [--expect <hash>] [--reason <s>] [--actor <s>] [--dry-run]",
+            options: [
+                ["-m <markdown>", "content inline"],
+                ["-f <file>", "content from a file"],
+                ["-", "content from stdin"],
+                ["--plan", "(doc) print the reconciliation opset — identity effects + summary — and commit nothing"],
+                ["--expect <hash>", "(block) fail with stale_expectation unless the block's hash still matches"],
+                ["--reason <s>", "commit reason recorded in history"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    const doc = positionals[0];
+    if (!doc)
+        throw new CliUsageError("update requires a <doc> (id or path)");
+    const bytes = readContent(content);
+    const dryRun = Boolean(values.plan) || cli.flags.dryRun;
+    let opset;
+    let result;
+    if (cli.flags.server) {
+        // Remote: docs_update reconciles + commits server-side, returning the same
+        // { opset, result } — render unchanged.
+        const r = await remoteCall(cli, "docs_update", {
+            doc,
+            content: bytes,
+            ...(values.reason ? { reason: values.reason } : {}),
+            ...(dryRun ? { dry_run: true } : {}),
+        });
+        opset = r.opset;
+        result = r.result;
+    }
+    else {
+        const ws = cli.workspace();
+        const repo = cli.repo(ws);
+        if (!repo.rootPath)
+            throw new CliUsageError(`repo '${repo.slug}' has no filesystem source; 'update' needs a working tree`);
+        const ctx = {
+            repoId: repo.repoId,
+            rootPath: repo.rootPath,
+            ...(ws.omgbaseDir ? { omgbaseDir: ws.omgbaseDir } : {}),
+            ...(values.actor ? { actor: values.actor } : {}),
+        };
+        ({ opset, result } = docsUpdate(ws.store, ctx, doc, bytes, {
+            dryRun,
+            ...(values.reason ? { reason: values.reason } : {}),
+        }));
+    }
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify({ opset, result }));
+        return EXIT_OK;
+    }
+    if (dryRun || result === null) {
+        const s = opset.summary;
+        cli.io.err(cli.style.dim(`  plan for ${cli.style.accent(opset.target.path)}${opset.converges ? "" : " — DOES NOT CONVERGE (will not apply)"}`));
+        cli.io.out(renderOpsetPlan(opset));
+        void s;
+        return EXIT_OK;
+    }
+    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))
+        cli.io.out(id);
+    return EXIT_OK;
+}
+export const cmdUpdateDoc = { name: "update", summary: "Replace a block, or reconcile a whole document (identity-preserving)", run: (c, a) => runUpdate(c, a) };
+//# sourceMappingURL=update.js.map

package/dist/src/commands.d.ts

@@ -0,0 +1,18 @@
+import type { Cli } from "./context.js";
+import { CliUsageError } from "./output.js";
+export interface Command {
+    name: string;
+    aliases?: string[];
+    summary: string;
+    /** false → hidden from the default help listing (dev/advanced). */
+    listed?: boolean;
+    run(cli: Cli, args: string[]): number | Promise<number>;
+}
+export declare const COMMANDS: Command[];
+export declare function resolveCommand(name: string): Command | 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 declare function unknownCommandError(prog: string, name: string): CliUsageError;