git-fs-s3 0.4.0 → 0.6.0

package/dist/types/git-layout.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Typed classification of paths inside a git directory, so callers can
+ * reason about "a ref", "a loose object" or "the pack listing" as values
+ * instead of matching path strings against patterns.
+ *
+ * Edge-compatible: no node: imports.
+ */
+import { type PackFileName } from "./pack-files.js";
+/** What a gitdir-relative path refers to. Listing prefixes end in `/`. */
+export type GitdirEntry = {
+    readonly kind: "head";
+} | {
+    readonly kind: "config";
+}
+/** A ref file (`refs/heads/main`) or a refs listing (`refs/heads/`). */
+ | {
+    readonly kind: "refs";
+    readonly path: string;
+}
+/** The `objects/` listing. */
+ | {
+    readonly kind: "objects-dir";
+}
+/** The `objects/pack/` listing. */
+ | {
+    readonly kind: "pack-dir";
+} | {
+    readonly kind: "pack-file";
+    readonly file: PackFileName;
+} | {
+    readonly kind: "loose-object";
+    readonly oid: string;
+} | {
+    readonly kind: "other";
+};
+/** Classify a path relative to a gitdir (no leading slash). */
+export declare function classifyGitdirPath(path: string): GitdirEntry;
+/**
+ * Whether reads of this entry can change between pushes: refs, `HEAD`, and
+ * the object/pack listings. Everything else is content-addressed (objects)
+ * or written once (config, a given pack file name).
+ */
+export declare function isMutableGitdirEntry(entry: GitdirEntry): boolean;
+/**
+ * A loose-object path anywhere in the fs, split into its gitdir and oid —
+ * for callers that don't know where the gitdir boundary is: a loose object
+ * is always `<gitdir>/objects/<2 hex>/<38 hex>`.
+ */
+export declare function parseLooseObjectPath(path: string): {
+    readonly gitdir: string;
+    readonly oid: string;
+} | null;

package/dist/types/http/index.d.ts

@@ -0,0 +1,7 @@
+export { type GitService, handleInfoRefs, type InfoRefsOptions, listAllRefs, } from "./info-refs.js";
+export { FLUSH, parsePktLines, pktLine, pktLineBuffer, sideBandPackfile, } from "./pkt-line.js";
+export { collectReachableOids, type ReachabilityResult, } from "./reachability.js";
+export { type ApplyReceivePackOptions, applyReceivePack, applyRefUpdates, ensureRepoInitialized, indexIncomingPack, parseReceivePackBody, type RefUpdateCommand, type RefUpdateResult, receivePackResponse, } from "./receive-pack.js";
+export { REPACK_PACK_COUNT_THRESHOLD, type RepackOptions, repackRepository, } from "./repack.js";
+export { type GitHttpResult, type HttpHooks, type RawFsPromises, rawFs, } from "./types.js";
+export { handleUploadPack, type UploadPackOptions } from "./upload-pack.js";

package/dist/types/http/info-refs.d.ts

@@ -0,0 +1,28 @@
+import type { Repo } from "../ops/types.js";
+import { type GitHttpResult, type HttpHooks } from "./types.js";
+export type GitService = "git-upload-pack" | "git-receive-pack";
+/** All refs with resolved oids, plus the symref HEAD should advertise. */
+export declare function listAllRefs(repo: Repo, defaultBranch: string): Promise<{
+    refs: {
+        name: string;
+        oid: string;
+    }[];
+    headSymref: string;
+}>;
+export interface InfoRefsOptions {
+    service: GitService;
+    /** Advertised as HEAD when HEAD itself doesn't name an existing branch. */
+    defaultBranch: string;
+    /** Advertised in the agent capability. Default "git-fs-s3". */
+    agent?: string;
+}
+/**
+ * `GET …/info/refs?service=…` — the ref advertisement. Authentication and
+ * authorization are the caller's job before invoking this.
+ *
+ * Capabilities advertised match what the sibling handlers implement:
+ * side-band-64k (honored by handleUploadPack's response framing — clients
+ * like isomorphic-git unconditionally expect it), tip/reachable sha1 wants,
+ * delete-refs and report-status for pushes.
+ */
+export declare function handleInfoRefs(repo: Repo, options: InfoRefsOptions, hooks?: HttpHooks): Promise<GitHttpResult>;

