gitx.do 0.0.1 → 0.0.3

package/dist/wire/capabilities.d.ts

@@ -1,236 +1,1044 @@
 /**
- * Git wire protocol capability negotiation
+ * @fileoverview Git wire protocol capability negotiation
  *
- * Capabilities are used during the initial handshake between git client and server
- * to determine what features are supported by both sides.
+ * This module implements the capability negotiation mechanism used in Git's wire protocol.
+ * Capabilities are exchanged during the initial handshake between git client and server
+ * to determine what features are supported by both sides, enabling backward compatibility
+ * and feature detection.
  *
- * Protocol v1: Capabilities are sent as a space-separated list after the first ref
- * Protocol v2: Capabilities are advertised line by line in the initial handshake
+ * ## Protocol Versions
  *
- * Reference: https://git-scm.com/docs/protocol-capabilities
- * Reference: https://git-scm.com/docs/protocol-v2
+ * **Protocol v1:**
+ * - Capabilities are sent as a space-separated list after the first ref line
+ * - Format: `<oid> <refname>\0<cap1> <cap2> cap3=value...`
+ * - The NUL byte (`\0`) separates ref information from capabilities
+ * - Only the first ref line contains capabilities
+ *
+ * **Protocol v2:**
+ * - Capabilities are advertised line by line in the initial handshake
+ * - Starts with `version 2` line
+ * - Each capability on its own line, with optional values after `=`
+ * - More structured and extensible than v1
+ *
+ * ## Common Capabilities
+ *
+ * **Fetch operations:**
+ * - `multi_ack`, `multi_ack_detailed`: Improved negotiation
+ * - `thin-pack`: Send thin packs requiring client to resolve deltas
+ * - `side-band`, `side-band-64k`: Multiplexed data channels
+ * - `ofs-delta`: Use offset-based delta encoding
+ * - `shallow`: Support shallow clone operations
+ *
+ * **Push operations:**
+ * - `report-status`, `report-status-v2`: Push result reporting
+ * - `atomic`: All-or-nothing ref updates
+ * - `delete-refs`: Allow ref deletion
+ * - `push-options`: Support push options
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * import {
+ *   parseCapabilityString,
+ *   findCommonCapabilities,
+ *   buildCapabilityString,
+ *   DEFAULT_FETCH_CAPABILITIES_V1
+ * } from './capabilities';
+ *
+ * // Parse capabilities from server advertisement
+ * const serverCaps = parseCapabilityString('abc123... refs/heads/main\0multi_ack side-band-64k');
+ *
+ * // Find common capabilities
+ * const clientCaps = DEFAULT_FETCH_CAPABILITIES_V1.map(name => ({ name }));
+ * const common = findCommonCapabilities(clientCaps, serverCaps);
+ *
+ * // Build capability string for request
+ * const capString = buildCapabilityString([
+ *   { name: 'multi_ack' },
+ *   { name: 'agent', value: 'gitdo/1.0' }
+ * ]);
+ * ```
+ *
+ * @module wire/capabilities
+ * @see {@link https://git-scm.com/docs/protocol-capabilities} - Protocol capabilities reference
+ * @see {@link https://git-scm.com/docs/protocol-v2} - Protocol v2 specification
+ */
+/**
+ * Git wire protocol version.
+ *
+ * @description
+ * Represents the Git wire protocol version used for communication.
+ * Version 1 is the traditional protocol, while version 2 offers improved
+ * capability negotiation and command structure.
+ *
+ * @example
+ * ```typescript
+ * const version: ProtocolVersion = 2;
+ *
+ * if (version === 2) {
+ *   // Use v2 command-based protocol
+ * } else {
+ *   // Use v1 ref advertisement protocol
+ * }
+ * ```
  */
-/** Git wire protocol version */
 export type ProtocolVersion = 1 | 2;
-/** Standard protocol v1 capabilities */
+/**
+ * Standard protocol v1 capabilities.
+ *
+ * @description
+ * Union type of all standard capability names supported in Git protocol v1.
+ * These capabilities control various aspects of fetch and push operations.
+ *
+ * **Negotiation capabilities:**
+ * - `multi_ack`: Multiple acknowledgment during negotiation
+ * - `multi_ack_detailed`: Extended ack with common/ready/continue states
+ *
+ * **Pack transfer capabilities:**
+ * - `thin-pack`: Allow thin packs requiring delta base reconstruction
+ * - `side-band`, `side-band-64k`: Multiplexed data/progress/error channels
+ * - `ofs-delta`: Use offset-based delta references (more efficient)
+ * - `include-tag`: Include tags that point to requested objects
+ *
+ * **Shallow clone capabilities:**
+ * - `shallow`: Basic shallow clone support
+ * - `deepen-since`: Shallow by date
+ * - `deepen-not`: Shallow excluding specific refs
+ * - `deepen-relative`: Deepen relative to current shallow boundary
+ *
+ * **Push capabilities:**
+ * - `report-status`, `report-status-v2`: Detailed push result reporting
+ * - `delete-refs`: Allow ref deletion via push
+ * - `atomic`: Atomic ref updates (all-or-nothing)
+ * - `push-options`: Support for push options
+ * - `push-cert`: Push certificate for signed pushes
+ * - `quiet`: Suppress progress output
+ *
+ * **Other capabilities:**
+ * - `no-progress`: Client doesn't want progress messages
+ * - `allow-tip-sha1-in-want`: Allow fetching by SHA-1 at ref tips
+ * - `allow-reachable-sha1-in-want`: Allow fetching any reachable SHA-1
+ * - `filter`: Partial clone filtering support
+ * - `agent`: Client/server identification
+ * - `symref`: Symbolic ref information (e.g., HEAD -> refs/heads/main)
+ * - `object-format`: Hash algorithm (sha1 or sha256)
+ *
+ * @example
+ * ```typescript
+ * const caps: CapabilityV1[] = ['multi_ack_detailed', 'side-band-64k', 'thin-pack'];
+ *
+ * const entries: CapabilityEntry[] = caps.map(name => ({ name }));
+ * ```
+ */
 export type CapabilityV1 = 'multi_ack' | 'multi_ack_detailed' | 'thin-pack' | 'side-band' | 'side-band-64k' | 'ofs-delta' | 'shallow' | 'deepen-since' | 'deepen-not' | 'deepen-relative' | 'no-progress' | 'include-tag' | 'report-status' | 'report-status-v2' | 'delete-refs' | 'quiet' | 'atomic' | 'push-options' | 'allow-tip-sha1-in-want' | 'allow-reachable-sha1-in-want' | 'push-cert' | 'filter' | 'agent' | 'symref' | 'object-format';
