gitx.do 0.0.2 → 0.0.3

package/dist/wire/upload-pack.d.ts

@@ -1,333 +1,727 @@
 /**
- * Git upload-pack protocol implementation
+ * @fileoverview Git upload-pack Protocol Implementation
  *
- * The upload-pack service is used by git-fetch and git-clone to retrieve
- * objects from a remote repository.
+ * This module implements the server-side of Git's upload-pack service, which is
+ * used by `git-fetch` and `git-clone` to retrieve objects from a remote repository.
  *
- * Protocol flow:
- * 1. Server advertises refs (ref advertisement)
- * 2. Client sends "want" lines for desired objects
- * 3. Client sends "have" lines for objects it already has
- * 4. Server responds with ACK/NAK
- * 5. Server sends packfile with requested objects
+ * @module wire/upload-pack
  *
- * Reference: https://git-scm.com/docs/protocol-v2
- *            https://git-scm.com/docs/pack-protocol
+ * ## Protocol Flow
+ *
+ * 1. **Ref Advertisement**: Server advertises available refs with capabilities
+ * 2. **Want Phase**: Client sends "want" lines for objects it needs
+ * 3. **Negotiation**: Client sends "have" lines, server responds with ACK/NAK
+ * 4. **Done**: Client signals negotiation complete with "done"
+ * 5. **Packfile**: Server generates and sends packfile with requested objects
+ *
+ * ## Features
+ *
+ * - Side-band multiplexing for progress reporting
+ * - Thin pack support for bandwidth efficiency
+ * - Shallow clone support with depth limiting
+ * - Multi-ack negotiation for optimal object transfer
+ *
+ * @see {@link https://git-scm.com/docs/protocol-v2} Git Protocol v2
+ * @see {@link https://git-scm.com/docs/pack-protocol} Git Pack Protocol
+ *
+ * @example Basic fetch operation
+ * ```typescript
+ * import { createSession, advertiseRefs, handleFetch } from './wire/upload-pack'
+ *
+ * // Create session and advertise refs
+ * const session = createSession('my-repo', await store.getRefs())
+ * const advertisement = await advertiseRefs(store)
+ *
+ * // Process fetch request
+ * const response = await handleFetch(session, requestBody, store)
+ * ```
  */
 import type { ObjectType } from '../types/objects';
 /**
- * A reference (branch, tag, etc.) with its SHA and optional peeled value
+ * A reference (branch, tag, etc.) with its SHA and optional peeled value.
+ *
+ * @description
+ * Represents a Git reference that can be advertised to clients. For annotated
+ * tags, the `peeled` field contains the SHA of the underlying commit.
+ *
+ * @example
+ * ```typescript
+ * const branch: Ref = {
+ *   name: 'refs/heads/main',
+ *   sha: 'abc123def456...'
+ * }
+ *
+ * const annotatedTag: Ref = {
+ *   name: 'refs/tags/v1.0.0',
+ *   sha: 'tag-object-sha...',
+ *   peeled: 'target-commit-sha...'
+ * }
+ * ```
  */
 export interface Ref {
+    /** Full ref name (e.g., 'refs/heads/main', 'refs/tags/v1.0.0') */
     name: string;
+    /** SHA-1 hash of the object this ref points to */
     sha: string;
+    /** For annotated tags, the SHA of the target object (commit) */
     peeled?: string;
 }
 /**
- * Capabilities supported by the upload-pack service
+ * Capabilities supported by the upload-pack service.
+ *
+ * @description
+ * These capabilities are advertised to clients and negotiated during the
+ * initial handshake. Clients select which capabilities to use based on
+ * what the server supports.
+ *
+ * @example
+ * ```typescript
+ * const caps: UploadPackCapabilities = {
+ *   sideBand64k: true,
+ *   thinPack: true,
+ *   shallow: true,
+ *   includeTag: true,
+ *   multiAckDetailed: true,
+ *   agent: 'my-server/1.0'
+ * }
+ * ```
  */
 export interface UploadPackCapabilities {
-    /** Side-band multiplexing for progress reporting */
+    /** Side-band multiplexing for progress reporting (8KB limit) */
     sideBand?: boolean;
+    /** Side-band-64k multiplexing (64KB limit, preferred) */
     sideBand64k?: boolean;
     /** Thin pack support - allows deltas against objects client has */
     thinPack?: boolean;
-    /** Include tags that point to fetched objects */
+    /** Include tags that point to fetched objects automatically */
     includeTag?: boolean;
-    /** Shallow clone support */
+    /** Shallow clone support (limited history depth) */
     shallow?: boolean;
     /** Deepen relative to current shallow boundary */
     deepenRelative?: boolean;
-    /** Don't send objects in common */
+    /** Don't send progress messages */
     noProgress?: boolean;
-    /** Object filtering (partial clone) */
+    /** Object filtering (partial clone) support */
     filter?: boolean;
-    /** Allow fetching reachable SHA-1 not advertised */
+    /** Allow fetching reachable SHA-1 not advertised in refs */
     allowReachableSha1InWant?: boolean;
-    /** Allow fetching any SHA-1 */
+    /** Allow fetching any SHA-1 (dangerous, usually disabled) */
     allowAnySha1InWant?: boolean;
-    /** Multi-ack for better negotiation */
+    /** Multi-ack for negotiation optimization */
     multiAck?: boolean;
+    /** Multi-ack with detailed status */
     multiAckDetailed?: boolean;
     /** Object format (sha1 or sha256) */
     objectFormat?: 'sha1' | 'sha256';
-    /** Protocol version */
+    /** Server agent identification string */
     agent?: string;
 }
 /**
- * Session state for an upload-pack operation
+ * Session state for an upload-pack operation.
+ *
+ * @description
+ * Maintains state across the multi-phase upload-pack protocol. For stateless
+ * protocols like HTTP, some state must be reconstructed from each request.
+ *
+ * @example
+ * ```typescript
+ * const session = createSession('my-repo', refs, false)
+ * // session.wants, session.haves populated during negotiation
+ * // session.negotiationComplete set to true when ready for packfile
+ * ```
  */
 export interface UploadPackSession {
-    /** Repository identifier */
+    /** Repository identifier for logging/tracking */
     repoId: string;
-    /** Advertised references */
+    /** Advertised references from the repository */
     refs: Ref[];
-    /** Capabilities negotiated with client */
+    /** Capabilities negotiated with the client */
     capabilities: UploadPackCapabilities;
-    /** Objects the client wants */
+    /** Object SHAs the client wants to receive */
     wants: string[];
-    /** Objects the client already has */
+    /** Object SHAs the client already has */
     haves: string[];
-    /** Common ancestors found during negotiation */
+    /** Common ancestor commits found during negotiation */
     commonAncestors: string[];
     /** Shallow boundary commits (for shallow clones) */
     shallowCommits: string[];
     /** Depth limit for shallow clone */
     depth?: number;
-    /** Deepen-since timestamp */
+    /** Deepen-since timestamp for shallow clone */
     deepenSince?: number;
-    /** Deepen-not refs */
+    /** Refs to exclude when deepening */
     deepenNot?: string[];
-    /** Whether negotiation is complete */
+    /** Whether negotiation is complete and packfile should be sent */
     negotiationComplete: boolean;
-    /** Whether this is a stateless request (HTTP) */
+    /** Whether this is a stateless request (HTTP protocol) */
     stateless: boolean;
 }
 /**
- * Result of want/have negotiation
+ * Result of want/have negotiation.
+ *
+ * @description
+ * Contains the ACK/NAK responses to send to the client and information
+ * about which objects need to be included in the packfile.
  */
 export interface WantHaveNegotiation {
-    /** ACK responses for common objects */
+    /** ACK responses for common objects found */
     acks: Array<{
         sha: string;
         status: 'common' | 'ready' | 'continue';
     }>;
-    /** Whether server has nothing in common (NAK) */
+    /** Whether server has nothing in common with client (NAK) */
     nak: boolean;
-    /** Common ancestor commits found */
+    /** Common ancestor commits found during negotiation */
     commonAncestors: string[];
-    /** Objects the server needs to send */
+    /** Object SHAs that need to be sent to the client */
     objectsToSend: string[];
     /** Whether negotiation is complete and packfile should be sent */
     ready: boolean;
 }
 /**
- * Side-band channel types
+ * Side-band channel types for multiplexed output.
+ *
+ * @description
+ * When side-band is enabled, the server can send data on multiple channels:
+ * - Channel 1: Packfile data
+ * - Channel 2: Progress messages (displayed to user)
+ * - Channel 3: Error messages (fatal, abort transfer)
  */
 export declare enum SideBandChannel {
-    /** Packfile data */
+    /** Packfile data - the actual objects being transferred */
     PACK_DATA = 1,
-    /** Progress messages */
+    /** Progress messages - informational output for the user */
     PROGRESS = 2,
-    /** Error messages */
+    /** Error messages - fatal errors that abort the transfer */
     ERROR = 3
 }
 /**
- * Progress callback for packfile generation
+ * Progress callback for packfile generation.
+ *
+ * @description
+ * Called during packfile generation to report progress. Messages are
+ * typically sent via side-band channel 2 to the client.
+ *
+ * @param message - Progress message to display
  */
 export type ProgressCallback = (message: string) => void;
 /**
- * Options for packfile generation
+ * Options for packfile generation.
+ *
+ * @description
+ * Controls how the packfile is generated, including delta compression
+ * settings and progress reporting.
  */
 export interface PackfileOptions {
     /** Generate thin pack (use deltas against client's objects) */
     thinPack?: boolean;
     /** Include tags pointing to requested objects */
     includeTag?: boolean;
-    /** Progress callback */
+    /** Progress callback for status updates */
     onProgress?: ProgressCallback;
-    /** Objects client already has (for thin pack) */
+    /** Objects client already has (for thin pack delta bases) */
     clientHasObjects?: string[];
-    /** Maximum delta depth */
+    /** Maximum delta chain depth */
     maxDeltaDepth?: number;
-    /** Window size for delta compression */
+    /** Window size for delta compression algorithm */
     deltaWindowSize?: number;
 }
 /**
- * Result of packfile generation
+ * Result of packfile generation.
+ *
+ * @description
+ * Contains the generated packfile along with metadata about what
+ * was included.
  */
 export interface PackfileResult {
-    /** The packfile data */
+    /** The generated packfile binary data */
     packfile: Uint8Array;
     /** Number of objects in the pack */
     objectCount: number;
-    /** Objects included in the pack */
+    /** List of object SHAs included in the pack */
     includedObjects: string[];
 }
 /**
- * Object storage interface for retrieving git objects
+ * Object storage interface for retrieving git objects.
+ *
+ * @description
+ * Defines the methods required from an object store to support
+ * upload-pack operations. Implementations typically wrap a Git
+ * object database or similar storage.
+ *
+ * @example
+ * ```typescript
+ * class MyObjectStore implements ObjectStore {
+ *   async getObject(sha: string) {
+ *     return this.database.get(sha)
+ *   }
+ *   async hasObject(sha: string) {
+ *     return this.database.has(sha)
+ *   }
+ *   // ... other methods
+ * }
+ * ```
  */
 export interface ObjectStore {
-    /** Get an object by SHA */
+    /**
+     * Get an object by its SHA.
+     * @param sha - The SHA-1 hash of the object
+     * @returns The object type and data, or null if not found
+     */
     getObject(sha: string): Promise<{
         type: ObjectType;
         data: Uint8Array;
     } | null>;
-    /** Check if object exists */
+    /**
+     * Check if an object exists in the store.
+     * @param sha - The SHA-1 hash to check
+     * @returns true if the object exists
+     */
     hasObject(sha: string): Promise<boolean>;
-    /** Get commit parents */
+    /**
+     * Get the parent commit SHAs for a commit.
+     * @param sha - The commit SHA
+     * @returns Array of parent commit SHAs
+     */
     getCommitParents(sha: string): Promise<string[]>;
-    /** Get all refs */
+    /**
+     * Get all refs in the repository.
+     * @returns Array of Ref objects
+     */
     getRefs(): Promise<Ref[]>;
-    /** Get objects reachable from a commit */
+    /**
+     * Get all objects reachable from a given SHA.
+     * @param sha - Starting object SHA
+     * @param depth - Optional depth limit
+     * @returns Array of reachable object SHAs
+     */
     getReachableObjects(sha: string, depth?: number): Promise<string[]>;
 }
 /**
- * Shallow clone info
+ * Shallow clone information.
+ *
+ * @description
+ * Contains information about shallow boundary changes during
+ * fetch operations with depth limiting.
  */
 export interface ShallowInfo {
-    /** Commits at the shallow boundary */
+    /** Commits at the new shallow boundary */
     shallowCommits: string[];
-    /** Commits that are no longer shallow */
+    /** Commits that are no longer shallow (deepened) */
     unshallowCommits: string[];
 }
 /**
- * Build capability string for ref advertisement
+ * Build capability string for ref advertisement.
+ *
+ * @description
+ * Converts a capabilities object into a space-separated string suitable
+ * for inclusion in the ref advertisement. Boolean capabilities become
+ * simple names, while capabilities with values become "name=value".
  *
  * @param capabilities - Capabilities to advertise
  * @returns Space-separated capability string
+ *
+ * @example
+ * ```typescript
+ * const caps: UploadPackCapabilities = {
+ *   sideBand64k: true,
+ *   thinPack: true,
+ *   agent: 'my-server/1.0'
+ * }
+ * const str = buildCapabilityString(caps)
+ * // 'side-band-64k thin-pack agent=my-server/1.0'
+ * ```
  */
 export declare function buildCapabilityString(capabilities: UploadPackCapabilities): string;
 /**
- * Parse capabilities from first want line
+ * Parse capabilities from first want line.
+ *
+ * @description
+ * Parses a space-separated capability string (typically from the first
+ * want line of a fetch request) into a structured capabilities object.
  *
- * @param capsString - Space-separated capabilities
- * @returns Parsed capabilities
+ * @param capsString - Space-separated capabilities from client
+ * @returns Parsed capabilities object
+ *
+ * @example
+ * ```typescript
+ * const caps = parseCapabilities('side-band-64k thin-pack agent=git/2.30.0')
+ * // caps.sideBand64k === true
+ * // caps.thinPack === true
+ * // caps.agent === 'git/2.30.0'
+ * ```
  */
 export declare function parseCapabilities(capsString: string): UploadPackCapabilities;
 /**
- * Create a new upload-pack session
+ * Create a new upload-pack session.
+ *
+ * @description
+ * Initializes a new session for an upload-pack operation. The session
+ * tracks state across the negotiation and packfile generation phases.
  *
- * @param repoId - Repository identifier
- * @param refs - Available refs
+ * @param repoId - Repository identifier for logging/tracking
+ * @param refs - Available refs to advertise
  * @param stateless - Whether this is a stateless (HTTP) request
  * @returns New session object
+ *
+ * @example
+ * ```typescript
+ * const refs = await store.getRefs()
+ * const session = createSession('my-repo', refs, true)  // HTTP
+ * // session.negotiationComplete === false initially
+ * ```
  */
 export declare function createSession(repoId: string, refs: Ref[], stateless?: boolean): UploadPackSession;
 /**
- * Parse a want line from the client
+ * Parse a want line from the client.
+ *
+ * @description
+ * Parses a "want" line which has the format:
+ * `want <sha> [capabilities...]`
  *
- * @param line - The want line (e.g., "want <sha> [capabilities]")
+ * The first want line typically includes capabilities, subsequent ones don't.
+ *
+ * @param line - The want line (e.g., "want abc123... side-band-64k")
  * @returns Parsed SHA and capabilities
+ *
+ * @throws {Error} If the line format is invalid or SHA is malformed
+ *
+ * @example
+ * ```typescript
+ * // First want line with capabilities
+ * const { sha, capabilities } = parseWantLine(
+ *   'want abc123... side-band-64k thin-pack'
+ * )
+ * // sha === 'abc123...'
+ * // capabilities.sideBand64k === true
+ *
+ * // Subsequent want line
+ * const { sha: sha2 } = parseWantLine('want def456...')
+ * ```
  */
 export declare function parseWantLine(line: string): {
     sha: string;
     capabilities: UploadPackCapabilities;
 };
 /**
- * Parse a have line from the client
+ * Parse a have line from the client.
+ *
+ * @description
+ * Parses a "have" line which has the simple format:
+ * `have <sha>`
+ *
+ * @param line - The have line (e.g., "have abc123...")
+ * @returns The parsed SHA
+ *
+ * @throws {Error} If the line format is invalid or SHA is malformed
  *
- * @param line - The have line (e.g., "have <sha>")
- * @returns Parsed SHA
+ * @example
+ * ```typescript
+ * const sha = parseHaveLine('have abc123def456...')
+ * // sha === 'abc123def456...'
+ * ```
  */
 export declare function parseHaveLine(line: string): string;
 /**
- * Advertise refs to the client
+ * Advertise refs to the client.
+ *
+ * @description
+ * Generates the ref advertisement response for the initial phase of
+ * upload-pack. This includes:
+ * - HEAD reference with capabilities
+ * - Sorted refs with symref information
+ * - Peeled refs for annotated tags
  *
  * @param store - Object store to get refs from
- * @param capabilities - Server capabilities to advertise
+ * @param capabilities - Optional server capabilities to advertise
  * @returns Pkt-line formatted ref advertisement
+ *
+ * @example
+ * ```typescript
+ * const advertisement = await advertiseRefs(store, {
+ *   sideBand64k: true,
+ *   thinPack: true
+ * })
+ * // Send as response to GET /info/refs?service=git-upload-pack
+ * ```
  */
 export declare function advertiseRefs(store: ObjectStore, capabilities?: Partial<UploadPackCapabilities>): Promise<string>;
 /**
- * Format an ACK response
+ * Format an ACK response.
+ *
+ * @description
+ * Creates a pkt-line formatted ACK response for negotiation:
+ * - Simple ACK: `ACK <sha>` (when negotiation is complete)
+ * - Status ACK: `ACK <sha> <status>` (during multi_ack negotiation)
  *
  * @param sha - The SHA being acknowledged
  * @param status - ACK status (common, ready, continue, or none for simple ACK)
  * @returns Pkt-line formatted ACK
+ *
+ * @example
+ * ```typescript
+ * // Simple ACK
+ * const ack = formatAck('abc123...')
+ * // '0014ACK abc123...\n'
+ *
+ * // Multi-ack with status
+ * const ackContinue = formatAck('abc123...', 'continue')
+ * // '001dACK abc123... continue\n'
+ * ```
  */
 export declare function formatAck(sha: string, status?: 'common' | 'ready' | 'continue'): string;
 /**
- * Format a NAK response
+ * Format a NAK response.
+ *
+ * @description
+ * Creates a pkt-line formatted NAK response. NAK indicates that the
+ * server has no objects in common with the client's "have" list.
  *
  * @returns Pkt-line formatted NAK
+ *
+ * @example
+ * ```typescript
+ * const nak = formatNak()
+ * // '0008NAK\n'
+ * ```
  */
 export declare function formatNak(): string;
 /**
- * Process client wants and update session
+ * Process client wants and update session.
+ *
+ * @description
+ * Validates and processes the "want" SHAs from a client fetch request.
+ * Verifies that all wanted objects exist in the repository.
  *
  * @param session - Current session state
- * @param wants - Array of want SHAs
+ * @param wants - Array of want SHAs from the client
  * @param store - Object store to verify objects exist
  * @returns Updated session
+ *
+ * @throws {Error} If any wanted object doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const session = createSession('repo', refs)
+ * await processWants(session, ['abc123...', 'def456...'], store)
+ * // session.wants now contains the validated wants
+ * ```
  */
 export declare function processWants(session: UploadPackSession, wants: string[], store: ObjectStore): Promise<UploadPackSession>;
 /**
- * Process client haves and perform negotiation
+ * Process client haves and perform negotiation.
+ *
+ * @description
+ * Processes the "have" SHAs from the client to find common ancestors.
+ * This determines which objects need to be sent vs which the client
+ * already has.
  *
  * @param session - Current session state
- * @param haves - Array of have SHAs
+ * @param haves - Array of have SHAs from the client
  * @param store - Object store to check for common objects
  * @param done - Whether client is done sending haves
- * @returns Negotiation result
+ * @returns Negotiation result with ACKs/NAKs and objects to send
+ *
+ * @example
+ * ```typescript
+ * const result = await processHaves(session, ['abc123...'], store, true)
+ * if (result.nak) {
+ *   // No common objects, will send full pack
+ * } else {
+ *   // Can send incremental pack
+ * }
+ * ```
  */
 export declare function processHaves(session: UploadPackSession, haves: string[], store: ObjectStore, done: boolean): Promise<WantHaveNegotiation>;
 /**
- * Calculate objects needed by client
+ * Calculate objects needed by client.
  *
- * Given wants and haves, determine minimal set of objects to send.
+ * @description
+ * Given the client's wants and haves, determines the minimal set of
+ * objects that need to be sent. Walks the object graph from wants,
+ * stopping at objects the client already has.
  *
  * @param store - Object store
  * @param wants - Objects client wants
  * @param haves - Objects client has
  * @returns Set of object SHAs to include in packfile
+ *
+ * @example
+ * ```typescript
+ * const missing = await calculateMissingObjects(
+ *   store,
+ *   ['new-commit-sha'],
+ *   ['old-commit-sha']
+ * )
+ * // missing contains only objects reachable from new-commit
+ * // but not reachable from old-commit
+ * ```
  */
 export declare function calculateMissingObjects(store: ObjectStore, wants: string[], haves: string[]): Promise<Set<string>>;
 /**
- * Process shallow/deepen commands
+ * Process shallow/deepen commands.
+ *
+ * @description
+ * Handles shallow clone requests by processing depth limits, deepen-since
+ * timestamps, and deepen-not refs. Updates the session with shallow
+ * boundary information.
  *
  * @param session - Current session
  * @param shallowLines - Shallow commit lines from client
- * @param depth - Requested depth
+ * @param depth - Requested commit depth
  * @param deepenSince - Timestamp to deepen since
  * @param deepenNot - Refs to not deepen past
  * @param store - Object store
  * @returns Shallow info with boundary commits
+ *
+ * @example
+ * ```typescript
+ * const shallowInfo = await processShallow(
+ *   session,
+ *   [],  // No previous shallow commits
+ *   3,   // Depth of 3 commits
+ *   undefined,
+ *   undefined,
+ *   store
+ * )
+ * // shallowInfo.shallowCommits contains boundary commits
+ * ```
  */
 export declare function processShallow(session: UploadPackSession, shallowLines: string[], depth?: number, deepenSince?: number, deepenNot?: string[], store?: ObjectStore): Promise<ShallowInfo>;
 /**
- * Format shallow/unshallow lines for response
+ * Format shallow/unshallow lines for response.
+ *
+ * @description
+ * Creates pkt-line formatted shallow/unshallow responses to send
+ * to the client before the packfile.
  *
  * @param shallowInfo - Shallow info to format
  * @returns Pkt-line formatted shallow response
+ *
+ * @example
+ * ```typescript
+ * const response = formatShallowResponse({
+ *   shallowCommits: ['abc123...'],
+ *   unshallowCommits: []
+ * })
+ * // '001cshallow abc123...\n'
+ * ```
  */
 export declare function formatShallowResponse(shallowInfo: ShallowInfo): string;
 /**
- * Wrap data in side-band format
+ * Wrap data in side-band format.
+ *
+ * @description
+ * Wraps data in side-band format for multiplexed transmission.
+ * The format is: pkt-line length + channel byte + data
  *
  * @param channel - Side-band channel (1=data, 2=progress, 3=error)
  * @param data - Data to wrap
  * @returns Pkt-line formatted side-band data
+ *
+ * @example
+ * ```typescript
+ * // Wrap packfile data for channel 1
+ * const wrapped = wrapSideBand(SideBandChannel.PACK_DATA, packfile)
+ *
+ * // Wrap progress message for channel 2
+ * const progress = wrapSideBand(
+ *   SideBandChannel.PROGRESS,
+ *   encoder.encode('Counting objects: 100%\n')
+ * )
+ * ```
  */
 export declare function wrapSideBand(channel: SideBandChannel, data: Uint8Array): Uint8Array;
 /**
- * Send progress message via side-band
+ * Send progress message via side-band.
  *
- * @param message - Progress message
+ * @description
+ * Creates a side-band channel 2 message for progress reporting.
+ * Messages are displayed to the user during fetch operations.
+ *
+ * @param message - Progress message (newline added if not present)
  * @returns Pkt-line formatted progress message
+ *
+ * @example
+ * ```typescript
+ * const progress = formatProgress('Counting objects: 42')
+ * // Side-band channel 2 packet with the message
+ * ```
  */
 export declare function formatProgress(message: string): Uint8Array;
 /**
- * Generate a packfile containing the requested objects
+ * Generate a packfile containing the requested objects.
+ *
+ * @description
+ * Creates a Git packfile containing all objects needed by the client.
+ * The packfile format includes:
+ * - 12-byte header (PACK + version + object count)
+ * - Compressed objects with type/size headers
+ * - 20-byte SHA-1 checksum
  *
  * @param store - Object store to get objects from
  * @param wants - Objects the client wants
  * @param haves - Objects the client already has
  * @param options - Packfile generation options
- * @returns Packfile result
+ * @returns Packfile result with binary data and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await generatePackfile(
+ *   store,
+ *   ['commit-sha-1', 'commit-sha-2'],
+ *   ['base-commit-sha'],
+ *   { thinPack: true, onProgress: console.log }
+ * )
+ * // result.packfile contains the binary packfile
+ * // result.objectCount is the number of objects
+ * ```
  */
 export declare function generatePackfile(store: ObjectStore, wants: string[], haves: string[], options?: PackfileOptions): Promise<PackfileResult>;
 /**
- * Generate thin pack with deltas against client's objects
+ * Generate thin pack with deltas against client's objects.
+ *
+ * @description
+ * Creates a thin pack that can use objects the client already has
+ * as delta bases, resulting in smaller transfer sizes.
  *
  * @param store - Object store
  * @param objects - Objects to include
  * @param clientHasObjects - Objects client already has (for delta bases)
  * @returns Thin packfile
+ *
+ * @example
+ * ```typescript
+ * const result = await generateThinPack(
+ *   store,
+ *   ['new-blob-sha'],
+ *   ['similar-blob-sha']  // Client has this, can be delta base
+ * )
+ * ```
  */
 export declare function generateThinPack(store: ObjectStore, objects: string[], clientHasObjects: string[]): Promise<PackfileResult>;
 /**
- * Handle a complete fetch request
+ * Handle a complete fetch request.
  *
- * This is the main entry point that handles the full protocol flow:
- * 1. Parse client request (wants, haves, capabilities)
- * 2. Negotiate common ancestors
- * 3. Generate and send packfile
+ * @description
+ * This is the main entry point that handles the full upload-pack protocol flow:
+ * 1. Parse client request (wants, haves, capabilities, shallow commands)
+ * 2. Negotiate common ancestors via ACK/NAK
+ * 3. Generate and return packfile with requested objects
  *
  * @param session - Upload pack session
- * @param request - Raw request data
+ * @param request - Raw request data (pkt-line formatted)
  * @param store - Object store
  * @returns Response data (ACKs/NAKs + packfile)
+ *
+ * @example
+ * ```typescript
+ * const session = createSession('repo', refs)
+ * const requestBody = '0032want abc123... side-band-64k\n00000009done\n'
+ *
+ * const response = await handleFetch(session, requestBody, store)
+ * // response contains NAK + packfile data
+ * ```
  */
 export declare function handleFetch(session: UploadPackSession, request: string, store: ObjectStore): Promise<Uint8Array>;
 //# sourceMappingURL=upload-pack.d.ts.map