omgbase 0.1.0

package/dist/src/cmd/admin.js

@@ -0,0 +1,289 @@
+import { parseArgs } from "node:util";
+import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, RepoSelectionError, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, renderHelp } from "../output.js";
+import { loadEmbedding, drainEmbeddings } from "./_embed.js";
+// admin/maintenance (11 §5.8–5.9). The live watcher moved to `omg sync --watch`.
+// ---- rebuild-index ----------------------------------------------------------
+function runRebuild(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { sections: { type: "boolean" }, edges: { type: "boolean" }, fts: { type: "boolean" }, "block-changes": { type: "boolean" }, all: { type: "boolean" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "rebuild-index",
+            summary: "Rebuild derived tables from the authoritative docs/blocks (safe any time; never touches content or history)",
+            usage: "rebuild-index [--sections|--edges|--fts|--block-changes|--all]",
+            options: [
+                ["--sections", "section spans"],
+                ["--edges", "the link graph"],
+                ["--fts", "the full-text index"],
+                ["--block-changes", "the per-block change log"],
+                ["--all", "everything (default)"],
+            ],
+        });
+    }
+    const target = values.sections ? "sections" : values.edges ? "edges" : values.fts ? "fts" : values["block-changes"] ? "block_changes" : "all";
+    const ws = cli.workspace();
+    rebuildIndex(ws.store, target);
+    cli.io.err(cli.style.dim(`  ${cli.style.ok(cli.render.g.ok)} rebuilt ${target}`));
+    return EXIT_OK;
+}
+// ---- gc ---------------------------------------------------------------------
+function runGcCmd(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: true, options: { "dry-run": { type: "boolean" }, help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "gc",
+            summary: "Mark-and-sweep unreferenced blobs and tree nodes (refuses unless gc.enabled is set in repo settings)",
+            usage: "gc [--dry-run]",
+            options: [["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"]],
+        });
+    }
+    // `--dry-run` is also a global flag (parseGlobals consumes it) — honor either spelling.
+    const dryRun = Boolean(values["dry-run"]) || cli.flags.dryRun;
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const settings = resolveSettings(ws.store, repo.repoId);
+    const enabled = Boolean(settings.gc?.enabled);
+    if (!enabled && !dryRun) {
+        throw new EngineErrorLike("target_missing", "gc is disabled; set gc.enabled=true (or use --dry-run)");
+    }
+    const result = runGc(ws.store, { enabled: enabled || dryRun });
+    if (cli.flags.mode !== "human")
+        cli.io.out(JSON.stringify(result));
+    else
+        cli.io.err(cli.style.dim(`  swept ${result.blobsSwept} blobs, ${result.treeNodesSwept} tree nodes`));
+    return EXIT_OK;
+}
+// ---- doctor -----------------------------------------------------------------
+function runDoctor(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "doctor",
+            summary: "Invariant sweep: convergence, FTS rows vs live blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
+            usage: "doctor [--json]",
+            options: [["--json", "`{ ok, checks: [{ name, ok, detail }] }`"]],
+        });
+    }
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const db = ws.store.db;
+    const checks = [];
+    const status = reposStatus(ws.store, repo.repoId);
+    checks.push({ name: "convergence", ok: status.unconverged === 0, detail: `${status.unconverged} unconverged` });
+    const ftsCount = db.prepare("SELECT count(*) c FROM blocks_fts").get().c;
+    const liveBlocks = db.prepare("SELECT count(*) c FROM blocks WHERE deleted_commit IS NULL").get().c;
+    checks.push({ name: "fts rows == live blocks", ok: ftsCount === liveBlocks, detail: `fts=${ftsCount} live=${liveBlocks}` });
+    const dangling = db.prepare("SELECT count(*) c FROM docs d WHERE d.deleted_commit IS NULL AND d.current_rev IS NOT NULL AND NOT EXISTS (SELECT 1 FROM revisions r WHERE r.rev_id = d.current_rev)").get().c;
+    checks.push({ name: "no dangling current_rev", ok: dangling === 0, detail: `${dangling} dangling` });
+    const integrity = db.pragma("integrity_check", { simple: true });
+    checks.push({ name: "sqlite integrity", ok: integrity === "ok", detail: integrity });
+    const allOk = checks.every((c) => c.ok);
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify({ ok: allOk, checks }));
+        return allOk ? EXIT_OK : EXIT_ERROR;
+    }
+    const { style, io, render } = cli;
+    for (const c of checks) {
+        const mark = c.ok ? style.ok(render.g.ok) : style.err(render.g.err);
+        io.out(`  ${mark} ${c.name}${c.detail && !c.ok ? style.dim(`  (${c.detail})`) : ""}`);
+    }
+    return allOk ? EXIT_OK : EXIT_ERROR;
+}
+function resolveConfigScope(cli, ws) {
+    if (cli.flags.repo === "")
+        return { kind: "workspace" };
+    try {
+        const repo = cli.repo(ws);
+        return { kind: "repo", repoId: repo.repoId, slug: repo.slug };
+    }
+    catch (err) {
+        // An explicit --repo <slug> that doesn't resolve is a real error. A bare
+        // (cwd-based) selection that's ambiguous or empty just means "workspace
+        // layer" — the workspace is what you mean when not clearly inside a repo.
+        if (cli.flags.repo)
+            throw err;
+        if (err instanceof RepoSelectionError)
+            return { kind: "workspace" };
+        throw err;
+    }
+}
+function runConfig(cli, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "help" || args.includes("--help")) {
+        return renderHelp(cli, {
+            name: "config",
+            summary: "Read/write settings — one schema at two layers: workspace defaults, overridable per repo",
+            usage: ["config [list]", "config get <key>", "config set <key> <value>"],
+            options: [
+                ["list", "show the effective settings (default); at repo scope, overrides are marked"],
+                ["get <key>", "print one effective value (dotted path, e.g. embedding.provider)"],
+                ["set <key> <value>", "write a value at the selected layer (true/false/null/numbers are typed)"],
+                ["--repo <slug>", "target a repo's layer"],
+                ['--repo ""', "target the workspace layer (what every repo inherits)"],
+            ],
+            notes: [`e.g. ${cli.prog} config set embedding.provider omgbase-embedder --repo ""`],
+        });
+    }
+    const ws = cli.workspace();
+    const scope = resolveConfigScope(cli, ws);
+    const label = scope.kind === "workspace" ? "workspace" : scope.slug;
+    const readLayer = () => scope.kind === "workspace" ? workspaceSettings(ws.store) : repoOwnSettings(ws.store, scope.repoId);
+    const writeLayer = (s) => scope.kind === "workspace" ? writeWorkspaceSettings(ws.store, s) : writeRepoSettings(ws.store, scope.repoId, s);
+    if (sub === "list" || sub === undefined) {
+        // At repo scope show the EFFECTIVE (merged) view with an override marker;
+        // at workspace scope the layer is the effective view.
+        if (scope.kind === "workspace") {
+            const s = workspaceSettings(ws.store);
+            if (cli.flags.mode !== "human")
+                cli.io.out(JSON.stringify(s));
+            else {
+                cli.io.err(cli.style.dim(`  workspace defaults`));
+                for (const [k, v] of Object.entries(s))
+                    cli.io.out(`  ${cli.style.accent(k)} ${cli.style.dim("=")} ${JSON.stringify(v)}`);
+            }
+            return EXIT_OK;
+        }
+        const effective = resolveSettings(ws.store, scope.repoId);
+        const own = repoOwnSettings(ws.store, scope.repoId);
+        if (cli.flags.mode !== "human") {
+            cli.io.out(JSON.stringify(effective));
+            return EXIT_OK;
+        }
+        cli.io.err(cli.style.dim(`  ${label} (effective; ${cli.render.g.diamond} = overrides workspace default)`));
+        for (const [k, v] of Object.entries(effective)) {
+            const overridden = Object.prototype.hasOwnProperty.call(own, k);
+            const mark = overridden ? cli.style.accent(cli.render.g.diamond) : " ";
+            cli.io.out(`  ${mark} ${cli.style.accent(k)} ${cli.style.dim("=")} ${JSON.stringify(v)}`);
+        }
+        return EXIT_OK;
+    }
+    if (sub === "get") {
+        const key = rest[0];
+        if (!key)
+            throw new CliUsageError("config get <key>");
+        // get returns the EFFECTIVE value (what actually takes effect for the scope).
+        const source = scope.kind === "workspace" ? workspaceSettings(ws.store) : resolveSettings(ws.store, scope.repoId);
+        const val = getPath(source, key);
+        cli.io.out(val === undefined ? "" : typeof val === "string" ? val : JSON.stringify(val));
+        return EXIT_OK;
+    }
+    if (sub === "set") {
+        const key = rest[0];
+        const raw = rest[1];
+        if (!key || raw === undefined)
+            throw new CliUsageError("config set <key> <value>");
+        const settings = readLayer();
+        setPath(settings, key, coerce(raw));
+        writeLayer(settings);
+        cli.io.err(cli.style.dim(`  set ${key} (${label})`));
+        return EXIT_OK;
+    }
+    throw new CliUsageError(`unknown config subcommand '${sub}' (get|set|list)`, `run '${cli.prog} config --help'`);
+}
+// ---- embed ------------------------------------------------------------------
+async function runEmbed(cli, args) {
+    const sub = args.find((a) => !a.startsWith("-"));
+    if (args.includes("--help") || args.includes("-h") || sub === "help") {
+        return renderHelp(cli, {
+            name: "embed",
+            summary: "The embedding queue: report the provider + what is queued, or drain it to embed now",
+            usage: ["embed [status]", "embed drain [--verbose] [--prune]"],
+            options: [
+                ["status", "(default) provider, model, and how many blocks/docs are embeddable but not yet embedded"],
+                ["drain", "embed the queued blocks now — status alone makes no progress"],
+                ["-v, --verbose", "(drain) per-batch progress"],
+                ["--prune", "(drain) afterwards delete vectors left by other models (e.g. after switching models)"],
+            ],
+            notes: [`needs embedding.provider (\`${cli.prog} config set embedding.provider omgbase-embedder --repo ""\`); without one, semantic search is simply off.`],
+        });
+    }
+    const verbose = args.includes("--verbose") || args.includes("-v");
+    const prune = args.includes("--prune");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const loaded = await loadEmbedding(ws, repo.repoId);
+    if (!loaded) {
+        // No provider configured (05 §6). Honest report; not an error.
+        const hint = 'set one with `omg config set embedding.provider <command|url>` (e.g. omgbase-embedder)';
+        if (cli.flags.mode !== "human")
+            cli.io.out(JSON.stringify({ provider: null, queued: 0 }));
+        else
+            cli.io.err(cli.style.dim(`  no embedding provider configured — ${hint}`));
+        return EXIT_OK;
+    }
+    if (sub === "drain") {
+        await loaded.close(); // drainEmbeddings connects its own provider
+        const result = await drainEmbeddings(cli, ws, repo.repoId, { verbose, prune });
+        if (cli.flags.mode !== "human")
+            cli.io.out(JSON.stringify({ provider: loaded.providerName, ...(result ?? { embedded: 0, cached: 0 }) }));
+        else if (result)
+            cli.io.err(`  ${cli.style.ok(cli.render.g.ok)} embedded ${result.embedded}, cached ${result.cached}`);
+        return EXIT_OK;
+    }
+    try {
+        const tasks = buildEmbedTasks(ws.store, repo.repoId);
+        // Queue depth = embeddable blocks whose current-context vector isn't cached.
+        const pending = loaded.worker.staleBlocks(tasks);
+        // Doc-grain queue depth = live docs whose current-content vector isn't cached.
+        const docTasks = buildDocEmbedTasks(ws.store, repo.repoId);
+        const docPending = loaded.worker.staleDocs(docTasks);
+        // Vectors left by a previous model (dead weight after a model switch).
+        const foreign = loaded.worker.foreignVectorCount();
+        // status
+        const payload = { provider: loaded.providerName, model: loaded.provider.model, dim: loaded.provider.dim, embeddable: tasks.length, queued: pending.length, docs: docTasks.length, docsQueued: docPending.length, foreignBlocks: foreign.blocks, foreignDocs: foreign.docs };
+        if (cli.flags.mode !== "human")
+            cli.io.out(JSON.stringify(payload));
+        else {
+            cli.io.out(`  provider  ${cli.style.accent(loaded.providerName)} ${cli.style.dim(`(${loaded.provider.model}, ${loaded.provider.dim}d)`)}`);
+            cli.io.out(`  embeddable ${tasks.length}   ${cli.style.dim("queued")} ${payload.queued}`);
+            cli.io.out(`  docs ${docTasks.length}   ${cli.style.dim("queued")} ${payload.docsQueued}`);
+            // `status` reports but never embeds — point the reader at the verb that does.
+            if (payload.queued > 0 || payload.docsQueued > 0)
+                cli.io.out(cli.style.dim(`  run \`omg embed drain\` to embed the ${payload.queued} queued block(s) + ${payload.docsQueued} doc(s)`));
+            // Stale vectors from another model don't affect search (queries filter by
+            // model) but waste space — nudge toward reclaiming them.
+            if (foreign.blocks > 0 || foreign.docs > 0)
+                cli.io.out(cli.style.dim(`  ${foreign.blocks} block + ${foreign.docs} doc vector(s) from other models — \`omg embed drain --prune\` to reclaim`));
+        }
+        return EXIT_OK;
+    }
+    finally {
+        await loaded.close();
+    }
+}
+// helpers ---------------------------------------------------------------------
+function getPath(obj, path) {
+    return path.split(".").reduce((o, k) => (o && typeof o === "object" ? o[k] : undefined), obj);
+}
+function setPath(obj, path, value) {
+    const parts = path.split(".");
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const k = parts[i];
+        if (typeof cur[k] !== "object" || cur[k] === null)
+            cur[k] = {};
+        cur = cur[k];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function coerce(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "null")
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}
+export const cmdRebuild = { name: "rebuild-index", summary: "Rebuild derived tables", run: (c, a) => runRebuild(c, a) };
+export const cmdGc = { name: "gc", summary: "Mark-and-sweep (flag-gated)", run: (c, a) => runGcCmd(c, a) };
+export const cmdDoctor = { name: "doctor", summary: "Invariant sweep (CI-able)", run: (c, a) => runDoctor(c, a) };
+export const cmdConfig = { name: "config", summary: "Read/write repo settings", run: (c, a) => runConfig(c, a) };
+export const cmdEmbed = { name: "embed", summary: "Embedding queue: status, or drain to embed", run: (c, a) => runEmbed(c, a) };
+//# sourceMappingURL=admin.js.map

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

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