-/** Protocol v2 capabilities/commands */
+/**
+ * Protocol v2 capabilities/commands.
+ *
+ * @description
+ * Union type of capabilities and commands available in Git protocol v2.
+ * Protocol v2 uses a command-based model where capabilities are more
+ * like available services.
+ *
+ * **Commands:**
+ * - `ls-refs`: List refs (replaces ref advertisement)
+ * - `fetch`: Fetch objects (replaces upload-pack negotiation)
+ * - `object-info`: Query object information without fetching
+ * - `bundle-uri`: Bundle URI advertisement
+ *
+ * **Other capabilities:**
+ * - `agent`: Client/server identification
+ * - `server-option`: Support for server-specific options
+ * - `object-format`: Hash algorithm (sha1 or sha256)
+ * - `session-id`: Session tracking for debugging
+ * - `wait-for-done`: Wait for client "done" before sending pack
+ *
+ * @example
+ * ```typescript
+ * const v2Caps: CapabilityV2[] = ['ls-refs', 'fetch', 'agent'];
+ * ```
+ */
 export type CapabilityV2 = 'agent' | 'ls-refs' | 'fetch' | 'server-option' | 'object-format' | 'session-id' | 'wait-for-done' | 'object-info' | 'bundle-uri';
-/** Capability with optional value (e.g., agent=git/2.30.0) */
+/**
+ * Capability with optional value.
+ *
+ * @description
+ * Represents a single capability entry that may have an associated value.
+ * Some capabilities are boolean (presence indicates support), while others
+ * carry values (e.g., `agent=git/2.30.0`, `symref=HEAD:refs/heads/main`).
+ *
+ * @example
+ * ```typescript
+ * // Boolean capability (no value)
+ * const multiAck: CapabilityEntry = { name: 'multi_ack' };
+ *
+ * // Capability with value
+ * const agent: CapabilityEntry = { name: 'agent', value: 'gitdo/1.0' };
+ *
+ * // Symref capability (multiple values possible)
+ * const symref: CapabilityEntry = { name: 'symref', value: 'HEAD:refs/heads/main' };
+ * ```
+ */
 export interface CapabilityEntry {
+    /**
+     * The capability name (e.g., 'multi_ack', 'agent', 'symref').
+     * Must not contain spaces, NUL bytes, or newlines.
+     */
     name: string;
+    /**
+     * Optional value for the capability.
+     * Format depends on the capability (e.g., 'git/2.30.0' for agent).
+     * @default undefined
+     */
     value?: string;
 }
-/** Parsed capability set */
+/**
+ * Parsed capability set.
+ *
+ * @description
+ * A collection of capabilities parsed from a protocol exchange,
+ * along with the protocol version. Provides efficient lookup
+ * via a Map structure.
+ *
+ * @example
+ * ```typescript
+ * const capSet: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['side-band-64k', undefined],
+ *     ['agent', 'git/2.30.0'],
+ *     ['symref', 'HEAD:refs/heads/main']
+ *   ])
+ * };
+ *
+ * // Check if capability exists
+ * if (capSet.capabilities.has('multi_ack')) {
+ *   console.log('Server supports multi_ack');
+ * }
+ *
+ * // Get capability value
+ * const agent = capSet.capabilities.get('agent');
+ * ```
+ */
 export interface CapabilitySet {
-    /** Protocol version being used */
+    /**
+     * Protocol version being used (1 or 2).
+     */
     version: ProtocolVersion;
-    /** Map of capability name to optional value */
+    /**
+     * Map of capability name to optional value.
+     * The key is the capability name, value is the capability value or undefined.
+     */
     capabilities: Map<string, string | undefined>;
 }