package/dist/types/http/pack-reuse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Build a packfile by copying already-compressed entries out of existing
+ * packs ("pack reuse"), instead of inflating and re-deflating every object.
+ *
+ * Entries keep their stored form, deltas included, so the output is as
+ * compact as the packs it came from. `OFS_DELTA` entries are rewritten as
+ * `REF_DELTA` (base named by oid), since offsets don't survive the move into
+ * a new pack; delta bases are always included and written before the deltas
+ * that use them. Formats: gitformat-pack(5).
+ *
+ * Edge-compatible: Web Crypto SHA-1 and Uint8Array only.
+ */
+import type { Repo } from "../ops/types.js";
+/** An object's position in a pack, as listed by its `.idx`. */
+export interface PackIndexEntry {
+    readonly oid: string;
+    readonly offset: number;
+}
+/** Entries of a version-2 `.idx`; `null` for any other format. */
+export declare function readPackIndex(idx: Uint8Array): PackIndexEntry[] | null;
+/**
+ * A pack holding at least `oids`, built from stored entries, or `null` when
+ * any of them (or a delta base they need) isn't in a readable pack — e.g. a
+ * loose object — so the caller should build the pack another way.
+ */
+export declare function buildPackFromExistingPacks(repo: Repo, oids: readonly string[]): Promise<Uint8Array | null>;

package/dist/types/http/pkt-line.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Git pkt-line framing (smart HTTP protocol wire format).
+ *
+ * Edge-compatible: uses Uint8Array instead of Buffer.
+ */
+/** Flush packet: exactly four zero bytes. */
+export declare const FLUSH: Uint8Array<ArrayBuffer>;
+/** Frame a UTF-8 string as one pkt-line. */
+export declare function pktLine(data: string): Uint8Array<ArrayBuffer>;
+/** Frame raw bytes as one pkt-line. */
+export declare function pktLineBuffer(body: Uint8Array): Uint8Array<ArrayBuffer>;
+/** Decode pkt-lines to strings; `null` marks a flush-pkt. Stops on garbage. */
+export declare function parsePktLines(buf: Uint8Array): Array<string | null>;
+export declare function sideBandPackfile(packData: Uint8Array): Uint8Array<ArrayBuffer>;

package/dist/types/http/reachability.d.ts

@@ -0,0 +1,36 @@
+import type { Repo } from "../ops/types.js";
+import type { HttpHooks } from "./types.js";
+export interface ReachabilityResult {
+    oids: string[];
+    /**
+     * False if any object in the graph couldn't be read — repack uses this
+     * (not a raw object-count comparison) to decide whether it's safe to
+     * delete old packs: counts alone can't distinguish "everything read fine"
+     * from "some objects silently failed".
+     */
+    complete: boolean;
+}
+/**
+ * Walk the object graph from `startOids`, returning every reachable oid.
+ * Concurrent traversal paths are deduplicated promise-per-oid; a missing
+ * object is retried once, then reported through `hooks.onWarn` and
+ * reflected in `complete: false`.
+ *
+ * `haveOids` bounds the walk: any oid in this set is assumed already
+ * verified (it was reachable from a ref that existed before this call) and
+ * is recorded in `seen` without being read or descended into. Without a
+ * boundary, every call re-walks the *entire* history from scratch — for
+ * receive-pack validation (see receive-pack.ts) that means every push pays
+ * for reading every object in the repo, not just the ones it introduced,
+ * and one transient read failure anywhere in that whole history rejects an
+ * otherwise-valid push.
+ *
+ * Commits, trees and tags are read once each (parsed). Blobs have no
+ * children, so `verifyBlobs: false` records a blob from its tree entry
+ * without reading (and inflating) it — for callers that read every blob
+ * themselves afterwards anyway, like upload-pack's `packObjects`. Leave it
+ * true wherever the walk *is* the existence check (receive-pack, repack).
+ */
+export declare function collectReachableOids(repo: Repo, startOids: string[], hooks?: HttpHooks, haveOids?: ReadonlySet<string> | readonly string[], options?: {
+    verifyBlobs?: boolean;
+}): Promise<ReachabilityResult>;

