git-fs-s3 0.4.0 → 0.5.0

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,54 @@
+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 {
+    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,85 @@
+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. Returns [] for an empty repo/unborn
+ * branch; throws 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[]>;

package/dist/{types-BHoHOaQt.d.cts → types/ops/types.d.ts}

@@ -1,13 +1,12 @@
-import git__default from 'isomorphic-git';
-
+import type git from "isomorphic-git";
 /** The fs shape isomorphic-git accepts, derived from its own signatures. */
-type IsoGitFs = Parameters<typeof git__default.readTree>[0]["fs"];
+export type IsoGitFs = Parameters<typeof git.readTree>[0]["fs"];
 /**
  * A repository handle: everything isomorphic-git needs to address one bare
  * repo. Create it once per request (sharing `cache` across calls is what lets
  * isomorphic-git reuse parsed pack indexes) and pass it to every op.
  */
-interface Repo {
+export interface Repo {
     fs: IsoGitFs;
     gitdir: string;
     /** isomorphic-git's shared parse cache — strongly recommended per repo. */
@@ -20,12 +19,12 @@ interface Repo {
  * under {@link resultKeyPrefixes} after rewriting a repo's storage out of
  * band, or stale walks leak until your store's own eviction.
  */
-interface ResultCache {
+export interface ResultCache {
     get<T>(key: string): T | null | undefined;
     set(key: string, value: unknown): void;
 }
 /** Optional instrumentation and tuning hooks accepted by every op. */
-interface OpsHooks {
+export interface OpsHooks {
     resultCache?: ResultCache;
     /** Wrap a timed sub-step (network walk, tree listing). Default: run directly. */
     step?: <T>(label: string, fn: () => Promise<T>) => Promise<T>;
@@ -43,11 +42,10 @@ interface OpsHooks {
     /** Minimum walk depth before `prefetch` fires for history walks. Default 5. */
     prefetchMinDepth?: number;
 }
+export declare const runStep: <T>(hooks: OpsHooks | undefined, label: string, fn: () => Promise<T>) => Promise<T>;
 /**
  * The result-cache key prefixes holding entries for `gitdir` — evict these
  * from your {@link ResultCache} when the repo's storage was rewritten outside
  * a normal push (bulk sync, rename, repack cleanup).
  */
-declare function resultKeyPrefixes(gitdir: string): string[];
-
-export { type IsoGitFs as I, type OpsHooks as O, type Repo as R, type ResultCache as a, resultKeyPrefixes as r };
+export declare function resultKeyPrefixes(gitdir: string): string[];

package/dist/types/pack-files.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Typed view of a git `objects/pack` directory listing.
+ *
+ * Every pack is a set of sibling files sharing one base name
+ * (`pack-<hash>.pack`, `.idx`, and optionally `.keep`/`.bitmap`/`.rev`).
+ * Parsing names once into {@link PackFileName} lets callers group, filter and
+ * rename by kind instead of re-matching filename strings at each call site.
+ *
+ * Edge-compatible: no node: imports.
+ */
+/** Every file kind git writes into `objects/pack`. */
+export declare const PACK_FILE_KINDS: readonly ["pack", "idx", "keep", "bitmap", "rev"];
+export type PackFileKind = (typeof PACK_FILE_KINDS)[number];
+/** Kinds isomorphic-git actually reads; the rest are git-CLI accelerators. */
+export declare const READABLE_PACK_FILE_KINDS: ReadonlySet<PackFileKind>;
+export interface PackFileName {
+    /** Shared base of a pack's sibling files, e.g. `pack-1a2b…`. */
+    readonly base: string;
+    readonly kind: PackFileKind;
+    /** The file name as listed, e.g. `pack-1a2b….idx`. */
+    readonly name: string;
+}
+/** Parse a pack-directory entry; `null` for anything git didn't put there. */
+export declare function parsePackFileName(name: string): PackFileName | null;
+/** File name of the `kind` sibling of the pack with this base name. */
+export declare function packFileName(base: string, kind: PackFileKind): string;
+/** Parse a directory listing, dropping entries that aren't pack files. */
+export declare function parsePackDirectory(entries: readonly string[]): PackFileName[];

package/dist/types/path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize an absolute-or-relative filesystem path into a storage key
+ * segment: no leading/trailing slashes, `.` segments dropped, `..` resolved.
+ * A `..` that would escape the root throws EINVAL — paths handed to the fs
+ * must never address keys outside the configured prefix.
+ */
+export declare function normalizePath(filepath: string): string;
+/** Join a configured key prefix with a normalized path. */
+export declare function toKey(prefix: string, filepath: string): string;