-/** Ref advertisement with capabilities (protocol v1) */
+/**
+ * Ref advertisement with capabilities (protocol v1).
+ *
+ * @description
+ * Represents a single ref line from the server's ref advertisement.
+ * The first ref line includes capabilities after a NUL byte separator.
+ *
+ * @example
+ * ```typescript
+ * // First ref (with capabilities)
+ * const firstRef: RefAdvertisement = {
+ *   oid: 'abc123def456...',
+ *   name: 'refs/heads/main',
+ *   capabilities: {
+ *     version: 1,
+ *     capabilities: new Map([['multi_ack', undefined]])
+ *   }
+ * };
+ *
+ * // Subsequent ref (no capabilities)
+ * const otherRef: RefAdvertisement = {
+ *   oid: 'def789abc012...',
+ *   name: 'refs/heads/feature'
+ * };
+ * ```
+ */
 export interface RefAdvertisement {
-    /** The SHA-1 of the ref */
+    /**
+     * The SHA-1 hash of the ref's target object.
+     * 40 hexadecimal characters for SHA-1.
+     */
     oid: string;
-    /** The ref name (e.g., refs/heads/main) */
+    /**
+     * The full ref name (e.g., 'refs/heads/main', 'refs/tags/v1.0').
+     */
     name: string;
-    /** Capabilities (only on first ref line) */
+    /**
+     * Capabilities advertised by the server.
+     * Only present on the first ref line in protocol v1.
+     * @default undefined
+     */
     capabilities?: CapabilitySet;
 }
-/** Protocol v2 server capabilities response */
+/**
+ * Protocol v2 server capabilities response.
+ *
+ * @description
+ * Parsed server capability advertisement for protocol v2.
+ * Unlike v1, protocol v2 separates commands (services) from
+ * general capabilities and provides structured sub-capability values.
+ *
+ * @example
+ * ```typescript
+ * const serverCaps: ServerCapabilitiesV2 = {
+ *   version: 2,
+ *   commands: ['ls-refs', 'fetch', 'server-option'],
+ *   agent: 'git/2.40.0',
+ *   objectFormat: 'sha1',
+ *   capabilities: new Map([
+ *     ['fetch', 'shallow filter'],
+ *     ['ls-refs', 'symrefs peel']
+ *   ])
+ * };
+ *
+ * if (serverCaps.commands.includes('fetch')) {
+ *   console.log('Server supports fetch command');
+ * }
+ * ```
+ */
 export interface ServerCapabilitiesV2 {
+    /**
+     * Protocol version, always 2 for this interface.
+     */
     version: 2;
-    /** List of supported commands */
+    /**
+     * List of supported commands/services.
+     * Common commands: 'ls-refs', 'fetch', 'server-option'.
+     */
     commands: string[];
-    /** Agent string */
+    /**
+     * Agent identification string (e.g., 'git/2.40.0').
+     * @default undefined
+     */
     agent?: string;
-    /** Object format (sha1 or sha256) */
+    /**
+     * Object hash format used by the repository.
+     * @default undefined (implies 'sha1')
+     */
     objectFormat?: 'sha1' | 'sha256';
-    /** Other capabilities */
+    /**
+     * Map of capability names to values.
+     * Commands may have sub-capabilities as values (e.g., 'fetch' -> 'shallow filter').
+     */
     capabilities: Map<string, string | undefined>;
 }
-/** Want line with capabilities for fetch request */
+/**
+ * Want line with capabilities for fetch request.
+ *
+ * @description
+ * Represents a client's fetch request specifying which objects are wanted
+ * and what capabilities the client supports. Capabilities are only sent
+ * with the first want line.
+ *
+ * @example
+ * ```typescript
+ * const request: WantRequest = {
+ *   wants: [
+ *     'abc123def456789012345678901234567890abcd',
+ *     'def456789012345678901234567890abcdef12'
+ *   ],
+ *   capabilities: [
+ *     { name: 'multi_ack_detailed' },
+ *     { name: 'side-band-64k' },
+ *     { name: 'agent', value: 'gitdo/1.0' }
+ *   ]
+ * };
+ *
+ * const lines = buildFetchRequest(request);
+ * // First line: "want abc123... multi_ack_detailed side-band-64k agent=gitdo/1.0\n"
+ * // Second line: "want def456...\n"
+ * ```
+ */
 export interface WantRequest {
-    /** SHA-1s of objects we want */
+    /**
+     * SHA-1 hashes of objects the client wants to receive.
+     * These are typically commit objects at ref tips.
+     */
     wants: string[];
-    /** Capabilities to send */
+    /**
+     * Capabilities to advertise to the server.
+     * Sent only with the first want line.
+     */
     capabilities: CapabilityEntry[];
 }
-/** Have line for negotiation */
+/**
+ * Have line for negotiation.
+ *
+ * @description
+ * Represents objects the client already has, used during negotiation
+ * to determine the minimal set of objects to send.
+ *
+ * @example
+ * ```typescript
+ * const haves: HaveRequest = {
+ *   haves: [
+ *     'abc123def456789012345678901234567890abcd',
+ *     'def456789012345678901234567890abcdef12'
+ *   ],
+ *   done: true
+ * };
+ * ```
+ */
 export interface HaveRequest {
-    /** SHA-1s of objects we have */
+    /**
+     * SHA-1 hashes of objects the client already has.
+     * Used to find common ancestors and minimize data transfer.
+     */
     haves: string[];
-    /** Whether this is the final batch */
+    /**
+     * Whether this is the final batch of have lines.
+     * When true, indicates the client is ready to receive the packfile.
+     * @default undefined
+     */
     done?: boolean;
 }
