@omgbase/git-adapter 0.0.0-stage → 0.1.0

package/dist/src/provider.js

@@ -0,0 +1,113 @@
+import { dirname, resolve } from "node:path";
+import { GitRepo, gitAvailable } from "./git.js";
+import { GitHistoryReader } from "./reader.js";
+import { GIT_PROVIDER, gitConfigFor, readGitConfig } from "./config.js";
+import { fetchRemote, pushAfterCheckpoint, pushBranch, reconcileRemote, remoteSet, remoteStatus, remoteSummary, remoteSync, remoteUnset, resolveConflict } from "./remote.js";
+import { commitSnapshot, runCheckpoint } from "./worker.js";
+import { clearGitCursor } from "./cursor.js";
+import { ensureExcluded } from "./exclude.js";
+// The git history provider (spec/store §5.12; modular-core Phase 6a): the
+// `HistoryProvider` the composition layer registers under the name `git`
+// (`registerHistoryProvider("git", gitHistoryProvider(opts))` in the CLI's entry
+// point, the MCP host and the fixture runners). One instance per `Store`; the
+// bare repository of a repository lives at `<workspace>/.omgbase/git`
+// (`config.git_dir`, relative to the workspace root — the parent of the
+// store's `omgbaseDir`).
+/** The committer identity in production. The author's name is the commit's actor when it has one. */
+export const DEFAULT_IDENTITY = { name: "omgbase", email: "omgbase@localhost" };
+/** The identity the fixture runners and the CLI under the spec seams use (spec/store §9.4 "The git provider"): pinned shas follow from it. */
+export const FIXTURE_IDENTITY = { name: "omgbase", email: "omgbase@fixture" };
+export class GitHistoryProvider {
+    store;
+    name = GIT_PROVIDER;
+    identity;
+    constructor(store, opts = {}) {
+        this.store = store;
+        this.identity = opts.identity ?? DEFAULT_IDENTITY;
+    }
+    available() {
+        if (this.store.omgbaseDir === null)
+            return { ok: false, reason: "the store has no workspace directory to keep a bare repository under" };
+        return gitAvailable();
+    }
+    /** The workspace root: the parent of `.omgbase`. */
+    root() {
+        return dirname(this.store.omgbaseDir);
+    }
+    repoOf(config) {
+        return new GitRepo(resolve(this.root(), config.git_dir));
+    }
+    context(repoId, config) {
+        return { store: this.store, repoId, git: this.repoOf(config), config, identity: this.identity };
+    }
+    reader(repoId, config) {
+        const c = readGitConfig(config);
+        return new GitHistoryReader(this.store, repoId, this.repoOf(c), c);
+    }
+    enable(repoId, commit, opts) {
+        const config = gitConfigFor({ ...(typeof opts.branch === "string" ? { branch: opts.branch } : {}), ...(opts.cadence !== undefined ? { cadence: opts.cadence } : {}) });
+        const ctx = this.context(repoId, config);
+        ctx.git.init(config.branch);
+        ensureExcluded(this.root());
+        const snap = commitSnapshot(ctx, commit.ts, commit);
+        return { config, baseline: { revisions: snap.documents, tip: snap.tip } };
+    }
+    purge(repoId, config) {
+        const c = readGitConfig(config);
+        const git = this.repoOf(c);
+        const removed = git.remove();
+        clearGitCursor(this.store.db, repoId);
+        return { removed, path: git.gitDir };
+    }
+    checkpoint(repoId, config, opts = {}) {
+        const ctx = this.context(repoId, readGitConfig(config));
+        const result = runCheckpoint(ctx, opts);
+        // `push: "on-checkpoint"` (17.6): the push follows a checkpoint that committed; its outcome rides on the receipt.
+        const push = pushAfterCheckpoint(ctx, opts.now ?? new Date().toISOString(), result.committed);
+        return push === undefined ? result : { ...result, push };
+    }
+    // ---- the remote half (17.6, Phase 6b; `remote.ts`) ----
+    remoteSummary(repoId, config) {
+        return remoteSummary(this.context(repoId, readGitConfig(config)));
+    }
+    remoteSync(repoId, config, opts) {
+        return remoteSync(this.context(repoId, readGitConfig(config)), opts.now, opts.vault);
+    }
+    /** `history remote set`: returns the config as written to the row. */
+    remoteSet(repoId, config, options, now = new Date().toISOString()) {
+        return remoteSet(this.context(repoId, readGitConfig(config)), options, now);
+    }
+    /** `history remote unset`. */
+    remoteUnset(repoId, config, now = new Date().toISOString()) {
+        return remoteUnset(this.context(repoId, readGitConfig(config)), now);
+    }
+    /** `history remote status` (local refs only). */
+    remoteStatus(repoId, config) {
+        return remoteStatus(this.context(repoId, readGitConfig(config)));
+    }
+    /** `history push`. */
+    push(repoId, config, now = new Date().toISOString()) {
+        return pushBranch(this.context(repoId, readGitConfig(config)), now);
+    }
+    /** `history fetch`: inbound content through `vault`. */
+    fetch(repoId, config, vault, now = new Date().toISOString()) {
+        return fetchRemote(this.context(repoId, readGitConfig(config)), now, vault);
+    }
+    /** `history remote resolve <path> --ours|--theirs`. */
+    resolve(repoId, config, vault, path, choice, now = new Date().toISOString()) {
+        return resolveConflict(this.context(repoId, readGitConfig(config)), now, vault, path, choice);
+    }
+    /** `history remote reconcile --rebase|--merge|--adopt|--fork`. */
+    reconcile(repoId, config, vault, mode, now = new Date().toISOString()) {
+        return reconcileRemote(this.context(repoId, readGitConfig(config)), now, vault, mode);
+    }
+    /** The bare repository of a repository (the measurement script, tests). */
+    gitRepo(config) {
+        return this.repoOf(readGitConfig(config));
+    }
+}
+/** The factory the composition layer registers: `registerHistoryProvider("git", gitHistoryProvider())`. */
+export function gitHistoryProvider(opts = {}) {
+    return (store) => new GitHistoryProvider(store, opts);
+}
+//# sourceMappingURL=provider.js.map