package/dist/types/http/receive-pack.d.ts

@@ -0,0 +1,55 @@
+import type { Repo } from "../ops/types.js";
+import { type RepackOptions } from "./repack.js";
+import { type GitHttpResult, type HttpHooks } from "./types.js";
+export interface RefUpdateCommand {
+    oldOid: string;
+    newOid: string;
+    refName: string;
+}
+export interface RefUpdateResult {
+    refName: string;
+    ok: boolean;
+    reason?: string;
+}
+/** Split a receive-pack body: pkt-line ref commands, flush, then raw PACK. */
+export declare function parseReceivePackBody(body: Uint8Array): {
+    refUpdates: RefUpdateCommand[];
+    packData: Uint8Array;
+};
+/** Initialize the repo when its HEAD doesn't exist yet (first push). */
+export declare function ensureRepoInitialized(repo: Repo, defaultBranch: string): Promise<void>;
+/** Write the incoming PACK into objects/pack/ and index it. */
+export declare function indexIncomingPack(repo: Repo, packData: Uint8Array, hooks?: HttpHooks): Promise<string[]>;
+/**
+ * Apply ref updates, enforcing compare-and-swap against each command's
+ * claimed oldOid. Every client-supplied refName is validated before any
+ * filesystem call reads or writes through it.
+ */
+export declare function applyRefUpdates(repo: Repo, refUpdates: RefUpdateCommand[], hooks?: HttpHooks): Promise<RefUpdateResult[]>;
+/** The report-status response body for a set of ref-update results. */
+export declare function receivePackResponse(results: RefUpdateResult[]): GitHttpResult;
+export interface ApplyReceivePackOptions {
+    /** HEAD's branch when a push initializes an empty repository. */
+    defaultBranch: string;
+    /**
+     * Repack tuning, or `false` to skip repacking entirely. The returned
+     * `stalePackPaths` are gitdir-relative pack files the repack deleted from
+     * this repo — after syncing to any secondary storage, delete them there
+     * too.
+     */
+    repack?: RepackOptions | false;
+}
+/**
+ * The storage half of a push against `repo`: initialize if needed, index the
+ * incoming pack, CAS-apply ref updates, then repack when enough packs have
+ * accumulated. Serialize concurrent pushes to the same repo externally (a
+ * per-repo lock); build the HTTP response afterwards with
+ * {@link receivePackResponse}.
+ */
+export declare function applyReceivePack(repo: Repo, parsed: {
+    refUpdates: RefUpdateCommand[];
+    packData: Uint8Array;
+}, options: ApplyReceivePackOptions, hooks?: HttpHooks): Promise<{
+    results: RefUpdateResult[];
+    stalePackPaths: string[];
+}>;

package/dist/types/http/repack.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pack consolidation: merge all packs into one, reusing stored (possibly
+ * deltified) entries when every object is packed.
+ *
+ * Edge-compatible: uses Web Crypto (SHA-1), CompressionStream (deflate),
+ * and Uint8Array throughout — no node:crypto, node:zlib, or Buffer.
+ */
+import type { Repo } from "../ops/types.js";
+import { type HttpHooks } from "./types.js";
+/**
+ * Default repack threshold. Consolidating is O(total repo object count) —
+ * so paying it on every push makes push latency grow with repo size forever.
+ */
+export declare const REPACK_PACK_COUNT_THRESHOLD = 4;
+export interface RepackOptions {
+    /** Skip repacking below this many accumulated packs. Default 4. */
+    threshold?: number;
+}
+/**
+ * Consolidate all pack files into one, returning the gitdir-relative paths
+ * of the old .pack/.idx files it removed — after syncing the new pack to any
+ * secondary storage, delete those same paths there too.
+ */
+export declare function repackRepository(repo: Repo, options?: RepackOptions, hooks?: HttpHooks): Promise<string[]>;