-/** Version negotiation result */
+/**
+ * Version negotiation result.
+ *
+ * @description
+ * Result of protocol version negotiation between client and server.
+ * The agreed version determines the communication format.
+ *
+ * @example
+ * ```typescript
+ * const result = negotiateVersion('version 2', 2);
+ * // result.version === 2
+ * // result.serverSupportsV2 === true
+ *
+ * const resultV1 = negotiateVersion('abc123... refs/heads/main\0multi_ack', 2);
+ * // resultV1.version === 1
+ * // resultV1.serverSupportsV2 === false
+ * ```
+ */
 export interface VersionNegotiationResult {
-    /** Agreed upon version */
+    /**
+     * The protocol version that will be used.
+     * This is the lower of the client's preference and server's support.
+     */
     version: ProtocolVersion;
-    /** Whether the server supports v2 */
+    /**
+     * Whether the server advertised protocol v2 support.
+     */
     serverSupportsV2: boolean;
-    /** Common capabilities */
+    /**
+     * Capability names supported by both client and server.
+     */
     commonCapabilities: string[];
 }
-/** Default client capabilities for fetch (protocol v1) */
+/**
+ * Default client capabilities for fetch operations (protocol v1).
+ *
+ * @description
+ * A sensible set of capabilities for fetch operations that provides
+ * good performance while maintaining compatibility. These are commonly
+ * supported by modern Git servers.
+ *
+ * - `multi_ack_detailed`: Efficient negotiation with detailed feedback
+ * - `side-band-64k`: Large multiplexed data channels for progress/data
+ * - `thin-pack`: Receive thin packs (smaller transfer size)
+ * - `ofs-delta`: Efficient delta encoding
+ * - `agent`: Identify the client
+ *
+ * @example
+ * ```typescript
+ * const clientCaps = DEFAULT_FETCH_CAPABILITIES_V1.map(name => ({ name }));
+ * // Add agent value
+ * clientCaps.find(c => c.name === 'agent')!.value = 'gitdo/1.0';
+ *
+ * const selected = selectFetchCapabilities(serverCaps, clientCaps);
+ * ```
+ */
 export declare const DEFAULT_FETCH_CAPABILITIES_V1: CapabilityV1[];
-/** Default client capabilities for push (protocol v1) */
+/**
+ * Default client capabilities for push operations (protocol v1).
+ *
+ * @description
+ * A sensible set of capabilities for push operations that provides
+ * detailed feedback and compatibility with modern Git servers.
+ *
+ * - `report-status`: Receive detailed push result status
+ * - `side-band-64k`: Multiplexed channels for status/errors
+ * - `agent`: Identify the client
+ * - `quiet`: Suppress unnecessary progress output
+ *
+ * @example
+ * ```typescript
+ * const pushCaps = DEFAULT_PUSH_CAPABILITIES_V1.map(name => ({ name }));
+ * pushCaps.find(c => c.name === 'agent')!.value = 'gitdo/1.0';
+ * ```
+ */
 export declare const DEFAULT_PUSH_CAPABILITIES_V1: CapabilityV1[];