package/dist/src/reader.d.ts

@@ -0,0 +1,44 @@
+import type { Store, HistoryReader, RevisionQueryRow, DocsReadAtResult, DocHistoryResult, NodeChange, DiffEntry, DocDiffUnified } from "@omgbase/core";
+import { type GitRepo } from "./git.js";
+import type { GitHistoryConfig } from "./config.js";
+export declare class GitHistoryReader implements HistoryReader {
+    private readonly store;
+    private readonly repoId;
+    private readonly git;
+    private readonly config;
+    constructor(store: Store, repoId: string, git: GitRepo, config: GitHistoryConfig);
+    private parse;
+    /** Every version of one document, oldest first, with the blob's sha256 (versions whose path is not in the commit's tree — superseded within a pending span — are dropped). */
+    private versionsOf;
+    private withHashes;
+    private toVersion;
+    private toRow;
+    private headOf;
+    /** The bytes of `docId` at `rev`, or null when `rev` is a head token (or an unknown form) the commits do not name; throws the table's answer for a sha. */
+    private bytesAt;
+    readAtRevision(docId: string, revId: string): DocsReadAtResult | null;
+    blocksHistory(_blockId: string, _opts?: {
+        limit?: number;
+    }): NodeChange[];
+    diffBlocks(_docId: string, _fromRev: string, _toRev: string): DiffEntry[];
+    diffUnified(docId: string, fromRev: string, toRev: string): string;
+    docDiffUnified(docId: string, opts?: {
+        fromRev?: string;
+        toRev?: string;
+        label?: string;
+    }): DocDiffUnified;
+    docsHistory(repoId: string, opts?: {
+        pathGlob?: string;
+        doc?: string;
+        includeDeleted?: boolean;
+        limit?: number;
+    }): DocHistoryResult;
+    dispositionCounts(_commitId: string): {
+        kind: string;
+        n: number;
+    }[] | null;
+    revisionRows(repoId: string): RevisionQueryRow[];
+    docRevisionRows(docId: string): RevisionQueryRow[];
+    hasRevision(revId: string): boolean;
+    uncapturedHeads(repoId: string, since: string): number;
+}

