omgbase 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,55 @@
+import { EmbeddingWorker, EngineError, type EmbeddingProvider } from "@omgbase/core";
+import type { Cli } from "../context.js";
+export interface LoadedEmbedding {
+    worker: EmbeddingWorker;
+    provider: EmbeddingProvider;
+    /** the command/URL that was connected, for diagnostics */
+    providerName: string;
+    /** whether the provider is a remote endpoint (text leaves the machine) */
+    remote: boolean;
+    /** release resources (kill the spawned process). */
+    close(): Promise<void>;
+}
+/**
+ * Connect the configured embedding provider + build a worker for a repo, or
+ * null when embedding.provider is UNSET (callers surface semantic_unavailable).
+ * When a provider IS configured but can't be reached (command won't spawn,
+ * endpoint unreachable, bad handshake) this throws a loud, typed `embedder_failed`
+ * EngineError naming the provider + reason — never a silent null, so a broken
+ * embedder is never mistaken for an unconfigured one. Callers MUST call close()
+ * when done (e.g. in a finally) to release a spawned process.
+ */
+export declare function loadEmbedding(ws: ReturnType<Cli["workspace"]>, repoId: string): Promise<LoadedEmbedding | null>;
+/** Build the shared `embedder_failed` error: a configured embedder that can't be
+ *  reached is a hard, clearly-diagnosed fault (not `semantic_unavailable`, which
+ *  means "no provider configured"). */
+export declare function embedderFailed(provider: string, err: unknown): EngineError;
+export interface DrainDecision {
+    /** number of blocks that would be embedded (cache misses). */
+    pending: number;
+    /** true if the provider is a remote endpoint (block text leaves the machine). */
+    remote: boolean;
+    providerName: string;
+}
+/**
+ * Embed the repo's queued blocks now, connecting the configured provider and
+ * releasing it afterward. No-op (returns null) when no provider is configured.
+ * `verbose` prints per-batch progress in human mode. An optional `confirm` gate
+ * is consulted BEFORE any block text is handed to the provider — returning
+ * false skips the drain (also null). Callers that are themselves the explicit
+ * "drain now" intent (`omg embed drain`) omit `confirm`; callers doing it as a
+ * side effect (post-`attach`) pass one so the user consents to the egress.
+ * Shared by both so they speak the same egress notice + progress output.
+ */
+export declare function drainEmbeddings(cli: Cli, ws: ReturnType<Cli["workspace"]>, repoId: string, opts?: {
+    verbose?: boolean;
+    prune?: boolean;
+    confirm?: (d: DrainDecision) => Promise<boolean>;
+}): Promise<{
+    embedded: number;
+    cached: number;
+    pruned?: {
+        blocks: number;
+        docs: number;
+    };
+} | null>;

package/dist/src/cmd/_embed.js