package/dist/types/http/types.d.ts

@@ -0,0 +1,40 @@
+import type { Repo } from "../ops/types.js";
+/**
+ * Transport-agnostic HTTP response the handlers produce.
+ *
+ * `body` is pinned to `Uint8Array<ArrayBuffer>` (not the bare `Uint8Array`,
+ * whose default type argument isn't consistent across TypeScript versions)
+ * so it's always assignable to Fetch API `BodyInit` regardless of which
+ * TypeScript/lib version a consumer compiles against — every producer here
+ * (`concat`, `pktLine`, `TextEncoder.encode`) is ArrayBuffer-backed already.
+ */
+export interface GitHttpResult {
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array<ArrayBuffer>;
+}
+/** Optional instrumentation hooks shared by the /http handlers. */
+export interface HttpHooks {
+    /** Wrap a timed sub-step. Default: run directly. */
+    step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+    /** Non-fatal problem sink (missing objects, failed repacks). */
+    onWarn?: (message: string, error?: unknown) => void;
+}
+export declare const runStep: <T>(hooks: HttpHooks | undefined, label: string, fn: () => Promise<T>) => Promise<T>;
+/**
+ * The raw promise-fs surface some /http paths need beyond isomorphic-git's
+ * plumbing (writing an incoming pack file, listing/deleting pack files).
+ * Both `node:fs` and this package's `GitFs` satisfy it via `.promises`.
+ */
+export interface RawFsPromises {
+    readFile(path: string): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<unknown>;
+    stat(path: string): Promise<unknown>;
+}
+/** Duck-type the `.promises` surface off a repo's fs. */
+export declare function rawFs(repo: Repo): RawFsPromises;

package/dist/types/http/upload-pack.d.ts

@@ -0,0 +1,21 @@
+import type { Repo } from "../ops/types.js";
+import { type GitHttpResult, type HttpHooks } from "./types.js";
+export interface UploadPackOptions {
+    /**
+     * Called once before the reachability walk — wire loose-object detection
+     * (`GitFs.detectLooseObjects`) here so a fully packed repo's walk doesn't
+     * pay a doomed loose-object probe per object.
+     */
+    beforeWalk?: () => Promise<void>;
+}
+/**
+ * `POST …/git-upload-pack` — serve a clone/fetch. Authorization is the
+ * caller's job. Negotiation is client-driven (no multi_ack advertised):
+ * "have" batches without "done" get a bare NAK; the final batch gets the
+ * packfile, side-band-64k framed.
+ *
+ * Fast path: a fresh clone (no haves) of a repo consolidated down to a
+ * single pack serves that pack's bytes directly — skipping the O(objects)
+ * traversal + repack entirely.
+ */
+export declare function handleUploadPack(repo: Repo, body: Uint8Array, options?: UploadPackOptions, hooks?: HttpHooks): Promise<GitHttpResult>;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export { type CachedObjectStore, type CacheOptions, createCachedStore, } from "./cache.js";
+export { concat, decodeAscii, decodeUtf8, deflate, encodeUtf8, fromHex, hasNullByte, readBlobContent, sha1, toBase64, toHex, } from "./edge-utils.js";
+export { FsError } from "./errors.js";
+export { formatErrorResponse, GitAuthenticationError, GitAuthorizationError, GitConflictError, GitError, GitInvalidRequestError, GitObjectNotFoundError, GitPathNotFoundError, GitProtocolError, GitRateLimitError, GitRefNotFoundError, GitRepositoryNotFoundError, type MergeConflictDetail, } from "./git-errors.js";
+export { createGitFs, type GitFs } from "./git-fs.js";
+export { classifyGitdirPath, type GitdirEntry, isMutableGitdirEntry, parseLooseObjectPath, } from "./git-layout.js";
+export { PACK_FILE_KINDS, type PackFileKind, type PackFileName, packFileName, parsePackDirectory, parsePackFileName, READABLE_PACK_FILE_KINDS, } from "./pack-files.js";
+export { isFullSha, isSafeBranchName, isSafeFullRefName, isSafeRefName, isSafeRepoPath, qualifyBranchRef, } from "./refs.js";
+export { CircuitOpenError, createRetryStore, type RetryOptions, } from "./retry.js";
+export { MemoryObjectStore } from "./stores/memory.js";
+export type { GitdirFacts, GitFsClient, GitFsOptions, ListOptions, ListResult, ObjectStat, ObjectStore, Stat, } from "./types.js";