-/** Minimum required capabilities for basic fetch */
+/**
+ * Minimum required capabilities for basic fetch.
+ *
+ * @description
+ * Capabilities that must be present for fetch to work correctly.
+ * Currently empty as Git is designed to work with minimal capabilities,
+ * but this can be populated if specific capabilities become required.
+ *
+ * @example
+ * ```typescript
+ * const missing = validateRequiredCapabilities(serverCaps, REQUIRED_FETCH_CAPABILITIES);
+ * if (missing.length > 0) {
+ *   throw new Error(`Server missing required capabilities: ${missing.join(', ')}`);
+ * }
+ * ```
+ */
 export declare const REQUIRED_FETCH_CAPABILITIES: CapabilityV1[];
 /**
  * Parse a capability string from ref advertisement (protocol v1).
  *
- * Format: "<oid> <refname>\0<cap1> <cap2> cap3=value..."
+ * @description
+ * Extracts capabilities from a protocol v1 ref advertisement line.
+ * The capabilities appear after a NUL byte (`\0`) separator following
+ * the ref information. This is only present on the first ref line.
  *
- * @param line - The ref advertisement line with capabilities
- * @returns Parsed capabilities
+ * Line format: `<oid> <refname>\0<cap1> <cap2> cap3=value...`
+ *
+ * @param line - The ref advertisement line containing capabilities
+ * @returns Parsed capability set with version 1
+ *
+ * @throws {Error} If the line doesn't contain a NUL byte separator
+ *
+ * @example
+ * ```typescript
+ * // Parse from first ref line
+ * const line = 'abc123def456789012345678901234567890abcd refs/heads/main\0multi_ack side-band-64k agent=git/2.30.0';
+ * const caps = parseCapabilityString(line);
+ *
+ * console.log(caps.version); // 1
+ * console.log(caps.capabilities.has('multi_ack')); // true
+ * console.log(caps.capabilities.get('agent')); // 'git/2.30.0'
+ * ```
  */
 export declare function parseCapabilityString(line: string): CapabilitySet;
 /**
  * Parse individual capability entries from a space-separated string.
  *
+ * @description
+ * Parses a whitespace-separated capability string into individual entries.
+ * Handles both simple capabilities (`multi_ack`) and capabilities with
+ * values (`agent=git/2.30.0`).
+ *
  * @param capString - Space-separated capability string
  * @returns Array of capability entries
+ *
+ * @example
+ * ```typescript
+ * // Simple capabilities
+ * const caps1 = parseCapabilities('multi_ack thin-pack ofs-delta');
+ * // [{ name: 'multi_ack' }, { name: 'thin-pack' }, { name: 'ofs-delta' }]
+ *
+ * // Capabilities with values
+ * const caps2 = parseCapabilities('agent=git/2.30.0 symref=HEAD:refs/heads/main');
+ * // [{ name: 'agent', value: 'git/2.30.0' }, { name: 'symref', value: 'HEAD:refs/heads/main' }]
+ *
+ * // Empty string
+ * const caps3 = parseCapabilities('');
+ * // []
+ * ```
  */
 export declare function parseCapabilities(capString: string): CapabilityEntry[];
 /**
  * Parse a ref advertisement line (protocol v1).
  *
- * First line format: "<oid> <refname>\0<capabilities>"
- * Subsequent lines: "<oid> <refname>"
+ * @description
+ * Parses a single line from the server's ref advertisement. The first
+ * line has a special format including capabilities after a NUL byte,
+ * while subsequent lines contain only the OID and ref name.
+ *
+ * First line format: `<oid> <refname>\0<capabilities>`
+ * Subsequent lines: `<oid> <refname>`
  *
  * @param line - The pkt-line data (without length prefix)
  * @param isFirst - Whether this is the first line (contains capabilities)
  * @returns Parsed ref advertisement
+ *
+ * @throws {Error} If the first line is missing the NUL byte
+ * @throws {Error} If the line is missing the space between OID and refname
+ * @throws {Error} If the OID is not 40 characters (SHA-1)
+ *
+ * @example
+ * ```typescript
+ * // Parse first line (with capabilities)
+ * const firstLine = 'abc123def456789012345678901234567890abcd refs/heads/main\0multi_ack side-band-64k\n';
+ * const firstRef = parseRefAdvertisement(firstLine, true);
+ * // {
+ * //   oid: 'abc123def456789012345678901234567890abcd',
+ * //   name: 'refs/heads/main',
+ * //   capabilities: { version: 1, capabilities: Map {...} }
+ * // }
+ *
+ * // Parse subsequent line (no capabilities)
+ * const otherLine = 'def456789012345678901234567890abcdef12 refs/heads/feature\n';
+ * const otherRef = parseRefAdvertisement(otherLine, false);
+ * // {
+ * //   oid: 'def456789012345678901234567890abcdef12',
+ * //   name: 'refs/heads/feature'
+ * // }
+ * ```
  */
 export declare function parseRefAdvertisement(line: string, isFirst: boolean): RefAdvertisement;
 /**
  * Parse protocol v2 capability advertisement.
  *
- * Format:
- *   version 2
- *   agent=git/2.30.0
- *   ls-refs
- *   fetch=...
- *   server-option
- *   object-format=sha1
+ * @description
+ * Parses the server's capability advertisement in protocol v2 format.
+ * Protocol v2 uses a line-by-line format starting with "version 2",
+ * followed by capability lines. Commands and capabilities are distinguished
+ * by whether they have values.
  *
- * @param lines - Array of pkt-line data
+ * Response format:
+ * ```
+ * version 2
+ * agent=git/2.30.0
+ * ls-refs
+ * fetch=shallow filter
+ * server-option
+ * object-format=sha1
+ * ```
+ *
+ * @param lines - Array of pkt-line data (without length prefixes)
  * @returns Parsed server capabilities
+ *
+ * @throws {Error} If lines is empty or doesn't start with "version 2"
+ *
+ * @example
+ * ```typescript
+ * const lines = [
+ *   'version 2',
+ *   'agent=git/2.40.0',
+ *   'ls-refs',
+ *   'fetch=shallow filter',
+ *   'server-option',
+ *   'object-format=sha1'
+ * ];
+ *
+ * const serverCaps = parseServerCapabilitiesV2(lines);
+ * // {
+ * //   version: 2,
+ * //   commands: ['ls-refs', 'fetch', 'server-option'],
+ * //   agent: 'git/2.40.0',
+ * //   objectFormat: 'sha1',
+ * //   capabilities: Map { 'ls-refs' => undefined, 'fetch' => 'shallow filter', ... }
+ * // }
+ *
+ * if (serverCaps.commands.includes('fetch')) {
+ *   console.log('Server supports fetch with:', serverCaps.capabilities.get('fetch'));
+ * }
+ * ```
  */
 export declare function parseServerCapabilitiesV2(lines: string[]): ServerCapabilitiesV2;
 /**
  * Build a capability string for want/have request (protocol v1).
  *
+ * @description
+ * Constructs a space-separated capability string from an array of
+ * capability entries. Capabilities with values are formatted as
+ * `name=value`, while those without are just the name.
+ *
  * @param capabilities - Capabilities to include
  * @returns Space-separated capability string
+ *
+ * @example
+ * ```typescript
+ * const caps: CapabilityEntry[] = [
+ *   { name: 'multi_ack_detailed' },
+ *   { name: 'side-band-64k' },
+ *   { name: 'agent', value: 'gitdo/1.0' }
+ * ];
+ *
+ * const str = buildCapabilityString(caps);
+ * // 'multi_ack_detailed side-band-64k agent=gitdo/1.0'
+ * ```
  */
 export declare function buildCapabilityString(capabilities: CapabilityEntry[]): string;
 /**
  * Build a want line with capabilities (first want only).
  *
- * Format: "want <oid> <capabilities>\n"
+ * @description
+ * Constructs a want line for a fetch request. The first want line
+ * includes capabilities, while subsequent want lines contain only
+ * the object ID.
  *
- * @param oid - The object ID to want
- * @param capabilities - Capabilities to include
- * @returns Formatted want line
+ * Format: `want <oid> <capabilities>\n` (first line)
+ * Format: `want <oid>\n` (subsequent lines)
+ *
+ * @param oid - The object ID to want (40-character SHA-1 hex string)
+ * @param capabilities - Capabilities to include (optional, first want only)
+ * @returns Formatted want line with trailing newline
+ *
+ * @example
+ * ```typescript
+ * // First want line with capabilities
+ * const firstWant = buildWantLine(
+ *   'abc123def456789012345678901234567890abcd',
+ *   [{ name: 'multi_ack' }, { name: 'agent', value: 'gitdo/1.0' }]
+ * );
+ * // 'want abc123def456789012345678901234567890abcd multi_ack agent=gitdo/1.0\n'
+ *
+ * // Subsequent want line (no capabilities)
+ * const nextWant = buildWantLine('def456789012345678901234567890abcdef12');
+ * // 'want def456789012345678901234567890abcdef12\n'
+ * ```
  */
 export declare function buildWantLine(oid: string, capabilities?: CapabilityEntry[]): string;
 /**
  * Build a have line for negotiation.
  *
- * Format: "have <oid>\n"
+ * @description
+ * Constructs a have line used during fetch negotiation. Have lines
+ * inform the server what objects the client already has, allowing
+ * the server to determine the minimal set of objects to send.
+ *
+ * Format: `have <oid>\n`
+ *
+ * @param oid - The object ID we have (40-character SHA-1 hex string)
+ * @returns Formatted have line with trailing newline
+ *
+ * @example
+ * ```typescript
+ * const haveLine = buildHaveLine('abc123def456789012345678901234567890abcd');
+ * // 'have abc123def456789012345678901234567890abcd\n'
  *
- * @param oid - The object ID we have
- * @returns Formatted have line
+ * // OID is normalized to lowercase
+ * const normalized = buildHaveLine('ABC123DEF456789012345678901234567890ABCD');
+ * // 'have abc123def456789012345678901234567890abcd\n'
+ * ```
  */
 export declare function buildHaveLine(oid: string): string;
 /**
  * Build a complete want/have request.
  *
- * @param request - The want request with capabilities
- * @returns Array of pkt-line format strings
+ * @description
+ * Constructs all want lines for a fetch request. The first want line
+ * includes the client's capabilities, while subsequent want lines
+ * contain only the object IDs.
+ *
+ * @param request - The want request containing object IDs and capabilities
+ * @returns Array of formatted want lines (ready for pkt-line encoding)
+ *
+ * @example
+ * ```typescript
+ * const request: WantRequest = {
+ *   wants: [
+ *     'abc123def456789012345678901234567890abcd',
+ *     'def456789012345678901234567890abcdef12',
+ *     '123456789012345678901234567890abcdef00'
+ *   ],
+ *   capabilities: [
+ *     { name: 'multi_ack_detailed' },
+ *     { name: 'side-band-64k' }
+ *   ]
+ * };
+ *
+ * const lines = buildFetchRequest(request);
+ * // [
+ * //   'want abc123... multi_ack_detailed side-band-64k\n',
+ * //   'want def456...\n',
+ * //   'want 123456...\n'
+ * // ]
+ * ```
  */
 export declare function buildFetchRequest(request: WantRequest): string[];
 /**
  * Build protocol v2 command request.
  *
- * Format:
- *   command=<cmd>
- *   capability1
- *   capability2=value
- *   0001 (delimiter)
- *   <command-specific args>
- *   0000 (flush)
+ * @description
+ * Constructs a protocol v2 command request. Protocol v2 uses a structured
+ * format with command specification, capabilities, and optional arguments.
+ *
+ * Request format:
+ * ```
+ * command=<cmd>
+ * capability1
+ * capability2=value
+ * 0001 (delimiter - added by caller)
+ * <command-specific args>
+ * 0000 (flush - added by caller)
+ * ```
  *
  * @param command - The v2 command (e.g., 'fetch', 'ls-refs')
- * @param capabilities - Client capabilities
- * @param args - Command-specific arguments
- * @returns Array of pkt-line format strings
+ * @param capabilities - Client capabilities to advertise
+ * @param args - Command-specific arguments (optional)
+ * @returns Array of lines (ready for pkt-line encoding)
+ *
+ * @example
+ * ```typescript
+ * // ls-refs request
+ * const lsRefsLines = buildV2CommandRequest(
+ *   'ls-refs',
+ *   [{ name: 'agent', value: 'gitdo/1.0' }],
+ *   ['peel', 'symrefs', 'ref-prefix refs/heads/']
+ * );
+ * // [
+ * //   'command=ls-refs',
+ * //   'agent=gitdo/1.0',
+ * //   'peel',
+ * //   'symrefs',
+ * //   'ref-prefix refs/heads/'
+ * // ]
+ *
+ * // fetch request
+ * const fetchLines = buildV2CommandRequest(
+ *   'fetch',
+ *   [{ name: 'agent', value: 'gitdo/1.0' }, { name: 'thin-pack' }],
+ *   ['want abc123...', 'have def456...', 'done']
+ * );
+ * ```
  */
 export declare function buildV2CommandRequest(command: string, capabilities: CapabilityEntry[], args?: string[]): string[];
 /**
  * Negotiate protocol version with server.
  *
- * @param serverAdvertisement - First line from server
- * @param preferredVersion - Client's preferred version
- * @returns Negotiation result
+ * @description
+ * Determines the protocol version to use based on the server's advertisement
+ * and the client's preference. The negotiated version is the highest version
+ * supported by both parties.
+ *
+ * @param serverAdvertisement - First line from server's response
+ * @param preferredVersion - Client's preferred protocol version (default: 2)
+ * @returns Negotiation result with agreed version
+ *
+ * @example
+ * ```typescript
+ * // Server supports v2, client prefers v2
+ * const v2Result = negotiateVersion('version 2', 2);
+ * // { version: 2, serverSupportsV2: true, commonCapabilities: [] }
+ *
+ * // Server is v1 only, client prefers v2
+ * const v1Result = negotiateVersion('abc123... refs/heads/main\0multi_ack', 2);
+ * // { version: 1, serverSupportsV2: false, commonCapabilities: [] }
+ *
+ * // Client explicitly wants v1
+ * const explicitV1 = negotiateVersion('version 2', 1);
+ * // { version: 1, serverSupportsV2: true, commonCapabilities: [] }
+ * ```
  */
 export declare function negotiateVersion(serverAdvertisement: string, preferredVersion?: ProtocolVersion): VersionNegotiationResult;
 /**
  * Find common capabilities between client and server.
  *
- * @param clientCaps - Client capabilities
- * @param serverCaps - Server capabilities
- * @returns Array of common capability names
+ * @description
+ * Determines which capabilities are supported by both the client and server.
+ * This is used to select the optimal set of capabilities for the session.
+ *
+ * @param clientCaps - Client's supported capabilities
+ * @param serverCaps - Server's advertised capabilities
+ * @returns Array of capability names supported by both parties
+ *
+ * @example
+ * ```typescript
+ * const clientCaps: CapabilityEntry[] = [
+ *   { name: 'multi_ack_detailed' },
+ *   { name: 'side-band-64k' },
+ *   { name: 'thin-pack' },
+ *   { name: 'ofs-delta' }
+ * ];
+ *
+ * const serverCaps: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['multi_ack_detailed', undefined],
+ *     ['side-band-64k', undefined],
+ *     ['shallow', undefined]
+ *   ])
+ * };
+ *
+ * const common = findCommonCapabilities(clientCaps, serverCaps);
+ * // ['multi_ack_detailed', 'side-band-64k']
+ * ```
  */
 export declare function findCommonCapabilities(clientCaps: CapabilityEntry[], serverCaps: CapabilitySet): string[];
 /**
  * Check if a specific capability is supported.
  *
+ * @description
+ * Checks whether a capability is present in the capability set.
+ * This is a convenience wrapper around Map.has().
+ *
  * @param capSet - The capability set to check
- * @param name - The capability name
- * @returns True if capability is supported
+ * @param name - The capability name to look for
+ * @returns True if the capability is present
+ *
+ * @example
+ * ```typescript
+ * const caps: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['side-band-64k', undefined],
+ *     ['agent', 'git/2.30.0']
+ *   ])
+ * };
+ *
+ * hasCapability(caps, 'multi_ack');      // true
+ * hasCapability(caps, 'side-band-64k');  // true
+ * hasCapability(caps, 'thin-pack');      // false
+ * ```
  */
 export declare function hasCapability(capSet: CapabilitySet, name: string): boolean;
 /**
  * Get the value of a capability (if it has one).
  *
- * @param capSet - The capability set
+ * @description
+ * Retrieves the value associated with a capability. Returns undefined
+ * if the capability is not present or has no value.
+ *
+ * @param capSet - The capability set to query
  * @param name - The capability name
- * @returns The capability value or undefined
+ * @returns The capability value, or undefined if not present/no value
+ *
+ * @example
+ * ```typescript
+ * const caps: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['agent', 'git/2.30.0'],
+ *     ['symref', 'HEAD:refs/heads/main']
+ *   ])
+ * };
+ *
+ * getCapabilityValue(caps, 'agent');     // 'git/2.30.0'
+ * getCapabilityValue(caps, 'symref');    // 'HEAD:refs/heads/main'
+ * getCapabilityValue(caps, 'multi_ack'); // undefined (present but no value)
+ * getCapabilityValue(caps, 'thin-pack'); // undefined (not present)
+ * ```
  */
 export declare function getCapabilityValue(capSet: CapabilitySet, name: string): string | undefined;
 /**
  * Create a capability set from entries.
  *
- * @param version - Protocol version
- * @param entries - Capability entries
- * @returns CapabilitySet
+ * @description
+ * Constructs a CapabilitySet from an array of capability entries.
+ * This is useful for creating capability sets programmatically.
+ *
+ * @param version - Protocol version (1 or 2)
+ * @param entries - Array of capability entries
+ * @returns A new CapabilitySet
+ *
+ * @example
+ * ```typescript
+ * const entries: CapabilityEntry[] = [
+ *   { name: 'multi_ack_detailed' },
+ *   { name: 'side-band-64k' },
+ *   { name: 'agent', value: 'gitdo/1.0' }
+ * ];
+ *
+ * const capSet = createCapabilitySet(1, entries);
+ * // {
+ * //   version: 1,
+ * //   capabilities: Map {
+ * //     'multi_ack_detailed' => undefined,
+ * //     'side-band-64k' => undefined,
+ * //     'agent' => 'gitdo/1.0'
+ * //   }
+ * // }
+ * ```
  */
 export declare function createCapabilitySet(version: ProtocolVersion, entries: CapabilityEntry[]): CapabilitySet;
 /**
  * Select optimal capabilities for a fetch operation.
  *
- * @param serverCaps - Server advertised capabilities
- * @param clientPrefs - Client preferred capabilities (in priority order)
- * @returns Selected capabilities to use
+ * @description
+ * Filters client-preferred capabilities to only those supported by the server.
+ * The client's values are preserved (not the server's), maintaining client
+ * identification and preferences.
+ *
+ * @param serverCaps - Server's advertised capabilities
+ * @param clientPrefs - Client's preferred capabilities (in priority order)
+ * @returns Array of capabilities to use (subset of client preferences)
+ *
+ * @example
+ * ```typescript
+ * const serverCaps: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['side-band-64k', undefined],
+ *     ['thin-pack', undefined]
+ *   ])
+ * };
+ *
+ * const clientPrefs: CapabilityEntry[] = [
+ *   { name: 'multi_ack_detailed' },  // Not supported by server
+ *   { name: 'multi_ack' },           // Supported
+ *   { name: 'side-band-64k' },       // Supported
+ *   { name: 'ofs-delta' },           // Not supported
+ *   { name: 'agent', value: 'gitdo/1.0' }  // Not in server caps
+ * ];
+ *
+ * const selected = selectFetchCapabilities(serverCaps, clientPrefs);
+ * // [
+ * //   { name: 'multi_ack' },
+ * //   { name: 'side-band-64k' }
+ * // ]
+ * ```
  */
 export declare function selectFetchCapabilities(serverCaps: CapabilitySet, clientPrefs: CapabilityEntry[]): CapabilityEntry[];
 /**
  * Validate that a capability name is well-formed.
  *
+ * @description
+ * Checks that a capability name follows the Git protocol requirements.
+ * Capability names must be non-empty and cannot contain spaces, NUL bytes,
+ * or newline characters.
+ *
  * @param name - The capability name to validate
- * @returns True if valid
+ * @returns True if the name is valid
+ *
+ * @example
+ * ```typescript
+ * isValidCapabilityName('multi_ack');        // true
+ * isValidCapabilityName('side-band-64k');    // true
+ * isValidCapabilityName('agent');            // true
+ * isValidCapabilityName('');                 // false (empty)
+ * isValidCapabilityName('multi ack');        // false (contains space)
+ * isValidCapabilityName('cap\0name');        // false (contains NUL)
+ * isValidCapabilityName('cap\nname');        // false (contains newline)
+ * ```
  */
 export declare function isValidCapabilityName(name: string): boolean;
 /**
  * Validate that required capabilities are present.
  *
- * @param capSet - The capability set to check
- * @param required - Required capability names
- * @returns Array of missing capability names
+ * @description
+ * Checks a capability set for the presence of all required capabilities.
+ * Returns an array of missing capability names. An empty array indicates
+ * all requirements are satisfied.
+ *
+ * @param capSet - The capability set to validate
+ * @param required - Array of required capability names
+ * @returns Array of missing capability names (empty if all present)
+ *
+ * @example
+ * ```typescript
+ * const caps: CapabilitySet = {
+ *   version: 1,
+ *   capabilities: new Map([
+ *     ['multi_ack', undefined],
+ *     ['side-band-64k', undefined]
+ *   ])
+ * };
+ *
+ * // All present
+ * const missing1 = validateRequiredCapabilities(caps, ['multi_ack']);
+ * // []
+ *
+ * // Some missing
+ * const missing2 = validateRequiredCapabilities(caps, ['multi_ack', 'thin-pack', 'ofs-delta']);
+ * // ['thin-pack', 'ofs-delta']
+ *
+ * if (missing2.length > 0) {
+ *   throw new Error(`Server missing capabilities: ${missing2.join(', ')}`);
+ * }
+ * ```
  */
 export declare function validateRequiredCapabilities(capSet: CapabilitySet, required: string[]): string[];
 //# sourceMappingURL=capabilities.d.ts.map