@@ -0,0 +1,102 @@
+import { EmbeddingWorker, buildEmbedTasks, buildDocEmbedTasks, embeddingSettings, createExternalProvider, resolveSettings, EngineError } from "@omgbase/core";
+/**
+ * Connect the configured embedding provider + build a worker for a repo, or
+ * null when embedding.provider is UNSET (callers surface semantic_unavailable).
+ * When a provider IS configured but can't be reached (command won't spawn,
+ * endpoint unreachable, bad handshake) this throws a loud, typed `embedder_failed`
+ * EngineError naming the provider + reason — never a silent null, so a broken
+ * embedder is never mistaken for an unconfigured one. Callers MUST call close()
+ * when done (e.g. in a finally) to release a spawned process.
+ */
+export async function loadEmbedding(ws, repoId) {
+    const settings = embeddingSettings(resolveSettings(ws.store, repoId));
+    if (!settings.provider)
+        return null;
+    let ext;
+    try {
+        ext = await createExternalProvider(settings);
+    }
+    catch (err) {
+        throw embedderFailed(settings.provider, err);
+    }
+    if (!ext)
+        return null;
+    return {
+        worker: new EmbeddingWorker(ws.store, ext.provider),
+        provider: ext.provider,
+        providerName: settings.provider,
+        remote: /^https?:\/\//i.test(settings.provider),
+        close: ext.close,
+    };
+}
+/** Build the shared `embedder_failed` error: a configured embedder that can't be
+ *  reached is a hard, clearly-diagnosed fault (not `semantic_unavailable`, which
+ *  means "no provider configured"). */
+export function embedderFailed(provider, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new EngineError("embedder_failed", `embedder '${provider}' is configured but failed to start: ${reason}. Fix: put it on PATH or use an absolute path / http(s) URL for embedding.provider — or unset embedding.provider to run without semantic search.`, { data: { provider, reason } });
+}
+/**
+ * Embed the repo's queued blocks now, connecting the configured provider and
+ * releasing it afterward. No-op (returns null) when no provider is configured.
+ * `verbose` prints per-batch progress in human mode. An optional `confirm` gate
+ * is consulted BEFORE any block text is handed to the provider — returning
+ * false skips the drain (also null). Callers that are themselves the explicit
+ * "drain now" intent (`omg embed drain`) omit `confirm`; callers doing it as a
+ * side effect (post-`attach`) pass one so the user consents to the egress.
+ * Shared by both so they speak the same egress notice + progress output.
+ */
+export async function drainEmbeddings(cli, ws, repoId, opts = {}) {
+    const loaded = await loadEmbedding(ws, repoId);
+    if (!loaded)
+        return null;
+    try {
+        const tasks = buildEmbedTasks(ws.store, repoId);
+        const pending = loaded.worker.staleBlocks(tasks);
+        if (opts.confirm) {
+            const ok = await opts.confirm({ pending: pending.length, remote: loaded.remote, providerName: loaded.providerName });
+            if (!ok)
+                return null;
+        }
+        // Egress notice (05 §6): a remote provider receives block text off-machine.
+        if (loaded.remote) {
+            cli.io.err(cli.style.warn(`  embedding ${pending.length} block(s) via ${loaded.providerName} — block text is sent to this remote endpoint`));
+        }
+        else {
+            cli.io.err(cli.style.dim(`  embedding ${pending.length} block(s) via ${loaded.providerName} (local process)`));
+        }
+        const verboseHuman = Boolean(opts.verbose) && cli.flags.mode === "human";
+        const result = await loaded.worker.process(tasks, {
+            ...(verboseHuman
+                ? { onProgress: ({ embedded, total }) => cli.io.err(cli.style.dim(`    … ${embedded}/${total} embedded`)) }
+                : {}),
+        });
+        // Doc-grain vectors: embed whole documents (or pool block vectors for
+        // oversized docs) after blocks, so the pooled fallback can reuse the
+        // vectors just cached. This is also the one-time backfill path for existing
+        // repos — a fresh doc_embeddings table fills on the first drain.
+        const docTasks = buildDocEmbedTasks(ws.store, repoId);
+        const docResult = await loaded.worker.processDocs(docTasks, {
+            ...(verboseHuman
+                ? { onProgress: ({ embedded, total }) => cli.io.err(cli.style.dim(`    … ${embedded}/${total} doc(s) embedded`)) }
+                : {}),
+        });
+        // Prune AFTER the drain, so the current model's vectors are in place before
+        // we reclaim the old model's — a crash mid-way leaves the new vectors, not a
+        // half-empty cache. Only touches rows for models other than the current one.
+        let pruned;
+        if (opts.prune) {
+            pruned = loaded.worker.pruneForeignVectors();
+            if (cli.flags.mode === "human" && (pruned.blocks || pruned.docs)) {
+                cli.io.err(cli.style.dim(`  pruned ${pruned.blocks} block + ${pruned.docs} doc vector(s) from other models`));
+            }
+        }
+        // Fold doc work into the block counts so callers' "embedded/cached" report
+        // covers both grains (pooled docs count as embedded work done).
+        return { embedded: result.embedded + docResult.embedded + docResult.pooled, cached: result.cached + docResult.cached, ...(pruned ? { pruned } : {}) };
+    }
+    finally {
+        await loaded.close();
+    }
+}
+//# sourceMappingURL=_embed.js.map

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