package/dist/types/ops/branch.d.ts

@@ -0,0 +1,38 @@
+import type { Repo } from "./types.js";
+export interface Branch {
+    name: string;
+    commit: string;
+    isDefault: boolean;
+}
+/**
+ * Defense in depth for every branch-name argument below: `git.deleteBranch`
+ * and raw resolveRef/writeRef reads don't validate ref names internally the
+ * way `git.branch` does (see refs.ts) — guard at the point the primitives are
+ * actually called, not just at an API boundary far above.
+ */
+export declare function assertSafeBranchName(name: string): void;
+/**
+ * Loose ref names under `dir` (e.g. `refs/tags`) in one recursive listing,
+ * or `null` when the fs can't list recursively (use isomorphic-git's walk).
+ */
+export declare function listLooseRefNames(repo: Repo, dir: "refs/heads" | "refs/tags"): Promise<string[] | null>;
+/**
+ * Resolve a fully-qualified ref's oid with one read instead of isomorphic-
+ * git's own `resolveRef`, which does a stat *then* a read for a loose ref
+ * (two round trips against object storage) — wasteful specifically here,
+ * where the caller already knows the ref exists (it came from a directory
+ * listing moments earlier). Reads the loose file directly and falls back to
+ * `git.resolveRef` only when that doesn't pan out (packed-refs, or anything
+ * else the plain-loose-file assumption doesn't cover), so correctness for
+ * those cases is unchanged — this only removes the redundant round trip on
+ * the common path.
+ */
+export declare function resolveLooseRefFast(repo: Repo, ref: string): Promise<string>;
+/** All branches with their tip commits; [] for an empty repository. */
+export declare function listBranches(repo: Repo): Promise<Branch[]>;
+/** Create `name` pointing at the tip of `startPoint` (no checkout). */
+export declare function createBranchFrom(repo: Repo, name: string, startPoint: string): Promise<void>;
+/** Delete a branch ref (validated — deleteBranch has no internal ref check). */
+export declare function deleteBranchByName(repo: Repo, name: string): Promise<void>;
+/** Throws (NotFoundError) unless the branch resolves. */
+export declare function assertBranchExists(repo: Repo, name: string): Promise<void>;

package/dist/types/ops/commit.d.ts

@@ -0,0 +1,45 @@
+import type { Repo } from "./types.js";
+export interface CommitAuthor {
+    name: string;
+    email: string;
+    timestamp: number;
+    timezoneOffset: number;
+}
+/** An author stamped with the current time. */
+export declare function authorNow(name: string, email: string): CommitAuthor;
+/**
+ * Write a commit directly to a bare repository — no worktree, no checkout.
+ * `buildTree` receives the parent commit's tree oid (undefined on an empty
+ * repo / unborn branch) and returns the new root tree oid; this function
+ * writes the commit object and force-updates `refs/heads/<branch>`.
+ *
+ * Serialize concurrent writers externally (a per-repo lock): the
+ * resolve-ref → write-ref sequence is not atomic on object storage.
+ */
+export declare function writeCommitToBare(repo: Repo, options: {
+    branch: string;
+    message: string;
+    author: CommitAuthor;
+    buildTree: (parentTreeOid: string | undefined) => Promise<string>;
+}): Promise<string>;
+/**
+ * Commit a set of files onto a branch, straight to the bare repo. Each blob
+ * is written to its own content-addressed key — no shared state between
+ * files, so they're written in parallel.
+ */
+export declare function commitFilesToBare(repo: Repo, options: {
+    branch: string;
+    message: string;
+    author: CommitAuthor;
+    files: Array<{
+        path: string;
+        content: string | Uint8Array;
+    }>;
+}): Promise<string>;
+/** Commit the removal of one file from a branch, straight to the bare repo. */
+export declare function deleteFileFromBare(repo: Repo, options: {
+    branch: string;
+    filePath: string;
+    message: string;
+    author: CommitAuthor;
+}): Promise<string>;

