@catmint-fs/git 0.0.0-prealpha.0

package/dist/index.d.ts

@@ -0,0 +1,615 @@
+import { DirentEntry, StatResult } from '@catmint-fs/core';
+
+interface Layer {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array, options?: {
+        mode?: number;
+        uid?: number;
+        gid?: number;
+    }): Promise<void>;
+    readdir(path: string): Promise<DirentEntry[]>;
+    stat(path: string): Promise<StatResult>;
+    lstat(path: string): Promise<StatResult>;
+    readlink(path: string): Promise<string>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    createReadStream(path: string): ReadableStream<Uint8Array>;
+}
+interface GitIdentity {
+    name: string;
+    email: string;
+    timestamp?: number;
+    timezoneOffset?: number;
+}
+interface GitIdentityFull {
+    name: string;
+    email: string;
+    timestamp: number;
+    timezoneOffset: number;
+}
+interface BranchInfo {
+    name: string;
+    current: boolean;
+    commit: string;
+    upstream: string | null;
+}
+interface RemoteInfo {
+    name: string;
+    url: string;
+}
+interface RefEntry {
+    name: string;
+    oid: string;
+}
+type StatusCode = "added" | "modified" | "deleted" | "renamed" | "untracked" | "ignored" | "unmodified";
+interface StatusEntry {
+    path: string;
+    index: StatusCode;
+    workingTree: StatusCode;
+    /** For renames: original path */
+    origPath?: string;
+}
+interface CommitInfo {
+    oid: string;
+    tree: string;
+    parents: string[];
+    author: GitIdentityFull;
+    committer: GitIdentityFull;
+    message: string;
+}
+interface TagInfo {
+    name: string;
+    oid: string;
+    /** Tag type. */
+    type: "lightweight" | "annotated";
+    /** If annotated, the commit it points to */
+    target?: string;
+    tagger?: GitIdentityFull;
+    message?: string;
+}
+interface StashEntry {
+    index: number;
+    oid: string;
+    message: string;
+}
+interface FetchResult {
+    /** Refs that were updated. */
+    updated: Array<{
+        ref: string;
+        oldOid: string | null;
+        newOid: string;
+    }>;
+}
+interface PushResult {
+    ok: boolean;
+    refs: Array<{
+        ref: string;
+        status: "ok" | "rejected";
+        reason?: string;
+    }>;
+}
+interface MergeResult {
+    /** How the merge was resolved. */
+    type: "fast-forward" | "merge-commit" | "already-up-to-date";
+    /** The resulting commit OID (absent for "already-up-to-date"). */
+    oid?: string;
+    /** Conflicted file paths (non-empty only if merge has conflicts). */
+    conflicts: string[];
+}
+interface DiffLine {
+    /** Line origin: "+" (added), "-" (removed), " " (context). */
+    origin: "+" | "-" | " ";
+    /** Line content (without the origin marker). */
+    content: string;
+    /** Line number in the old file (undefined for added lines). */
+    oldLineNumber?: number;
+    /** Line number in the new file (undefined for deleted lines). */
+    newLineNumber?: number;
+}
+interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    header: string;
+    lines: DiffLine[];
+}
+interface DiffFile {
+    /** Path of the file. */
+    path: string;
+    /** Previous path (if renamed). */
+    oldPath?: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+    binary: boolean;
+    hunks: DiffHunk[];
+    similarity?: number;
+}
+interface DiffResult {
+    files: DiffFile[];
+}
+interface InitOptions {
+    defaultBranch?: string;
+    bare?: boolean;
+}
+interface CloneOptions {
+    url: string;
+    depth?: number;
+    branch?: string;
+    bare?: boolean;
+    transport?: GitTransport;
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+interface CommitOptions {
+    message: string;
+    author?: GitIdentity;
+    committer?: GitIdentity;
+    amend?: boolean;
+    allowEmpty?: boolean;
+}
+interface LogOptions {
+    ref?: string;
+    maxCount?: number;
+    skip?: number;
+    since?: Date;
+    until?: Date;
+    path?: string;
+}
+interface CheckoutOptions {
+    force?: boolean;
+    create?: boolean;
+}
+interface CreateBranchOptions {
+    startPoint?: string;
+    force?: boolean;
+}
+interface DeleteBranchOptions {
+    force?: boolean;
+}
+interface ListBranchesOptions {
+    remote?: boolean;
+}
+interface MergeOptions {
+    message?: string;
+    author?: GitIdentity;
+    noFastForward?: boolean;
+    fastForwardOnly?: boolean;
+}
+interface FetchOptions {
+    branch?: string;
+    depth?: number;
+    tags?: boolean;
+    transport?: GitTransport;
+    prune?: boolean;
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+interface PullOptions {
+    remote?: string;
+    branch?: string;
+    rebase?: boolean;
+    fastForwardOnly?: boolean;
+    author?: GitIdentity;
+    depth?: number;
+    tags?: boolean;
+    transport?: GitTransport;
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+interface PushOptions {
+    remote?: string;
+    branch?: string;
+    force?: boolean;
+    setUpstream?: boolean;
+    tags?: boolean;
+    transport?: GitTransport;
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+interface CreateTagOptions {
+    target?: string;
+    message?: string;
+    tagger?: GitIdentity;
+}
+interface DiffOptions {
+    /** Compare index vs HEAD (staged changes). Default: working tree vs index */
+    staged?: boolean;
+    /** Specific path to diff */
+    path?: string;
+    /** Compare two refs: source ref or OID */
+    from?: string;
+    /** Compare two refs: target ref or OID */
+    to?: string;
+    /** Number of context lines around each change. Default: 3 */
+    contextLines?: number;
+}
+interface StashOptions {
+    message?: string;
+    includeUntracked?: boolean;
+}
+interface ApplyStashOptions {
+    index?: number;
+}
+interface ResetOptions {
+    mode?: "soft" | "mixed" | "hard";
+    paths?: string[];
+}
+interface RemoveOptions {
+    cached?: boolean;
+    recursive?: boolean;
+}
+interface TransportDiscoveryResult {
+    refs: RefEntry[];
+    capabilities: string[];
+}
+interface TransportFetchRequest {
+    wants: string[];
+    haves: string[];
+    depth?: number;
+}
+interface TransportFetchResponse {
+    packfile: Uint8Array;
+    acks: string[];
+}
+interface TransportPushRequest {
+    updates: Array<{
+        ref: string;
+        oldOid: string;
+        newOid: string;
+    }>;
+    packfile: Uint8Array;
+}
+interface TransportPushResponse {
+    ok: boolean;
+    refs: Array<{
+        ref: string;
+        status: "ok" | "rejected";
+        reason?: string;
+    }>;
+}
+interface GitTransport {
+    discover(url: string, service: "git-upload-pack" | "git-receive-pack"): Promise<TransportDiscoveryResult>;
+    fetch(url: string, request: TransportFetchRequest): Promise<TransportFetchResponse>;
+    push(url: string, request: TransportPushRequest): Promise<TransportPushResponse>;
+}
+type GitObjectType = "blob" | "tree" | "commit" | "tag";
+interface GitObject {
+    type: GitObjectType;
+    content: Uint8Array;
+}
+interface TreeEntry {
+    mode: string;
+    name: string;
+    oid: string;
+}
+interface IndexEntry {
+    ctimeSeconds: number;
+    ctimeNanoseconds: number;
+    mtimeSeconds: number;
+    mtimeNanoseconds: number;
+    dev: number;
+    ino: number;
+    mode: number;
+    uid: number;
+    gid: number;
+    size: number;
+    oid: string;
+    flags: number;
+    path: string;
+    stage: number;
+}
+
+declare class ObjectDB {
+    private layer;
+    private gitDir;
+    constructor(layer: Layer, gitDir: string);
+    writeObject(type: GitObjectType, content: Uint8Array): Promise<string>;
+    readObject(oid: string): Promise<GitObject>;
+    existsObject(oid: string): Promise<boolean>;
+    private parseRawObject;
+    private readFromPacks;
+    writeBlob(content: Uint8Array): Promise<string>;
+    writeTree(entries: TreeEntry[]): Promise<string>;
+    parseTree(content: Uint8Array): TreeEntry[];
+    writeCommit(tree: string, parents: string[], author: GitIdentityFull, committer: GitIdentityFull, message: string): Promise<string>;
+    parseCommit(content: Uint8Array): {
+        tree: string;
+        parents: string[];
+        author: GitIdentityFull;
+        committer: GitIdentityFull;
+        message: string;
+    };
+    writeTag(object: string, type: GitObjectType, tagName: string, tagger: GitIdentityFull, message: string): Promise<string>;
+    parseTag(content: Uint8Array): {
+        object: string;
+        type: GitObjectType;
+        tag: string;
+        tagger: GitIdentityFull;
+        message: string;
+    };
+    hashObject(type: GitObjectType, content: Uint8Array): Promise<string>;
+}
+declare function formatIdentity(id: GitIdentityFull): string;
+declare function parseIdentity(str: string): GitIdentityFull;
+
+declare class RefStore {
+    private layer;
+    private gitDir;
+    constructor(layer: Layer, gitDir: string);
+    readRef(ref: string): Promise<string | null>;
+    readSymbolicRef(ref: string): Promise<string | null>;
+    resolveRef(ref: string): Promise<string>;
+    private resolveRefInner;
+    expandRef(shortName: string): Promise<string>;
+    writeRef(ref: string, oid: string): Promise<void>;
+    writeSymbolicRef(ref: string, target: string): Promise<void>;
+    deleteRef(ref: string): Promise<void>;
+    listRefs(prefix?: string): Promise<RefEntry[]>;
+    private listLooseRefs;
+    private readPackedRef;
+    private readAllPackedRefs;
+    private removeFromPackedRefs;
+}
+
+declare class IndexFile {
+    private layer;
+    private gitDir;
+    entries: IndexEntry[];
+    constructor(layer: Layer, gitDir: string);
+    read(): Promise<void>;
+    parse(data: Uint8Array): void;
+    write(): Promise<void>;
+    serialize(): Promise<Uint8Array>;
+    addEntry(entry: IndexEntry): void;
+    removeEntry(path: string): void;
+    removeEntriesUnder(dirPath: string): void;
+    getEntry(path: string, stage?: number): IndexEntry | undefined;
+    hasConflicts(): boolean;
+    getConflictedPaths(): string[];
+    clearConflictEntries(path: string): void;
+    private sortEntries;
+}
+
+interface ConfigSection {
+    name: string;
+    subsection?: string;
+    entries: Array<{
+        key: string;
+        value: string;
+    }>;
+}
+declare class GitConfig {
+    private layer;
+    private gitDir;
+    private sections;
+    private loaded;
+    constructor(layer: Layer, gitDir: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    get(key: string): string | undefined;
+    getAll(key: string): string[];
+    set(key: string, value: string): void;
+    delete(key: string): boolean;
+    deleteSection(sectionKey: string): boolean;
+    parseConfig(content: string): ConfigSection[];
+    serialize(): string;
+    private parseKey;
+}
+
+declare class GitIgnore {
+    private layer;
+    private workDir;
+    private rules;
+    constructor(layer: Layer, workDir: string);
+    load(): Promise<void>;
+    loadNested(dirPath: string): Promise<void>;
+    private loadFile;
+    parseRules(content: string, basePath: string): void;
+    isIgnored(path: string, isDirectory?: boolean): boolean;
+    addRules(content: string, basePath?: string): void;
+}
+
+declare class DiffEngine {
+    private layer;
+    private workDir;
+    private objectDB;
+    private indexFile;
+    private refStore;
+    private gitDir;
+    constructor(layer: Layer, workDir: string, objectDB: ObjectDB, indexFile: IndexFile, refStore: RefStore, gitDir: string);
+    diff(options?: DiffOptions): Promise<DiffResult>;
+    private diffWorkingTree;
+    private diffCached;
+    private diffRefs;
+    getHeadTree(): Promise<Map<string, string>>;
+    private getTreeForRef;
+    getTreeForCommit(commitOid: string): Promise<Map<string, string>>;
+    flattenTree(treeOid: string, prefix: string): Promise<Map<string, string>>;
+    /**
+     * Look up the OID of a specific path in a tree without flattening
+     * the entire tree. Walks tree objects one path segment at a time.
+     * Returns null if the path does not exist in the tree.
+     */
+    lookupPathInTree(treeOid: string, filePath: string): Promise<string | null>;
+    /**
+     * Get the OID of a specific path in a commit's tree.
+     * Returns null if the path does not exist.
+     */
+    getPathOidInCommit(commitOid: string, filePath: string): Promise<string | null>;
+    private createDiffFile;
+    private readBlob;
+}
+declare function computeDiffHunks(oldContent: string, newContent: string, contextLines?: number): DiffHunk[];
+
+declare class MergeEngine {
+    private layer;
+    private workDir;
+    private gitDir;
+    private objectDB;
+    private indexFile;
+    private refStore;
+    private diffEngine;
+    constructor(layer: Layer, workDir: string, gitDir: string, objectDB: ObjectDB, indexFile: IndexFile, refStore: RefStore, diffEngine: DiffEngine);
+    findMergeBase(oid1: string, oid2: string): Promise<string | null>;
+    merge(oursOid: string, theirsOid: string, message: string, author: GitIdentityFull, committer: GitIdentityFull): Promise<MergeResult>;
+    buildTreeFromPaths(paths: Map<string, string>): Promise<string>;
+    private writeTreeNode;
+    private readBlobText;
+    private addConflictEntry;
+    private createIndexEntry;
+}
+
+declare class StashManager {
+    private layer;
+    private workDir;
+    private gitDir;
+    private objectDB;
+    private indexFile;
+    private refStore;
+    private diffEngine;
+    private mergeEngine;
+    constructor(layer: Layer, workDir: string, gitDir: string, objectDB: ObjectDB, indexFile: IndexFile, refStore: RefStore, diffEngine: DiffEngine, mergeEngine: MergeEngine);
+    push(message: string, author: GitIdentityFull, includeUntracked?: boolean): Promise<string>;
+    apply(index?: number): Promise<void>;
+    pop(index?: number): Promise<void>;
+    drop(index?: number): Promise<void>;
+    list(): Promise<StashEntry[]>;
+    private pushStashRef;
+    private writeStashList;
+    private buildIndexTree;
+    private buildWorkingTree;
+    /**
+     * Recursively collects all file paths in the working directory,
+     * excluding .git directories.
+     */
+    private collectWorkingTreePaths;
+    private resetToHead;
+    private getCurrentBranchName;
+}
+
+declare class Repository {
+    readonly workDir: string;
+    readonly gitDir: string;
+    readonly objectDB: ObjectDB;
+    readonly refStore: RefStore;
+    readonly indexFile: IndexFile;
+    readonly config: GitConfig;
+    readonly ignore: GitIgnore;
+    readonly diffEngine: DiffEngine;
+    readonly mergeEngine: MergeEngine;
+    readonly stashManager: StashManager;
+    private transport;
+    constructor(layer: Layer, workDir?: string);
+    private _layer;
+    setTransport(transport: GitTransport): void;
+    load(): Promise<void>;
+    currentBranch(): Promise<string | null>;
+    createBranch(name: string, options?: CreateBranchOptions): Promise<void>;
+    deleteBranch(name: string, options?: DeleteBranchOptions): Promise<void>;
+    listBranches(options?: ListBranchesOptions): Promise<BranchInfo[]>;
+    renameBranch(oldName: string, newName: string): Promise<void>;
+    checkout(ref: string, options?: CheckoutOptions): Promise<void>;
+    /**
+     * Update working tree and index to match the given commit OID,
+     * without changing HEAD's symbolic ref. Used by merge to avoid
+     * accidentally switching branches.
+     */
+    private updateWorkingTreeToCommit;
+    add(pathOrPaths: string | string[]): Promise<void>;
+    private addDirectory;
+    unstage(pathOrPaths: string | string[]): Promise<void>;
+    remove(pathOrPaths: string | string[], options?: RemoveOptions): Promise<void>;
+    status(path?: string): Promise<StatusEntry[] | StatusEntry | null>;
+    private collectWorkingTreePaths;
+    listFiles(): Promise<string[]>;
+    isIgnored(path: string): Promise<boolean>;
+    commit(options: CommitOptions): Promise<string>;
+    log(options?: LogOptions): Promise<CommitInfo[]>;
+    readCommit(oid: string): Promise<CommitInfo>;
+    addRemote(name: string, url: string): Promise<void>;
+    listRemotes(): Promise<RemoteInfo[]>;
+    deleteRemote(name: string): Promise<void>;
+    fetch(remote: string, options?: FetchOptions): Promise<FetchResult>;
+    pull(remote: string, options?: PullOptions): Promise<MergeResult>;
+    push(remote: string, options?: PushOptions): Promise<PushResult>;
+    private collectObjectsForPush;
+    private storePackData;
+    merge(ref: string, options?: MergeOptions): Promise<MergeResult>;
+    abortMerge(): Promise<void>;
+    createTag(name: string, options?: CreateTagOptions): Promise<void>;
+    deleteTag(name: string): Promise<void>;
+    listTags(): Promise<TagInfo[]>;
+    diff(options?: DiffOptions): Promise<DiffResult>;
+    stash(options?: StashOptions): Promise<void>;
+    listStashes(): Promise<StashEntry[]>;
+    applyStash(options?: ApplyStashOptions): Promise<void>;
+    popStash(options?: ApplyStashOptions): Promise<void>;
+    dropStash(index?: number): Promise<void>;
+    getConfig(key: string): Promise<string | null>;
+    setConfig(key: string, value: string): Promise<void>;
+    deleteConfig(key: string): Promise<void>;
+    resolveRef(ref: string): Promise<string>;
+    listRefs(prefix?: string): Promise<RefEntry[]>;
+    setUpstream(branch: string, upstream: string): Promise<void>;
+    reset(ref: string, options?: ResetOptions): Promise<void>;
+    /**
+     * Resolve ref expressions like HEAD~1, HEAD~3, HEAD^, main~2, etc.
+     */
+    private resolveRefExpression;
+    private resetIndex;
+    private resetHard;
+    private buildIdentity;
+    buildTreeFromIndex(): Promise<string>;
+}
+
+interface HttpTransportOptions {
+    auth?: {
+        username: string;
+        password: string;
+    };
+    headers?: Record<string, string>;
+}
+declare class HttpTransport implements GitTransport {
+    private headers;
+    constructor(options?: HttpTransportOptions);
+    discover(url: string, service: "git-upload-pack" | "git-receive-pack"): Promise<TransportDiscoveryResult>;
+    parseDiscovery(data: Uint8Array, service: string): TransportDiscoveryResult;
+    fetch(url: string, request: TransportFetchRequest): Promise<TransportFetchResponse>;
+    buildFetchRequest(request: TransportFetchRequest): Uint8Array;
+    parseFetchResponse(data: Uint8Array): TransportFetchResponse;
+    push(url: string, request: TransportPushRequest): Promise<TransportPushResponse>;
+    buildPushRequest(request: TransportPushRequest): Uint8Array;
+    parsePushResponse(data: Uint8Array): TransportPushResponse;
+}
+
+type GitErrorCode = "NOT_A_GIT_REPO" | "ALREADY_EXISTS" | "NOT_FOUND" | "DIRTY_WORKING_TREE" | "NOTHING_TO_COMMIT" | "NOTHING_TO_STASH" | "DETACHED_HEAD" | "CURRENT_BRANCH" | "NON_FAST_FORWARD" | "TRANSPORT_ERROR" | "INVALID_OBJECT" | "UNRESOLVED_CONFLICT" | "BRANCH_NOT_FULLY_MERGED" | "NOT_MERGING" | "REPO_NOT_EMPTY";
+declare class GitError extends Error {
+    readonly code: GitErrorCode;
+    constructor(code: GitErrorCode, message: string);
+}
+
+declare function initRepository(layer: Layer, options?: InitOptions): Promise<Repository>;
+declare function openRepository(layer: Layer): Promise<Repository>;
+declare function cloneRepository(layer: Layer, options: CloneOptions): Promise<Repository>;
+declare function httpTransport(options?: HttpTransportOptions): HttpTransport;
+
+export { type ApplyStashOptions, type BranchInfo, type CheckoutOptions, type CloneOptions, type CommitInfo, type CommitOptions, type CreateBranchOptions, type CreateTagOptions, type DeleteBranchOptions, DiffEngine, type DiffFile, type DiffHunk, type DiffLine, type DiffOptions, type DiffResult, type FetchOptions, type FetchResult, GitConfig, GitError, type GitErrorCode, type GitIdentity, type GitIdentityFull, GitIgnore, type GitObject, type GitObjectType, type GitTransport, HttpTransport, type HttpTransportOptions, type IndexEntry, IndexFile, type InitOptions, type Layer, type ListBranchesOptions, type LogOptions, MergeEngine, type MergeOptions, type MergeResult, ObjectDB, type PullOptions, type PushOptions, type PushResult, type RefEntry, RefStore, type RemoteInfo, type RemoveOptions, Repository, type ResetOptions, type StashEntry, StashManager, type StashOptions, type StatusCode, type StatusEntry, type TagInfo, type TransportDiscoveryResult, type TransportFetchRequest, type TransportFetchResponse, type TransportPushRequest, type TransportPushResponse, type TreeEntry, cloneRepository, computeDiffHunks, formatIdentity, httpTransport, initRepository, openRepository, parseIdentity };