package/dist/src/reader.js

@@ -0,0 +1,190 @@
+import { CapabilityUnavailable, EngineError, RevisionNotFound, TargetMissingRevision, inCoverage, listHistoryDocs, readCapability, referencePath, sha256, unifiedDiff, unretainedHeadVersion } from "@omgbase/core";
+import { SHA_RE } from "./git.js";
+import { parseMessage, subjectOf } from "./trailers.js";
+import { tipPosition } from "./worker.js";
+export class GitHistoryReader {
+    store;
+    repoId;
+    git;
+    config;
+    constructor(store, repoId, git, config) {
+        this.store = store;
+        this.repoId = repoId;
+        this.git = git;
+        this.config = config;
+    }
+    // ---- versions ----
+    parse(records, docId) {
+        const out = [];
+        for (const r of records) {
+            const t = parseMessage(r.message);
+            if (!t)
+                continue;
+            for (const d of t.docs) {
+                if (docId !== null && d.docId !== docId)
+                    continue;
+                if (d.head === null)
+                    continue; // a deletion mints no version
+                out.push({ sha: r.sha, trailers: t, doc: d, subject: subjectOf(r.message) });
+            }
+        }
+        return out;
+    }
+    /** Every version of one document, oldest first, with the blob's sha256 (versions whose path is not in the commit's tree — superseded within a pending span — are dropped). */
+    versionsOf(docId) {
+        if (!this.git.exists())
+            return [];
+        const versions = this.parse(this.git.log(this.config.branch, { grep: `omgbase-doc: ${docId} ` }), docId);
+        return this.withHashes(versions);
+    }
+    withHashes(versions) {
+        const blobs = this.git.blobsAt(versions.map((v) => `${v.sha}:${v.doc.path}`));
+        const out = [];
+        versions.forEach((v, i) => {
+            const b = blobs[i];
+            if (b)
+                out.push({ ...v, hash: sha256(b).toString("hex") });
+        });
+        return out;
+    }
+    toVersion(v, head) {
+        return {
+            _rev: v.doc.head,
+            _seq: v.trailers.to,
+            _commit: v.sha,
+            _ts: v.trailers.ts,
+            _origin: v.trailers.origin,
+            _actor: v.trailers.actor,
+            _hash: v.hash,
+            _is_current: v.doc.head === head,
+            _archived: false,
+            retained: true,
+        };
+    }
+    toRow(v, head) {
+        return {
+            rev_id: v.doc.head,
+            doc_id: v.doc.docId,
+            seq: v.trailers.to,
+            rendered_hash: Buffer.from(v.hash, "hex"),
+            path: v.doc.path,
+            commit_id: v.sha,
+            ts: v.trailers.ts,
+            origin: v.trailers.origin ?? "observed",
+            actor: v.trailers.actor,
+            reason: v.subject,
+            is_current: v.doc.head === head ? 1 : 0,
+            archived: 0,
+        };
+    }
+    headOf(docId) {
+        return this.store.db.prepare("SELECT head FROM docs WHERE doc_id = ?").get(docId)?.head ?? null;
+    }
+    // ---- resolving a token (spec/surface §3, the git rows of the decision table) ----
+    /** The bytes of `docId` at `rev`, or null when `rev` is a head token (or an unknown form) the commits do not name; throws the table's answer for a sha. */
+    bytesAt(docId, rev, fix) {
+        if (SHA_RE.test(rev)) {
+            if (!this.git.exists() || this.git.objectType(rev) === null)
+                throw CapabilityUnavailable.historyPruned(rev, fix);
+            if (this.git.objectType(rev) !== "commit")
+                throw new TargetMissingRevision(rev, docId);
+            const t = parseMessage(this.git.message(rev));
+            if (!t)
+                throw new TargetMissingRevision(rev, docId);
+            const coverage = readCapability(this.store.db, this.repoId, "history")?.coverage ?? [];
+            if (coverage.length > 0 && !inCoverage(coverage, t.ts))
+                throw CapabilityUnavailable.historyOutsideCoverage(rev, coverage[0].from, fix);
+            const d = t.docs.find((x) => x.docId === docId && x.head !== null);
+            if (!d)
+                throw new TargetMissingRevision(rev, docId);
+            const bytes = this.git.blobsAt([`${rev}:${d.path}`])[0];
+            if (!bytes)
+                throw CapabilityUnavailable.historyPruned(rev, fix);
+            return { path: d.path, bytes, sha: rev };
+        }
+        if (/^r_/.test(rev)) {
+            const v = this.versionsOf(docId).find((x) => x.doc.head === rev);
+            if (!v)
+                return null;
+            const bytes = this.git.blobsAt([`${v.sha}:${v.doc.path}`])[0];
+            if (!bytes)
+                return null;
+            return { path: v.doc.path, bytes, sha: v.sha };
+        }
+        return null;
+    }
+    // ---- HistoryReader ----
+    readAtRevision(docId, revId) {
+        const at = this.bytesAt(docId, revId, `docs_read ${JSON.stringify({ _id: docId })}`);
+        if (!at)
+            return null;
+        return { _id: docId, _path: referencePath(at.path), rev: revId, _raw: at.bytes.toString("utf8"), renderedHashMatch: true };
+    }
+    blocksHistory(_blockId, _opts) {
+        throw CapabilityUnavailable.historyUnsupported("git", "blocks_history", "docs_history");
+    }
+    diffBlocks(_docId, _fromRev, _toRev) {
+        throw CapabilityUnavailable.historyUnsupported("git", "docs_diff", "docs_diff_unified");
+    }
+    diffUnified(docId, fromRev, toRev) {
+        const text = (rev) => {
+            const at = this.bytesAt(docId, rev, undefined);
+            if (!at)
+                throw new RevisionNotFound(docId, rev);
+            return at.bytes.toString("utf8");
+        };
+        return unifiedDiff(text(fromRev), text(toRev));
+    }
+    docDiffUnified(docId, opts = {}) {
+        const versions = this.versionsOf(docId);
+        const to = opts.toRev ?? versions[versions.length - 1]?.sha;
+        const from = opts.fromRev ?? versions[versions.length - 2]?.sha ?? versions[versions.length - 1]?.sha;
+        if (!to || !from)
+            throw new EngineError("target_missing", `no revisions to diff for ${opts.label ?? docId}`);
+        const path = this.store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path;
+        return { _id: docId, _path: path === undefined ? "" : referencePath(path), from, to, diff: this.diffUnified(docId, from, to) };
+    }
+    docsHistory(repoId, opts = {}) {
+        const { page, truncated } = listHistoryDocs(this.store, repoId, opts);
+        const docs = page.map((d) => {
+            const versions = this.versionsOf(d.doc_id).map((v) => this.toVersion(v, d.head));
+            if (d.head !== null && !versions.some((v) => v._rev === d.head))
+                versions.push(unretainedHeadVersion(this.store, d.doc_id, d.head));
+            return { _id: d.doc_id, _path: referencePath(d.path), deleted: d.deleted_at !== null, currentRev: d.head, versions };
+        });
+        return { docs, truncated, coverage: readCapability(this.store.db, repoId, "history")?.coverage ?? [] };
+    }
+    dispositionCounts(_commitId) {
+        return null;
+    }
+    revisionRows(repoId) {
+        if (!this.git.exists())
+            return [];
+        const heads = new Map(this.store.db.prepare("SELECT doc_id, head FROM docs WHERE repo_id = ?").all(repoId).map((r) => [r.doc_id, r.head]));
+        const versions = this.withHashes(this.parse(this.git.log(this.config.branch), null).filter((v) => heads.has(v.doc.docId)));
+        return versions.map((v) => this.toRow(v, heads.get(v.doc.docId) ?? null)).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : a.rev_id < b.rev_id ? -1 : a.rev_id > b.rev_id ? 1 : 0));
+    }
+    docRevisionRows(docId) {
+        const head = this.headOf(docId);
+        return this.versionsOf(docId).map((v) => this.toRow(v, head));
+    }
+    hasRevision(revId) {
+        if (!this.git.exists())
+            return false;
+        if (SHA_RE.test(revId))
+            return this.git.objectType(revId) === "commit" && parseMessage(this.git.message(revId)) !== null;
+        if (/^r_[A-Za-z0-9_]+$/.test(revId))
+            return this.git.log(this.config.branch, { regex: `^omgbase-doc: .* ${revId}$` }).length > 0;
+        return false;
+    }
+    uncapturedHeads(repoId, since) {
+        const position = this.git.exists() ? tipPosition(this.git, this.config.branch) : null;
+        const db = this.store.db;
+        if (!position)
+            return db.prepare("SELECT count(*) c FROM docs WHERE repo_id = ? AND deleted_at IS NULL AND head IS NOT NULL AND updated_at >= ?").get(repoId, since).c;
+        return db
+            .prepare("SELECT count(*) c FROM docs d WHERE d.repo_id = ? AND d.deleted_at IS NULL AND d.head IS NOT NULL AND d.updated_at >= ? AND EXISTS (SELECT 1 FROM feed_entries e WHERE e.repo_id = d.repo_id AND e.head = d.head AND e.seq > ?)")
+            .get(repoId, since, position.seq).c;
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/src/remote.d.ts

@@ -0,0 +1,113 @@
+import type { HistoryPushResult, HistoryRemoteState, HistoryRemoteSummary, HistoryVaultSink, HistoryRemoteSyncResult } from "@omgbase/core";
+import { type GitHistoryConfig, type GitRemoteOptions } from "./config.js";
+import { type WorkerContext } from "./worker.js";
+export declare const GIT_REMOTE_DIVERGED_ALERT = "git_remote_diverged";
+export declare const GIT_MERGE_CONFLICT_ALERT = "git_merge_conflict";
+export declare const GIT_REMOTE_FORKED_ALERT = "git_remote_forked";
+export type FetchState = "nothing" | "fast-forward" | "merged" | "conflict" | "diverged";
+export type ReconcileMode = "rebase" | "merge" | "adopt" | "fork";
+export type ResolveChoice = "ours" | "theirs";
+export interface RemoteStatus {
+    remote: string;
+    branch: string;
+    local_tip: string | null;
+    remote_tip: string | null;
+    pushed_through: number | null;
+    state: HistoryRemoteState;
+}
+export interface FetchResult {
+    state: FetchState;
+    /** the remote's tip after the fetch (null when the remote branch does not exist yet) */
+    remote_tip: string | null;
+    /** `diverged` alone: the tip we last knew the remote at (null for unrelated histories) */
+    old_remote_tip?: string | null;
+    /** our branch tip after the fetch */
+    tip: string | null;
+    /** the paths written into the vault from the remote (sidecars included), in path order */
+    applied: string[];
+    /** the conflicting paths (a sidecar beside each) */
+    conflicts: string[];
+}
+export interface ResolveResult {
+    path: string;
+    choice: ResolveChoice;
+    remaining: string[];
+    /** the merge commit written when the last conflict was settled, else null */
+    merged: string | null;
+    tip: string | null;
+}
+export interface ReconcileResult {
+    mode: ReconcileMode;
+    tip: string | null;
+    /** the previous tip, kept on `refs/omgbase/backup/<ts>` (rebase, merge, adopt) */
+    backup: string | null;
+    /** `--rebase`: the commits rewritten; `--merge`: 1 when the merge commit was written, 0 while conflicts stand */
+    rewritten: number;
+    /** `--fork`: the branch pushed */
+    fork: string | null;
+    applied: string[];
+    conflicts: string[];
+}
+/** `<ts>` as a ref/branch segment: `20260927T000000Z`. */
+export declare function tsSegment(ts: string): string;
+/** The sidecar beside `path` holding the OTHER side's version: `<stem>.remote-<short>.md` / `<stem>.local-<short>.md` (a path without `.md` keeps its name and gains the suffix). */
+export declare function sidecarPath(path: string, side: "remote" | "local", sha: string): string;
+/**
+ * Are push and fetch PAUSED? While the remote stands rewritten
+ * (`git_remote_diverged` carrying `old_remote_tip`) or forked, nothing moves
+ * either way until a remediation; a plain rejected push (no `old_remote_tip`)
+ * pauses nothing — `history fetch` merges the remote's commits and clears it.
+ */
+export declare function pausedBy(ctx: WorkerContext): {
+    code: string;
+    detail: Record<string, unknown>;
+} | null;
+export declare function rejectedMessage(remote: string, branch: string, remoteTip: string | null, localTip: string | null): string;
+export declare function rewrittenMessage(remote: string, branch: string, remoteTip: string | null, oldRemoteTip: string | null): string;
+export declare function conflictMessage(remote: string, branch: string, remoteTip: string | null, paths: string[]): string;
+export declare function forkedMessage(remote: string, branch: string, fork: string): string;
+/** `history remote set`: the remote in the bare repository and the row's `remote` member; returns the config as written. */
+export declare function remoteSet(ctx: WorkerContext, opts: GitRemoteOptions, now: string): GitHistoryConfig;
+/** `history remote unset`: the remote, its tracking and bookkeeping refs, the alerts about it and the row's binding leave; the pushed record is cleared. */
+export declare function remoteUnset(ctx: WorkerContext, now: string): GitHistoryConfig;
+/** `history remote status` (local refs only — no network): where the two sides stand. */
+export declare function remoteStatus(ctx: WorkerContext): RemoteStatus;
+/** `version.capabilities.history.remote`. */
+export declare function remoteSummary(ctx: WorkerContext): HistoryRemoteSummary | null;
+/**
+ * `history push`: the content branch (`refs/heads/<b>:refs/heads/<rb>`) and,
+ * when it exists, the ids ref — never `--force`. A rejected push raises
+ * `git_remote_diverged` (warning; `{ remote, branch, local_tip, remote_tip }`)
+ * and throws it; the ids ref's rejection alone is reported (`ids:
+ * "rejected"`) — two engines writing one remote's identities is 6c's.
+ */
+export declare function pushBranch(ctx: WorkerContext, now: string): HistoryPushResult & {
+    ids: "pushed" | "rejected" | "none";
+};
+/**
+ * `history fetch` (spec/store §5.12 "Fetch"): fetch `<name>/<rb>` into the
+ * tracking ref (and the remote's ids ref when it has one), then — nothing new:
+ * `nothing`; the remote rewritten (its tip does not descend from the tip we
+ * last knew, or unrelated histories): `diverged` — the alert, the old tip
+ * kept, push and fetch paused; we are behind: the remote's tree changes into
+ * the vault through the sink, then our branch fast-forwarded; both moved: the
+ * three-way merge — clean: the remote's changes into the vault and one merge
+ * commit; conflicts: the remote's versions beside ours, the alert, no merge
+ * commit until `resolve`.
+ */
+export declare function fetchRemote(ctx: WorkerContext, now: string, vault: HistoryVaultSink): FetchResult;
+/**
+ * `history remote resolve <path> --ours|--theirs`: the sidecar leaves the
+ * vault (`--theirs` first writes the remote's version over ours); the path
+ * leaves the alert; when none remains the pending merge — if one waits — is
+ * committed over the resolution the worker just checkpointed.
+ */
+export declare function resolveConflict(ctx: WorkerContext, now: string, vault: HistoryVaultSink, path: string, choice: ResolveChoice): ResolveResult;
+/** `history remote reconcile --rebase|--merge|--adopt|--fork`. */
+export declare function reconcileRemote(ctx: WorkerContext, now: string, vault: HistoryVaultSink, mode: ReconcileMode): ReconcileResult;
+/** `remoteSync` of the provider seam (spec/sync §4.3 steps 7–8): push on `periodic`, fetch on `periodic`; both skipped while paused or while a merge waits. */
+export declare function remoteSync(ctx: WorkerContext, now: string, vault: HistoryVaultSink): HistoryRemoteSyncResult | null;
+/** `push: "on-checkpoint"`: after a checkpoint that committed, the push — its error reported on the receipt, never thrown (the checkpoint stands). */
+export declare function pushAfterCheckpoint(ctx: WorkerContext, now: string, committed: number): HistoryPushResult | {
+    error: string;
+} | undefined;