package/dist/types/ops/diff.d.ts

@@ -0,0 +1,24 @@
+import type { Repo } from "./types.js";
+export interface DiffFile {
+    path: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+    additions: number;
+    deletions: number;
+    patch: string;
+    oldPath?: string;
+    isBinary?: boolean;
+    oldContent?: string;
+    newContent?: string;
+    oldSize?: number;
+    newSize?: number;
+}
+export interface DiffResult {
+    files: DiffFile[];
+    totalAdditions: number;
+    totalDeletions: number;
+    totalFiles: number;
+}
+/** The diff a single commit introduced (against its first parent). */
+export declare function getCommitDiff(repo: Repo, commitSha: string): Promise<DiffResult>;
+/** The diff between two refs (base -> compare). */
+export declare function getDiffBetweenRefs(repo: Repo, baseRef: string, compareRef: string): Promise<DiffResult>;

package/dist/types/ops/file-history.d.ts

@@ -0,0 +1,41 @@
+import type { OpsHooks, Repo } from "./types.js";
+export interface FileHistoryEntry {
+    sha: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    createdAt: string;
+}
+export interface FileHistoryResult {
+    entries: FileHistoryEntry[];
+    /**
+     * True when the walk hit its depth budget (or the requested `limit`)
+     * before exhausting the branch's full commit chain — there may be older
+     * commits touching this file that a deeper walk would surface.
+     */
+    truncated: boolean;
+}
+/**
+ * Default walk bound for a caller that actually wants deep history (a file's
+ * "History" tab). Walking the full chain is round-trip-bound on object
+ * storage, so cap how far back a single request will look.
+ */
+export declare const HISTORY_WALK_DEPTH = 400;
+/**
+ * Much shallower default for a "latest commit touching this file" banner that
+ * only displays `entries[0]` — trades "always finds the true last-touching
+ * commit" for "finds it if it's reasonably recent", the right call for a
+ * banner with a full History view a click away.
+ */
+export declare const BANNER_WALK_DEPTH = 60;
+/**
+ * All commits (newest first) that changed a single file's blob oid, walking
+ * the first-parent chain — same approach as getLastCommitsForTree but for one
+ * path and collecting every match instead of stopping at the first.
+ */
+export declare function getFileHistory(repo: Repo, options: {
+    ref: string;
+    filePath: string;
+    limit?: number;
+    maxDepth?: number;
+}, hooks?: OpsHooks): Promise<FileHistoryResult>;

package/dist/types/ops/history.d.ts