@@ -0,0 +1,47 @@
+import { type Op } from "@omgbase/core";
+import type { Cli } from "../context.js";
+import type { RepoRow } from "@omgbase/core";
+import type { Workspace } from "@omgbase/core";
+import { EXIT_OK, EXIT_ERROR } from "../output.js";
+/** Read markdown content from -m, -f (file, or "-" = stdin), or bare stdin. */
+export declare function readContent(values: {
+    m?: string;
+    f?: string;
+}, allowStdin?: boolean): string;
+/**
+ * Pull content-bearing options out of argv before `parseArgs` sees them, so a
+ * value that starts with `-` (list/task markdown like "- [ ] x") is taken
+ * verbatim as the next token rather than mis-parsed as a flag. Handles
+ * -m/--message and -f/--file (and their `=` forms). Returns the extracted
+ * values plus the remaining argv for normal option parsing.
+ */
+export declare function extractContentOpts(args: string[]): {
+    m?: string;
+    f?: string;
+    rest: string[];
+};
+export declare function readStdin(): string;
+/** Read a list of ids from stdin (one per line), for `-` block-list args. */
+export declare function readIdsFromStdin(): string[];
+/** Expand a block-list argument list, substituting stdin ids for a bare "-". */
+export declare function expandBlockArgs(args: string[]): string[];
+export interface RunOpsOptions {
+    reason?: string;
+    actor?: string;
+}
+/**
+ * Apply a set of kernel ops as one changeset and render the outcome. Honors
+ * cli.flags.dryRun (per-file unified diffs to stdout, nothing committed) and
+ * cli.flags.mode (--json emits ApplyResult verbatim). Typed conflicts are
+ * rendered by the caller's catch via the output contract; we let apply throw.
+ */
+export declare function runOps(cli: Cli, ws: Workspace, repo: RepoRow, ops: Op[], opts?: RunOpsOptions): number;
+/**
+ * Remote peer of runOps: call the changeset-producing tool that mirrors this
+ * command (blocks_insert, tasks_complete, …) against the `--server` engine — the
+ * server resolves refs + pins CAS + applies — then render the returned
+ * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
+ * tool's dry_run so the preview comes back without committing.
+ */
+export declare function runOpsRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>): Promise<number>;
+export { EXIT_OK, EXIT_ERROR };

package/dist/src/cmd/_mutate.js

