git-fs-s3 0.3.5

package/dist/ops.d.ts

@@ -0,0 +1,290 @@
+import { R as Repo, O as OpsHooks } from './types-BHoHOaQt.js';
+export { I as IsoGitFs, a as ResultCache, r as resultKeyPrefixes } from './types-BHoHOaQt.js';
+import * as git from 'isomorphic-git';
+
+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.
+ */
+declare function assertSafeBranchName(name: string): void;
+/** All branches with their tip commits; [] for an empty repository. */
+declare function listBranches(repo: Repo): Promise<Branch[]>;
+/** Create `name` pointing at the tip of `startPoint` (no checkout). */
+declare function createBranchFrom(repo: Repo, name: string, startPoint?: string): Promise<void>;
+/** Delete a branch ref (validated — deleteBranch has no internal ref check). */
+declare function deleteBranchByName(repo: Repo, name: string): Promise<void>;
+/** Throws (NotFoundError) unless the branch resolves. */
+declare function assertBranchExists(repo: Repo, name: string): Promise<void>;
+
+interface CommitAuthor {
+    name: string;
+    email: string;
+    timestamp: number;
+    timezoneOffset: number;
+}
+/** An author stamped with the current time. */
+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.
+ */
+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.
+ */
+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. */
+declare function deleteFileFromBare(repo: Repo, options: {
+    branch: string;
+    filePath: string;
+    message: string;
+    author: CommitAuthor;
+}): Promise<string>;
+
+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;
+}
+interface DiffResult {
+    files: DiffFile[];
+    totalAdditions: number;
+    totalDeletions: number;
+    totalFiles: number;
+}
+/** The diff a single commit introduced (against its first parent). */
+declare function getCommitDiff(repo: Repo, commitSha: string): Promise<DiffResult>;
+/** The diff between two refs (base -> compare). */
+declare function getDiffBetweenRefs(repo: Repo, baseRef: string, compareRef: string): Promise<DiffResult>;
+
+interface FileHistoryEntry {
+    sha: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    createdAt: string;
+}
+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.
+ */
+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.
+ */
+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.
+ */
+declare function getFileHistory(repo: Repo, options: {
+    ref: string;
+    filePath: string;
+    limit?: number;
+    maxDepth?: number;
+}, hooks?: OpsHooks): Promise<FileHistoryResult>;
+
+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.
+ */
+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. */
+declare function deleteFromTree(repo: Repo, treeOid: string, filePath: string): Promise<string>;
+/** Resolve a path inside a tree to its entry, or null when absent. */
+declare function findTreeEntry(repo: Repo, rootTreeOid: string, treePath: string): Promise<TreeEntry | null>;
+/** List a tree's direct entries, with paths prefixed by `prefix`. */
+declare function listTreeEntries(repo: Repo, treeOid: string, prefix?: string): Promise<TreeEntry[]>;
+
+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).
+ */
+declare function resolveCommit(repo: Repo, ref: string): Promise<{
+    oid: string;
+    commit: git.CommitObject;
+}>;
+/** Read a blob's bytes by oid. */
+declare function getBlob(repo: Repo, sha: string): Promise<Uint8Array>;
+/** Read a file's bytes at a ref. Throws GitPathNotFoundError when absent. */
+declare function getFileContent(repo: Repo, filePath: string, ref?: string): Promise<Uint8Array>;
+/** Read one commit by sha. */
+declare function getCommit(repo: Repo, sha: string): Promise<CommitInfo>;
+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.
+ */
+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. */
+declare function getFileFromRef(repo: Repo, filePath: string, ref: string): 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).
+ */
+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.
+ */
+declare function getCommitHistory(repo: Repo, options: {
+    ref: string;
+    limit?: number;
+    skip?: number;
+}, hooks?: OpsHooks): Promise<CommitInfo[]>;
+
+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.
+ */
+declare function getLastCommitsForTree(repo: Repo, options: {
+    ref: string;
+    treePath?: string;
+    depth?: number;
+}, hooks?: OpsHooks): Promise<Record<string, LastCommitInfo>>;
+
+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.
+ */
+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.
+ */
+declare function fastForwardMerge(repo: Repo, sourceBranch: string, targetBranch: string): Promise<{
+    success: true;
+    commitSha: string;
+} | null>;
+
+export { BANNER_WALK_DEPTH, type Branch, type CommitAuthor, type CommitInfo, type CommitLogOptions, type DiffFile, type DiffResult, type FileHistoryEntry, type FileHistoryResult, HISTORY_WALK_DEPTH, type LastCommitInfo, type MergeAnalysis, OpsHooks, Repo, type TreeEntry, analyzeMerge, assertBranchExists, assertSafeBranchName, authorNow, commitFilesToBare, createBranchFrom, deleteBranchByName, deleteFileFromBare, deleteFromTree, fastForwardMerge, findTreeEntry, getBlob, getCommit, getCommitDiff, getCommitHistory, getCommitLog, getDiffBetweenRefs, getFileContent, getFileFromRef, getFileHistory, getLastCommitsForTree, getTreeFromRef, listBranches, listTreeEntries, resolveCommit, upsertTree, writeCommitToBare };