@@ -0,0 +1,86 @@
+import { type TreeEntry } from "./tree.js";
+import { type OpsHooks, type Repo } from "./types.js";
+export interface CommitInfo {
+    oid: string;
+    commit: {
+        message: string;
+        tree: string;
+        parent: string[];
+        author: {
+            name: string;
+            email: string;
+            timestamp: number;
+            timezoneOffset: number;
+        };
+        committer: {
+            name: string;
+            email: string;
+            timestamp: number;
+            timezoneOffset: number;
+        };
+    };
+    payload: string;
+}
+/**
+ * Resolve a branch name / full ref / sha to its commit. The ref not
+ * resolving (unborn branch, genuinely empty repo) and the ref resolving but
+ * its commit object being unreadable (storage inconsistency — see
+ * `wrapMissingObject` above) are different failures with different meanings,
+ * so only the first is left as a raw isomorphic-git NotFoundError for
+ * callers to treat as "empty"; the second is wrapped into
+ * GitObjectNotFoundError specifically so it can't be mistaken for the first
+ * by an `isNotFound`-style check downstream (see getTreeFromRef/getCommitLog).
+ */
+export declare function resolveCommit(repo: Repo, ref: string): Promise<{
+    oid: string;
+    commit: import("isomorphic-git").CommitObject;
+}>;
+/** Read a blob's bytes by oid. */
+export declare function getBlob(repo: Repo, sha: string): Promise<Uint8Array>;
+/** Read a file's bytes at a ref. Throws GitPathNotFoundError when absent. */
+export declare function getFileContent(repo: Repo, filePath: string, ref: string, hooks?: OpsHooks): Promise<Uint8Array>;
+/** Read one commit by sha. */
+export declare function getCommit(repo: Repo, sha: string): Promise<CommitInfo>;
+export interface CommitLogOptions {
+    ref: string;
+    depth?: number;
+    /**
+     * Pass the head sha when the caller already resolved `ref` — resolveRef
+     * tries several candidate paths in sequence and misses the first few every
+     * time for a normal branch name, which is pure waste when the sha is known.
+     */
+    knownHeadSha?: string;
+}
+/**
+ * The commit chain from a ref, newest first. Walking is inherently sequential
+ * (each commit's oid is only discoverable by reading its child first) and
+ * network-round-trip-bound against object storage, so the deepest walk seen
+ * per head is memoized in `hooks.resultCache` and sliced for shallower or
+ * repeated requests — don't bypass this by calling `git.log` directly.
+ */
+export declare function getCommitLog(repo: Repo, options: CommitLogOptions, hooks?: OpsHooks): Promise<CommitInfo[]>;
+/** A file at a ref, decoded for display: utf8 text or base64 when binary. */
+export declare function getFileFromRef(repo: Repo, filePath: string, ref: string, hooks?: OpsHooks): Promise<{
+    content: string;
+    size: number;
+    isBinary: boolean;
+}>;
+/**
+ * List a directory at the tip of a ref. Throws GitRefNotFoundError when the
+ * ref doesn't resolve (including an empty repo's unborn branch) and
+ * GitPathNotFoundError when `treePath` doesn't exist. Results are memoized per
+ * head sha (auto-invalidates on push).
+ */
+export declare function getTreeFromRef(repo: Repo, options: {
+    ref: string;
+    treePath?: string;
+}, hooks?: OpsHooks): Promise<TreeEntry[]>;
+/**
+ * A page of commit history from a branch tip. Memoized per head sha; builds
+ * on {@link getCommitLog}'s walk cache for the underlying chain.
+ */
+export declare function getCommitHistory(repo: Repo, options: {
+    ref: string;
+    limit?: number;
+    skip?: number;
+}, hooks?: OpsHooks): Promise<CommitInfo[]>;

package/dist/types/ops/index.d.ts

@@ -0,0 +1,9 @@
+export { assertBranchExists, assertSafeBranchName, type Branch, createBranchFrom, deleteBranchByName, listBranches, resolveLooseRefFast, } from "./branch.js";
+export { authorNow, type CommitAuthor, commitFilesToBare, deleteFileFromBare, writeCommitToBare, } from "./commit.js";
+export { type DiffFile, type DiffResult, getCommitDiff, getDiffBetweenRefs, } from "./diff.js";
+export { BANNER_WALK_DEPTH, type FileHistoryEntry, type FileHistoryResult, getFileHistory, HISTORY_WALK_DEPTH, } from "./file-history.js";
+export { type CommitInfo, type CommitLogOptions, getBlob, getCommit, getCommitHistory, getCommitLog, getFileContent, getFileFromRef, getTreeFromRef, resolveCommit, } from "./history.js";
+export { getLastCommitsForTree, type LastCommitInfo, } from "./last-commit.js";
+export { analyzeMerge, fastForwardMerge, type MergeAnalysis } from "./merge.js";
+export { deleteFromTree, findTreeEntry, listTreeEntries, type TreeEntry, upsertTree, } from "./tree.js";
+export { type IsoGitFs, type OpsHooks, type Repo, type ResultCache, resultKeyPrefixes, } from "./types.js";