@@ -0,0 +1,211 @@
+import { readFileSync, readSync } from "node:fs";
+import { userInfo } from "node:os";
+import { apply } from "@omgbase/core";
+import { CliUsageError, EXIT_OK, EXIT_ERROR } from "../output.js";
+import { remoteCall } from "./_remote.js";
+// Shared plumbing for every write command (11 §5.6, §5.7). Sugar commands build
+// their kernel Ops, then hand them here: this sets origin.actor (human:$USER by
+// default, override --actor), runs under the writer flock (omgbaseDir), threads
+// --dry-run (validate + render diffs, commit nothing), and renders results or
+// typed conflicts uniformly.
+/** Read markdown content from -m, -f (file, or "-" = stdin), or bare stdin. */
+export function readContent(values, allowStdin = true) {
+    if (values.m !== undefined)
+        return values.m;
+    if (values.f !== undefined)
+        return values.f === "-" ? readStdin() : readFileSync(values.f, "utf8");
+    if (allowStdin)
+        return readStdin();
+    throw new CliUsageError("provide content with -m <md> or -f <file>");
+}
+/**
+ * Pull content-bearing options out of argv before `parseArgs` sees them, so a
+ * value that starts with `-` (list/task markdown like "- [ ] x") is taken
+ * verbatim as the next token rather than mis-parsed as a flag. Handles
+ * -m/--message and -f/--file (and their `=` forms). Returns the extracted
+ * values plus the remaining argv for normal option parsing.
+ */
+export function extractContentOpts(args) {
+    const rest = [];
+    let m;
+    let f;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--") {
+            rest.push(...args.slice(i));
+            break;
+        }
+        if (a === "-m" || a === "--message") {
+            m = args[++i];
+            if (m === undefined)
+                throw new CliUsageError(`${a} requires a value`);
+        }
+        else if (a.startsWith("-m=")) {
+            m = a.slice(3);
+        }
+        else if (a.startsWith("--message=")) {
+            m = a.slice("--message=".length);
+        }
+        else if (a === "-f" || a === "--file") {
+            f = args[++i];
+            if (f === undefined)
+                throw new CliUsageError(`${a} requires a value`);
+        }
+        else if (a.startsWith("-f=")) {
+            f = a.slice(3);
+        }
+        else if (a.startsWith("--file=")) {
+            f = a.slice("--file=".length);
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { ...(m !== undefined ? { m } : {}), ...(f !== undefined ? { f } : {}), rest };
+}
+export function readStdin() {
+    // Read fd 0 to EOF synchronously. `readFileSync(0)` is not enough: when stdin
+    // is a pipe whose writer hasn't produced data yet (the common `… | omg done -`
+    // case) the fd is non-blocking and the read throws EAGAIN — swallowing that as
+    // "" is why the piped idiom used to lose its input. Loop with an EAGAIN retry
+    // so we actually block for the upstream command's output.
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf, 0, buf.length, null);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EAGAIN")
+                continue; // pipe not ready yet — retry
+            if (code === "EOF")
+                break; // some platforms signal EOF this way
+            break; // fd not readable (no stdin) — treat as empty
+        }
+        if (n === 0)
+            break; // clean EOF
+        chunks.push(Buffer.from(buf.subarray(0, n)));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** Read a list of ids from stdin (one per line), for `-` block-list args. */
+export function readIdsFromStdin() {
+    return readStdin()
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Expand a block-list argument list, substituting stdin ids for a bare "-". */
+export function expandBlockArgs(args) {
+    const out = [];
+    for (const a of args) {
+        if (a === "-")
+            out.push(...readIdsFromStdin());
+        else
+            out.push(a);
+    }
+    return out;
+}
+function defaultActor() {
+    try {
+        return `human:${userInfo().username}`;
+    }
+    catch {
+        return "human:unknown";
+    }
+}
+/**
+ * Apply a set of kernel ops as one changeset and render the outcome. Honors
+ * cli.flags.dryRun (per-file unified diffs to stdout, nothing committed) and
+ * cli.flags.mode (--json emits ApplyResult verbatim). Typed conflicts are
+ * rendered by the caller's catch via the output contract; we let apply throw.
+ */
+export function runOps(cli, ws, repo, ops, opts = {}) {
+    if (ops.length === 0) {
+        cli.io.err(cli.style.dim("  nothing to do"));
+        return EXIT_OK;
+    }
+    const req = {
+        repoId: repo.repoId,
+        ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
+        ops,
+        origin: { actor: opts.actor ?? defaultActor(), ...(opts.reason ? { reason: opts.reason } : {}) },
+        omgbaseDir: ws.omgbaseDir,
+        ...(cli.flags.dryRun ? { dryRun: true } : {}),
+    };
+    const result = apply(ws.store, req);
+    return renderApply(cli, result);
+}
+/**
+ * Remote peer of runOps: call the changeset-producing tool that mirrors this
+ * command (blocks_insert, tasks_complete, …) against the `--server` engine — the
+ * server resolves refs + pins CAS + applies — then render the returned
+ * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
+ * tool's dry_run so the preview comes back without committing.
+ */
+export async function runOpsRemote(cli, tool, toolArgs) {
+    const result = await remoteCall(cli, tool, {
+        ...toolArgs,
+        ...(cli.flags.dryRun ? { dry_run: true } : {}),
+    });
+    return renderApply(cli, result);
+}
+/** Capture + render an ApplyResult (shared by the local and remote paths). */
+function renderApply(cli, result) {
+    cli.capture?.(result); // shell: ApplyResult — its minted/affected ids are the frame
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify(result));
+        return EXIT_OK;
+    }
+    return cli.flags.dryRun ? renderDryRun(cli, result) : renderCommitted(cli, result);
+}
+function renderDryRun(cli, result) {
+    const { render, style, io } = cli;
+    io.err(style.dim(`  dry run — ${Object.keys(result.diffs ?? {}).length} file(s) would change, nothing committed`));
+    for (const [path, { before, after }] of Object.entries(result.diffs ?? {})) {
+        io.out(`${style.bold(path)}`);
+        for (const line of unifiedDiff(before, after)) {
+            if (line.startsWith("+"))
+                io.out(style.ok(line));
+            else if (line.startsWith("-"))
+                io.out(style.err(line));
+            else
+                io.out(style.dim(line));
+        }
+        io.out("");
+    }
+    void render;
+    return EXIT_OK;
+}
+function renderCommitted(cli, result) {
+    const { render, style, io } = cli;
+    const g = render.g;
+    const n = result.revisions.length;
+    io.err(style.dim(`  ${style.ok(g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
+    // stdout stays useful for pipes: the ids minted/affected, one per line.
+    const ids = result.results.flatMap((r) => r.ids);
+    for (const id of ids)
+        io.out(id);
+    return EXIT_OK;
+}
+// Minimal line-based unified diff (matches the engine's diffUnified style; a
+// full Myers isn't needed for a human preview).
+function unifiedDiff(before, after) {
+    const a = before.split("\n");
+    const b = after.split("\n");
+    const out = [];
+    const max = Math.max(a.length, b.length);
+    for (let i = 0; i < max; i++) {
+        if (a[i] === b[i])
+            continue;
+        if (a[i] !== undefined)
+            out.push(`- ${a[i]}`);
+        if (b[i] !== undefined)
+            out.push(`+ ${b[i]}`);
+    }
+    return out;
+}
+export { EXIT_OK, EXIT_ERROR };
+//# sourceMappingURL=_mutate.js.map

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

@@ -0,0 +1,8 @@
+import type { Cli } from "../context.js";
+/** Call an MCP tool on the remote engine, threading the global `--repo` slug.
+ *  Returns the tool's parsed JSON result (same shape the local core fn returns,
+ *  so the command's existing renderer works unchanged). */
+export declare function remoteCall<T>(cli: Cli, tool: string, args: Record<string, unknown>): Promise<T>;
+/** Close the remote connection if one was opened (idempotent). Called after a
+ *  one-shot command and on shell exit. */
+export declare function closeRemote(): Promise<void>;

package/dist/src/cmd/_remote.js

@@ -0,0 +1,61 @@
+import { connectStdioEngine, connectHttpEngine } from "@omgbase/sync";
+import { CliUsageError } from "../output.js";
+// Remote (`--server`) mode plumbing (ADR-014). When a command runs with the
+// global `--server <cmd|url>` flag, it reaches a remote engine over MCP instead
+// of the embedded local store: it calls the MCP tool that mirrors its local
+// core function and renders the (identically-shaped) result. One connection per
+// process, opened lazily on first use and reused across a `shell` session;
+// closed via `closeRemote` at the end of a one-shot command or on shell exit.
+//
+// The flag is an http(s) URL to reach a remote server over Streamable HTTP, or
+// otherwise a command to spawn and talk to over stdio.
+let engine = null;
+/** The process's remote engine, connecting (spawning the command or opening the
+ *  HTTP transport) on first use. `--repo` is threaded into each tool call by
+ *  `remoteCall`. */
+async function remoteEngine(cli) {
+    if (engine)
+        return engine;
+    const spec = (cli.flags.server ?? "").trim();
+    if (/^https?:\/\//i.test(spec)) {
+        const headers = parseHeaders(cli.flags.headers);
+        engine = await connectHttpEngine({ url: spec, ...(Object.keys(headers).length > 0 ? { headers } : {}) });
+        return engine;
+    }
+    if (cli.flags.headers?.length)
+        throw new CliUsageError("-H/--header only applies to an http(s) --server url");
+    const argv = spec.split(/\s+/).filter(Boolean);
+    if (argv.length === 0)
+        throw new CliUsageError("--server requires a command to spawn (e.g. --server \"omg mcp -C /vault\") or an http(s) URL");
+    engine = await connectStdioEngine({ command: argv[0], args: argv.slice(1) });
+    return engine;
+}
+/** Parse repeatable `-H "Name: value"` flags into a header map. Splits on the
+ *  first colon; later values win for a repeated name. */
+function parseHeaders(raw) {
+    const headers = {};
+    for (const h of raw ?? []) {
+        const i = h.indexOf(":");
+        if (i < 1)
+            throw new CliUsageError(`invalid header ${JSON.stringify(h)} — expected "Name: value"`);
+        headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+    }
+    return headers;
+}
+/** Call an MCP tool on the remote engine, threading the global `--repo` slug.
+ *  Returns the tool's parsed JSON result (same shape the local core fn returns,
+ *  so the command's existing renderer works unchanged). */
+export async function remoteCall(cli, tool, args) {
+    const eng = await remoteEngine(cli);
+    return eng.callTool(tool, { ...args, ...(cli.flags.repo ? { repo: cli.flags.repo } : {}) });
+}
+/** Close the remote connection if one was opened (idempotent). Called after a
+ *  one-shot command and on shell exit. */
+export async function closeRemote() {
+    if (!engine)
+        return;
+    const e = engine;
+    engine = null;
+    await e.close();
+}
+//# sourceMappingURL=_remote.js.map

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

@@ -0,0 +1,13 @@
+import { type SyncSource, type Store, type RepoRow } from "@omgbase/core";
+/** The built-in filesystem adapter's registry name. */
+export declare const FS_ADAPTER = "fs";
+/** Seed the built-in `fs` adapter row (idempotent). Required before creating an
+ *  fs source (the `sources.adapter` FK is enforced). The stored command is the
+ *  globally-installed bin name; the actual spawn uses the bundled binary via
+ *  execPath (see spawnSource) so a source is never pinned to a stale path. */
+export declare function ensureFsAdapter(store: Store): void;
+/**
+ * Build the live filesystem SyncSource for a repo from its attached `fs` source
+ * (ADR-014), or null if it has none (a sourceless/headless repo).
+ */
+export declare function openRepoSource(store: Store, repo: RepoRow): Promise<SyncSource | null>;

package/dist/src/cmd/_source.js

@@ -0,0 +1,47 @@
+import { execPath } from "node:process";
+import { createExternalSource, ensureAdapter, sourcesForRepo, renderConfigFlags, } from "@omgbase/core";
+import { fsAdapterBinPath } from "@omgbase/fs-adapter";
+// Resolve a repo's live sync source for `omg watch`/`omg mcp`/`omg sync`
+// (sync-plugins, ADR-014 Stage 3). Resolution now prefers the source REGISTRY
+// (adapters/sources/attachments tables): a repo's attached filesystem source is
+// spawned from its `sources.config`. When a repo has no registered source we
+// fall back to synthesizing the fs source from its `root_path` — the pre-registry
+// behavior — so existing single-fs repos keep working unchanged until `attach`
+// starts populating the registry (Stage 5) and `root_path` is retired (Stage 6).
+/** The built-in filesystem adapter's registry name. */
+export const FS_ADAPTER = "fs";
+/** Seed the built-in `fs` adapter row (idempotent). Required before creating an
+ *  fs source (the `sources.adapter` FK is enforced). The stored command is the
+ *  globally-installed bin name; the actual spawn uses the bundled binary via
+ *  execPath (see spawnSource) so a source is never pinned to a stale path. */
+export function ensureFsAdapter(store) {
+    ensureAdapter(store, FS_ADAPTER, "omgbase-fs-adapter", []);
+}
+/** Spawn one registered source as a live SyncSource. The built-in `fs` adapter
+ *  is served by the bundled `@omgbase/fs-adapter` (execPath + bin path); other
+ *  adapters spawn their stored command. Source config renders to argv flags. */
+function spawnSource(source) {
+    const flags = renderConfigFlags(source.config);
+    if (source.adapter === FS_ADAPTER) {
+        return createExternalSource({ command: execPath, args: [fsAdapterBinPath(), ...flags], ...(hasEnv(source) ? { env: source.env } : {}) });
+    }
+    // Custom adapter: spawn its stored command (looked up by the caller).
+    throw new Error(`no launcher for adapter '${source.adapter}' (only the built-in '${FS_ADAPTER}' is wired)`);
+}
+function hasEnv(source) {
+    return Object.keys(source.env).length > 0;
+}
+/**
+ * Build the live filesystem SyncSource for a repo from its attached `fs` source
+ * (ADR-014), or null if it has none (a sourceless/headless repo).
+ */
+export async function openRepoSource(store, repo) {
+    const fsSource = sourcesForRepo(store, repo.repoId).find((s) => s.adapter === FS_ADAPTER);
+    if (!fsSource)
+        return null;
+    const root = fsSource.config.root;
+    if (typeof root !== "string" || root === "")
+        return null;
+    return spawnSource(fsSource);
+}
+//# sourceMappingURL=_source.js.map

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

@@ -0,0 +1,6 @@
+import type { Command } from "../commands.js";
+export declare const cmdRebuild: Command;
+export declare const cmdGc: Command;
+export declare const cmdDoctor: Command;
+export declare const cmdConfig: Command;
+export declare const cmdEmbed: Command;