package/dist/src/cmd/bootstrap.js

@@ -0,0 +1,252 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join, resolve, dirname, relative, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline";
+import { spawnSync } from "node:child_process";
+import { Workspace, reposStatus, workspaceSettings, writeWorkspaceSettings } from "@omgbase/core";
+import { columns as columnsLocal } from "../render.js";
+import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+// Bootstrap: init / repos (11 §5.1). Pointing a repo at a directory is
+// `omg source add <dir>` (ADR-014) — a repo owns identity; sources bring bytes.
+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();
+    }
+}
+/** Nearest ancestor (inclusive) that is a git working tree, or null. */
+function findGitRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Keep the db out of git. The workspace `.omgbase/` only matters to git when it
+ * lives inside a git working tree, so we locate the enclosing git root (if any)
+ * and offer to ignore it via the *closest* existing `.gitignore` at or above
+ * the workspace (bounded by the git root); if none exists in that span, we
+ * create one at the git root. The ignore line is written relative to whichever
+ * `.gitignore` we touch, so the pattern resolves correctly regardless of depth.
+ * Outside a git repo there is nothing to ignore — we say so and skip.
+ */
+function offerGitignore(cli, omgbaseParent, yes) {
+    const gitRoot = findGitRoot(omgbaseParent);
+    if (!gitRoot) {
+        cli.io.err(cli.style.dim("  not inside a git repo — no .gitignore needed for .omgbase/"));
+        return;
+    }
+    // Find the closest existing .gitignore from the workspace up to the git root;
+    // fall back to creating one at the git root.
+    const findGitignore = () => {
+        let dir = resolve(omgbaseParent);
+        for (;;) {
+            const gi = join(dir, ".gitignore");
+            if (existsSync(gi))
+                return { path: gi, exists: true };
+            if (dir === gitRoot)
+                return { path: join(gitRoot, ".gitignore"), exists: false };
+            const parent = dirname(dir);
+            if (parent === dir)
+                return { path: join(gitRoot, ".gitignore"), exists: false };
+            dir = parent;
+        }
+    };
+    const target = findGitignore();
+    // The pattern: `.omgbase/` at the workspace, expressed relative to the
+    // .gitignore that will hold it (so a repo-root .gitignore gets `sub/dir/.omgbase/`).
+    const rel = relative(dirname(target.path), join(omgbaseParent, ".omgbase")).split(sep).join("/");
+    const line = `${rel}/`;
+    const already = target.exists &&
+        readFileSync(target.path, "utf8")
+            .split(/\r?\n/)
+            .some((l) => l.trim() === line || l.trim() === rel);
+    if (already)
+        return;
+    const write = () => {
+        if (target.exists) {
+            const prefix = !readFileSync(target.path, "utf8").endsWith("\n") ? "\n" : "";
+            appendFileSync(target.path, `${prefix}${line}\n`);
+        }
+        else {
+            writeFileSync(target.path, `${line}\n`);
+        }
+        const shown = shortenHome(target.path);
+        cli.io.err(cli.style.dim(`  ${target.exists ? "added" : "created"} ${line} in ${shown}`));
+    };
+    // never silent (11 §5.1): --yes writes, TTY prompts, non-TTY without --yes
+    // prints a notice and skips.
+    if (yes)
+        return write();
+    const verb = target.exists ? "append to" : "create";
+    return confirmTTY(cli, `${verb} ${shortenHome(target.path)} to ignore ${line}?`).then((ok) => {
+        if (ok)
+            write();
+        else
+            cli.io.err(cli.style.dim(`  skipped .gitignore; add ${line} yourself to keep the db out of git`));
+    });
+}
+const EMBEDDER_CMD = "omgbase-embedder";
+const EMBEDDER_INSTALL = "npm i -g @omgbase/embedder";
+/** Is `cmd` runnable on PATH? Probes with a short-lived spawn (no shell). */
+function commandExists(cmd) {
+    const probe = spawnSync(process.platform === "win32" ? "where" : "which", [cmd], { stdio: "ignore" });
+    return probe.status === 0;
+}
+function setProvider(cli, ws, provider) {
+    const current = workspaceSettings(ws.store);
+    const emb = current.embedding ?? {};
+    writeWorkspaceSettings(ws.store, { ...current, embedding: { ...emb, provider } });
+    cli.io.err(cli.style.dim(`  embedding.provider = ${provider} (workspace default)`));
+}
+/**
+ * Configure the workspace's embedding provider (workspace layer, so every repo
+ * shares one vector space). Semantic search is off until a provider is set.
+ * Three paths:
+ *   • `--embedder <value>` — set it verbatim, no prompt, no PATH check (the
+ *     caller stated explicit intent; the value may be any command or URL).
+ *   • otherwise, only when `omgbase-embedder` is actually installed do we offer
+ *     it (—yes accepts, TTY prompts). We never wire a provider that isn't
+ *     there, so `omg embed` can't be left pointing at a missing command.
+ *   • not installed and no `--embedder` ⇒ we don't touch settings and return
+ *     true so init can print install/config guidance at the end.
+ * Returns whether the caller should show the "no provider" guidance footer.
+ */
+async function offerEmbedder(cli, ws, yes, embedder) {
+    const emb = workspaceSettings(ws.store).embedding;
+    if (emb?.provider)
+        return false; // already configured — leave it alone
+    if (embedder !== undefined) {
+        setProvider(cli, ws, embedder);
+        return false;
+    }
+    // Only offer the built-in embedder if it's genuinely runnable.
+    if (!commandExists(EMBEDDER_CMD))
+        return true;
+    const accept = yes || (await confirmTTY(cli, `set ${EMBEDDER_CMD} as the embedding provider (enables semantic search)?`));
+    if (!accept)
+        return true;
+    setProvider(cli, ws, EMBEDDER_CMD);
+    return false;
+}
+async function runInit(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            yes: { type: "boolean", short: "y" },
+            embedder: { type: "string" },
+            "no-embedder": { type: "boolean" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "init",
+            summary: `Create an omgbase workspace (.omgbase/ + database) in <dir> (default cwd). Ingests nothing — run \`${cli.prog} source add .\` next`,
+            usage: "init [<dir>] [--yes] [--embedder <cmd|url> | --no-embedder]",
+            options: [
+                ["-y, --yes", "accept the prompts (.gitignore entry, embedder offer) non-interactively"],
+                ["--embedder <cmd|url>", "set the embedding provider verbatim (optional; enables semantic search)"],
+                ["--no-embedder", "skip the embedder offer entirely"],
+            ],
+        });
+    }
+    const dir = resolve(positionals[0] ?? cli.cwd);
+    mkdirSync(dir, { recursive: true });
+    const omgbaseDir = join(dir, ".omgbase");
+    if (existsSync(join(omgbaseDir, "omgbase.db"))) {
+        throw new EngineErrorLike("path_taken", `workspace already initialized at ${dir}`);
+    }
+    // Create the workspace + db only. Ingesting a working tree is a separate,
+    // consent-gated step (`omg source add`) so init never silently absorbs whatever
+    // happens to live under cwd (home dir, desktop, …).
+    const ws = Workspace.open(dir);
+    let needsProviderHint = false;
+    try {
+        await offerGitignore(cli, dir, Boolean(values.yes));
+        if (!values["no-embedder"]) {
+            needsProviderHint = await offerEmbedder(cli, ws, Boolean(values.yes), values.embedder);
+        }
+    }
+    finally {
+        ws.close();
+    }
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify({ workspace: dir }));
+        return EXIT_OK;
+    }
+    const { render, style, io } = cli;
+    io.out(render.wordmark("initialized"));
+    io.out(render.rule(40));
+    io.out(`  ${style.ok(render.g.ok)} workspace  ${style.path(dir)}`);
+    io.err(style.dim(`  next: ${style.accent("omg source add .")} to point a repo at a directory of files`));
+    if (needsProviderHint) {
+        // Optional, and say so: everything except semantic ranking works without a
+        // provider. Name what the embedder is (a local model that turns blocks into
+        // vectors) so the reader can decide whether they want it at all.
+        io.err(style.dim(`  optional: semantic search is off — no embedding provider set. Full-text search, queries, and edits all work without one.`));
+        io.err(style.dim(`  to enable it, install the built-in embedder (@omgbase/embedder: a local transformers.js model that turns blocks into vectors so ${style.accent(`${cli.prog} find`)} and ${style.accent('semantic("…")')} can rank by meaning), then point the workspace at it:`));
+        io.err(style.dim(`    ${EMBEDDER_INSTALL} && ${cli.prog} config set embedding.provider ${EMBEDDER_CMD} --repo ""`));
+    }
+    return EXIT_OK;
+}
+function runRepos(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "repos",
+            summary: "List the repos in this workspace: slug, root path (from its fs source), doc/block counts",
+            usage: "repos [--ids|--json|--jsonl]",
+            options: [["--ids", "slugs only, one per line"]],
+        });
+    }
+    const ws = cli.workspace();
+    const repos = ws.repos().map((r) => ({ ...r, status: reposStatus(ws.store, r.repoId) }));
+    if (cli.flags.mode === "json") {
+        cli.io.out(JSON.stringify(repos.map((r) => ({ slug: r.slug, root: r.rootPath, docs: r.status.docs, blocks: r.status.blocks }))));
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "jsonl") {
+        for (const r of repos)
+            cli.io.out(JSON.stringify({ slug: r.slug, root: r.rootPath, docs: r.status.docs, blocks: r.status.blocks }));
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "ids") {
+        for (const r of repos)
+            cli.io.out(r.slug);
+        return EXIT_OK;
+    }
+    const { render, style, io } = cli;
+    const rows = repos.map((r) => [
+        `  ${render.g.diamond} ${style.accent(r.slug)}`,
+        style.path(r.rootPath ? shortenHome(r.rootPath) : "(no source)"),
+        style.dim(`${r.status.docs} docs`),
+        style.dim(`${r.status.blocks} blocks`),
+    ]);
+    if (rows.length === 0)
+        io.out(style.dim("  no repos attached"));
+    else
+        for (const line of columnsLocal(rows))
+            io.out(line);
+    return EXIT_OK;
+}
+// small local helpers ---------------------------------------------------------
+function shortenHome(p) {
+    const home = process.env.HOME;
+    return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+export const cmdInit = { name: "init", summary: "Create a workspace (run `source add` to ingest files)", run: (cli, a) => runInit(cli, a) };
+export const cmdRepos = { name: "repos", summary: "List repos in this workspace", run: (cli, a) => runRepos(cli, a) };
+//# sourceMappingURL=bootstrap.js.map

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

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

package/dist/src/cmd/cat.js

@@ -0,0 +1,80 @@
+import { parseArgs } from "node:util";
+import { resolveRef, nodesGet, docsRead } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { remoteCall } from "./_remote.js";
+import { expandBlockArgs } from "./_mutate.js";
+async function catOne(cli, ref, resolution) {
+    // Remote: the polymorphic `read_ref` tool classifies + reads server-side.
+    if (cli.flags.server) {
+        const r = await remoteCall(cli, "read_ref", { ref, ...(resolution !== "raw" ? { resolution } : {}) });
+        if (r.kind === "document") {
+            return { text: String(r.content ?? ""), json: { doc: r.docId, path: r.path, content: r.content }, capture: r.content };
+        }
+        return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
+    }
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const resolved = resolveRef(ws.store, repo.repoId, ref);
+    if (!resolved)
+        throw new EngineErrorLike("doc_missing", `no node ${ref}`);
+    if (resolved.kind === "document") {
+        // Cat the whole document byte-for-byte via the faithful reconstructor
+        // (leading trivia + frontmatter + each top-level block's raw + its trivia).
+        // This is the same content docs_read returns and what ingest's convergence
+        // check asserts against — never a hand-rolled block join (which dropped
+        // trivia and mangled spacing).
+        const res = docsRead(ws.store, resolved.docId);
+        if (!res)
+            throw new EngineErrorLike("doc_missing", `no document ${ref}`);
+        // shell: the bytes (a string; @_ only)
+        return { text: res.content, json: { doc: res.docId, path: res.path, content: res.content }, capture: res.content };
+    }
+    const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution });
+    if (!node)
+        throw new EngineErrorLike("block_missing", `no block ${ref}`);
+    // shell: the block (single entity)
+    return { text: node.raw ?? node.text ?? node.label ?? "", json: node, capture: node };
+}
+async function runCat(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { resolution: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "cat",
+            summary: "Content bytes of a node — exact raw bytes by default, pipe-clean (`show` is the metadata card)",
+            usage: "cat <node…|-> [--resolution raw|text|outline|skeleton|full]",
+            options: [
+                ["<node…>", "one or more refs: a doc/block id, a path, or a locator (`notes/x.md#Risks/p[2]`)"],
+                ["-", `read refs from stdin, one per line (\`${cli.prog} q … --ids | ${cli.prog} cat -\`)`],
+                ["--resolution <r>", "raw (default: exact bytes) | text | outline | skeleton | full"],
+            ],
+        });
+    }
+    const refs = expandBlockArgs(positionals);
+    if (refs.length === 0)
+        throw new CliUsageError("cat requires a <node> (or - to read refs from stdin)");
+    const resolution = (values.resolution ?? "raw");
+    const results = [];
+    for (const ref of refs)
+        results.push(await catOne(cli, ref, resolution));
+    // One ref keeps the single-entity shape (a string/object); several become a list.
+    const single = results.length === 1 ? results[0] : null;
+    cli.capture?.(single ? single.capture : results.map((r) => r.capture));
+    if (cli.flags.mode === "json") {
+        cli.io.out(JSON.stringify(single ? single.json : results.map((r) => r.json)));
+        return EXIT_OK;
+    }
+    if (cli.flags.mode === "jsonl") {
+        for (const r of results)
+            cli.io.out(JSON.stringify(r.json));
+        return EXIT_OK;
+    }
+    for (const r of results)
+        cli.io.out(r.text);
+    return EXIT_OK;
+}
+export const cmdCat = { name: "cat", summary: "Content bytes of a node (default raw)", run: (cli, a) => runCat(cli, a) };
+//# sourceMappingURL=cat.js.map

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

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