package/dist/types/ops/last-commit.d.ts

@@ -0,0 +1,23 @@
+import type { OpsHooks, Repo } from "./types.js";
+export interface LastCommitInfo {
+    sha: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    createdAt: string;
+}
+/**
+ * For each direct child of `treePath` (at the tip of `ref`), find the most
+ * recent commit that changed it — the tree view's "last commit" column. Walks
+ * history newest-to-oldest, comparing the directory's tree oid
+ * commit-to-commit and only descending one level to diff child oids when
+ * something under the directory actually changed. Preserve the two-phase
+ * structure (parallel prefetch, then sequential resolve) when touching this —
+ * the "which entries are still unresolved" state must advance
+ * commit-by-commit.
+ */
+export declare function getLastCommitsForTree(repo: Repo, options: {
+    ref: string;
+    treePath?: string;
+    depth?: number;
+}, hooks?: OpsHooks): Promise<Record<string, LastCommitInfo>>;

package/dist/types/ops/merge.d.ts

@@ -0,0 +1,28 @@
+import type { Repo } from "./types.js";
+export interface MergeAnalysis {
+    canMerge: boolean;
+    hasConflicts: boolean;
+    conflictingFiles: string[];
+    fastForward: boolean;
+}
+/**
+ * Cheap pre-merge check: do both branches exist, and is this a fast-forward?
+ * `canMerge`/`fastForward` are the only fields this actually determines —
+ * `hasConflicts`/`conflictingFiles` are NOT a real content-conflict check
+ * (isomorphic-git's `git.merge` doesn't expose a dry-run), they only ever
+ * reflect "one of the branches couldn't be resolved" (`canMerge: false`).
+ * Real merge conflicts are only discoverable by actually attempting the
+ * merge.
+ */
+export declare function analyzeMerge(repo: Repo, sourceBranch: string, targetBranch: string): Promise<MergeAnalysis>;
+/**
+ * Attempt a fast-forward merge directly against the bare repo: when source is
+ * a descendant of target, just move the target ref — no worktree, no new
+ * commit. Returns null when the merge is not a fast-forward (callers fall
+ * back to a real three-way merge, which needs a worktree). Serialize with a
+ * per-repo lock: resolve → writeRef is not atomic.
+ */
+export declare function fastForwardMerge(repo: Repo, sourceBranch: string, targetBranch: string): Promise<{
+    success: true;
+    commitSha: string;
+} | null>;

package/dist/types/ops/tree.d.ts

@@ -0,0 +1,19 @@
+import type { Repo } from "./types.js";
+export interface TreeEntry {
+    path: string;
+    mode: string;
+    type: "blob" | "tree";
+    oid: string;
+    size?: number;
+}
+/**
+ * Build/update a git tree by overlaying new blobs onto an existing tree,
+ * returning the new root tree oid. `entries` maps relative paths to blob oids.
+ */
+export declare function upsertTree(repo: Repo, treeOid: string | undefined, entries: Map<string, string>): Promise<string>;
+/** Remove a file path from a tree, returning the new root tree oid. */
+export declare function deleteFromTree(repo: Repo, treeOid: string, filePath: string): Promise<string>;
+/** Resolve a path inside a tree to its entry, or null when absent. */
+export declare function findTreeEntry(repo: Repo, rootTreeOid: string, treePath: string): Promise<TreeEntry | null>;
+/** List a tree's direct entries, with paths prefixed by `prefix`. */
+export declare function listTreeEntries(repo: Repo, treeOid: string, prefix?: string): Promise<TreeEntry[]>;