git-remote-ops 0.1.0

package/esm/pack/delta.js

@@ -0,0 +1,179 @@
+/**
+ * @module pack-delta
+ *
+ * Pack format varint decoders and the Git delta reconstruction routine.
+ *
+ * Two varint flavours live in pack files. The "big-endian" form used by
+ * `OBJ_OFS_DELTA` headers is decoded by {@link readVarintBe}; the
+ * little-endian form used inside the delta opcode stream is handled inline
+ * by {@link applyDelta}.
+ *
+ * Delta format spec: https://git-scm.com/docs/pack-format#_deltified_representation
+ */
+import { Result } from "better-result";
+import { PackParseError } from "../errors.js";
+import { VARINT_CONTINUE, VARINT_VALUE_MASK } from "./objects.js";
+/** Bits of payload per varint byte. */
+const VARINT_VALUE_BITS = 7;
+/** High bit on a delta opcode byte → COPY instruction; otherwise INSERT. */
+const DELTA_COPY_FLAG = 0x80;
+/** Up to 4 bytes encode the copy offset (one per set bit in opcode low nibble). */
+const DELTA_COPY_OFFSET_BYTES = 4;
+/** Up to 3 bytes encode the copy size (one per set bit in opcode high nibble). */
+const DELTA_COPY_SIZE_BYTES = 3;
+/** Bit position of the first copy-size selector inside the opcode byte. */
+const DELTA_COPY_SIZE_SHIFT = 4;
+/** Special case: a copy with all size bytes absent means "copy 64 KiB". */
+const DELTA_DEFAULT_COPY_SIZE = 0x10000;
+/**
+ * Decode Git's "offset-encoded" big-endian varint (used for `OBJ_OFS_DELTA`
+ * base offsets).
+ *
+ * Each continuation byte adds an implicit `+1` before shifting, which lets the
+ * encoding represent more values in the same number of bytes than a plain MSB
+ * varint would.
+ *
+ * @returns `{ value, offset }` where `offset` points just past the last byte
+ *   consumed, or {@link PackParseError} if the buffer ends mid-varint.
+ */
+export function readVarintBe(data, offset) {
+    if (offset >= data.length) {
+        return Result.err(new PackParseError({
+            reason: "truncated-varint",
+            message: "truncated varint",
+            offset,
+        }));
+    }
+    let byte = data[offset++];
+    let value = byte & VARINT_VALUE_MASK;
+    while ((byte & VARINT_CONTINUE) !== 0) {
+        if (offset >= data.length) {
+            return Result.err(new PackParseError({
+                reason: "truncated-varint",
+                message: "truncated varint",
+                offset,
+            }));
+        }
+        value += 1;
+        byte = data[offset++];
+        value = (value << VARINT_VALUE_BITS) | (byte & VARINT_VALUE_MASK);
+    }
+    return Result.ok({ value, offset });
+}
+/**
+ * Reconstruct an object body from a delta against `base`.
+ *
+ * The delta stream begins with two little-endian varints (source size, target
+ * size). Then a sequence of opcodes follows, each either:
+ *
+ *  - **COPY** (high bit set): copy a range from `base` into the output. The
+ *    low nibble's set bits select which of up to 4 offset bytes follow; the
+ *    next 3 bits select up to 3 size bytes. A size of 0 means 64 KiB.
+ *  - **INSERT** (high bit clear, opcode `1..0x7f`): emit the next `opcode`
+ *    bytes of the delta stream verbatim into the output.
+ *  - opcode `0` is reserved and invalid.
+ *
+ * The source size is validated implicitly by every COPY's bounds check.
+ *
+ * @returns The fully reconstructed object, or {@link PackParseError} on any
+ *   truncation, invalid opcode, or size mismatch.
+ */
+export function applyDelta(base, delta) {
+    let offset = 0;
+    function readVarint() {
+        let result = 0;
+        let shift = 0;
+        while (true) {
+            if (offset >= delta.length) {
+                return Result.err(new PackParseError({
+                    reason: "truncated-delta-varint",
+                    message: "truncated delta varint",
+                    offset,
+                }));
+            }
+            const byte = delta[offset++];
+            result |= (byte & VARINT_VALUE_MASK) << shift;
+            if ((byte & VARINT_CONTINUE) === 0)
+                return Result.ok(result);
+            shift += VARINT_VALUE_BITS;
+        }
+    }
+    const sourceSize = readVarint();
+    if (sourceSize.isErr())
+        return Result.err(sourceSize.error);
+    const targetSize = readVarint();
+    if (targetSize.isErr())
+        return Result.err(targetSize.error);
+    const out = new Uint8Array(targetSize.value);
+    let outOffset = 0;
+    while (offset < delta.length) {
+        const cmdOffset = offset;
+        const cmd = delta[offset++];
+        if ((cmd & DELTA_COPY_FLAG) !== 0) {
+            let copyOffset = 0;
+            let size = 0;
+            for (let i = 0; i < DELTA_COPY_OFFSET_BYTES; i++) {
+                if ((cmd & (1 << i)) !== 0) {
+                    if (offset >= delta.length) {
+                        return Result.err(new PackParseError({
+                            reason: "truncated-copy-offset",
+                            message: "truncated delta copy offset",
+                            offset,
+                        }));
+                    }
+                    copyOffset |= delta[offset++] << (i * 8);
+                }
+            }
+            for (let i = 0; i < DELTA_COPY_SIZE_BYTES; i++) {
+                if ((cmd & (1 << (DELTA_COPY_SIZE_SHIFT + i))) !== 0) {
+                    if (offset >= delta.length) {
+                        return Result.err(new PackParseError({
+                            reason: "truncated-copy-size",
+                            message: "truncated delta copy size",
+                            offset,
+                        }));
+                    }
+                    size |= delta[offset++] << (i * 8);
+                }
+            }
+            if (size === 0)
+                size = DELTA_DEFAULT_COPY_SIZE;
+            if (copyOffset + size > base.length || outOffset + size > out.length) {
+                return Result.err(new PackParseError({
+                    reason: "delta-copy-out-of-bounds",
+                    message: "delta copy exceeds source or target size",
+                    offset: cmdOffset,
+                }));
+            }
+            out.set(base.subarray(copyOffset, copyOffset + size), outOffset);
+            outOffset += size;
+        }
+        else if (cmd !== 0) {
+            if (offset + cmd > delta.length || outOffset + cmd > out.length) {
+                return Result.err(new PackParseError({
+                    reason: "delta-insert-out-of-bounds",
+                    message: "delta insert exceeds source or target size",
+                    offset: cmdOffset,
+                }));
+            }
+            out.set(delta.subarray(offset, offset + cmd), outOffset);
+            outOffset += cmd;
+            offset += cmd;
+        }
+        else {
+            return Result.err(new PackParseError({
+                reason: "invalid-delta-opcode",
+                message: "invalid delta opcode 0",
+                offset: cmdOffset,
+            }));
+        }
+    }
+    if (outOffset !== out.length) {
+        return Result.err(new PackParseError({
+            reason: "delta-target-size-mismatch",
+            message: `delta produced ${outOffset} bytes, expected ${out.length}`,
+            offset,
+        }));
+    }
+    return Result.ok(out);
+}

package/esm/pack/index.js

@@ -0,0 +1,3 @@
+export * from "./objects.js";
+export * from "./delta.js";
+export * from "./parser.js";

package/esm/pack/objects.js

@@ -0,0 +1,72 @@
+/**
+ * @module pack-objects
+ *
+ * Shared constants and the SHA-1 helper used by the packfile parser. Object
+ * type codes, varint flags, and pack-format magic live here so that
+ * {@link parser} and {@link delta} both reach for the same source of truth.
+ *
+ * Pack format reference:
+ * https://git-scm.com/docs/pack-format
+ */
+import { Result } from "better-result";
+import { crypto } from "../deps/jsr.io/@std/crypto/1.1.0/mod.js";
+import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.10/hex.js";
+import { PackParseError } from "../errors.js";
+/** Magic bytes opening every packfile: ASCII `"PACK"`. */
+export const PACK_SIGNATURE = new Uint8Array([0x50, 0x41, 0x43, 0x4b]);
+/** Bytes consumed by the fixed pack header (signature + version + count). */
+export const PACK_HEADER_SIZE = 12;
+/** Size of {@link PACK_SIGNATURE} in bytes. */
+export const PACK_SIGNATURE_SIZE = 4;
+/** Pack format versions this parser accepts. v4 exists but is not produced by mainline Git. */
+export const SUPPORTED_PACK_VERSIONS = new Set([2, 3]);
+/** Trailing SHA-1 over the rest of the pack — sits at the very end of the buffer. */
+export const PACK_TRAILER_SIZE = 20;
+/** High bit set on a varint byte means "another byte follows". */
+export const VARINT_CONTINUE = 0x80;
+/** Low 7 bits of a varint byte hold value bits. */
+export const VARINT_VALUE_MASK = 0x7f;
+/** Packfile object type code: commit. */
+export const OBJ_COMMIT = 1;
+/** Packfile object type code: tree. */
+export const OBJ_TREE = 2;
+/** Packfile object type code: blob. */
+export const OBJ_BLOB = 3;
+/** Packfile object type code: annotated tag. */
+export const OBJ_TAG = 4;
+/** Delta object whose base is referenced by negative offset within the same pack. */
+export const OBJ_OFS_DELTA = 6;
+/** Delta object whose base is referenced by 20-byte SHA-1 (may be outside the pack). */
+export const OBJ_REF_DELTA = 7;
+/** Pack type code → loose-object type name. Excludes delta codes by design. */
+export const OBJ_NAMES = new Map([
+    [OBJ_COMMIT, "commit"],
+    [OBJ_TREE, "tree"],
+    [OBJ_BLOB, "blob"],
+    [OBJ_TAG, "tag"],
+]);
+/** Reverse of {@link OBJ_NAMES} — type name → pack type code. */
+export const OBJ_TYPES = new Map([...OBJ_NAMES.entries()].map(([num, name]) => [name, num]));
+const encoder = new TextEncoder();
+/**
+ * Compute the canonical Git SHA-1 of an object — `sha1("<type> <size>\0" || content)`.
+ *
+ * @param type Either a pack type code (1–4) or the loose-object type name.
+ * @param content The uncompressed object body.
+ * @returns Lowercase hex SHA-1, or {@link PackParseError} when `type` is a
+ *   delta code or otherwise unknown.
+ */
+export function sha1OfObject(type, content) {
+    const name = typeof type === "number" ? OBJ_NAMES.get(type) : type;
+    if (!name) {
+        return Result.err(new PackParseError({
+            reason: "unknown-object-type",
+            message: `unknown object type ${type}`,
+        }));
+    }
+    const header = encoder.encode(`${name} ${content.length}\0`);
+    const input = new Uint8Array(header.length + content.length);
+    input.set(header);
+    input.set(content, header.length);
+    return Result.ok(encodeHex(new Uint8Array(crypto.subtle.digestSync("SHA-1", input))));
+}

package/esm/pack/parser.js

@@ -0,0 +1,304 @@
+/**
+ * @module pack-parser
+ *
+ * Decode an in-memory packfile into a `sha → GitObject` map.
+ *
+ * The parser handles the four loose-object types directly and resolves both
+ * delta encodings (`OBJ_OFS_DELTA`, `OBJ_REF_DELTA`) by applying
+ * {@link applyDelta} against bases discovered earlier in the same pack. Ref
+ * deltas whose bases haven't appeared yet are deferred and retried in fixed
+ * point until every delta resolves or progress stalls.
+ *
+ * Optimization: passing a `targets` set lets the parser bail out as soon as
+ * every requested SHA has been materialized — useful for "fetch one object"
+ * paths where the server may have sent a much larger pack.
+ *
+ * zlib note: we reach into `node:zlib`'s `_processChunk` to learn exactly how
+ * many compressed input bytes were consumed. The public Streams API doesn't
+ * expose that, and parsing the next object requires knowing where the current
+ * one's compressed run ends.
+ */
+import { Result } from "better-result";
+import zlib from "node:zlib";
+import { Buffer } from "node:buffer";
+import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.10/hex.js";
+import { PackParseError } from "../errors.js";
+import { applyDelta, readVarintBe } from "./delta.js";
+import { OBJ_NAMES, OBJ_OFS_DELTA, OBJ_REF_DELTA, OBJ_TYPES, PACK_HEADER_SIZE, PACK_SIGNATURE, PACK_SIGNATURE_SIZE, PACK_TRAILER_SIZE, sha1OfObject, SUPPORTED_PACK_VERSIONS, VARINT_CONTINUE, VARINT_VALUE_MASK, } from "./objects.js";
+/** Mask for the 3-bit object type field in the first header byte. */
+const TYPE_FIELD_MASK = 0x07;
+/** Shift to bring the type field into the low bits. */
+const TYPE_FIELD_SHIFT = 4;
+/** Mask for the size bits in the first header byte (bottom 4 bits). */
+const SIZE_LOW_NIBBLE_MASK = 0x0f;
+/** Bit width of those size bits. */
+const SIZE_LOW_NIBBLE_BITS = 4;
+/** Bit width of each subsequent varint byte's payload. */
+const VARINT_VALUE_BITS = 7;
+/** Raw 20-byte SHA-1 inline-prefixed on every `OBJ_REF_DELTA`. */
+const REF_DELTA_SHA_SIZE = 20;
+/** Offset of the big-endian pack version word inside the 12-byte header. */
+const VERSION_OFFSET = 4;
+/** Offset of the big-endian object count word inside the 12-byte header. */
+const COUNT_OFFSET = 8;
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function typeNumberOf(type) {
+    const num = OBJ_TYPES.get(type);
+    if (num === undefined) {
+        return Result.err(new PackParseError({
+            reason: "unknown-base-object-type",
+            message: `unknown base object type ${type}`,
+        }));
+    }
+    return Result.ok(num);
+}
+/**
+ * Decode a single pack-entry header starting at `offset`.
+ *
+ * Format: one byte holds `[MSB | type:3 | size_lo:4]`. While MSB is set,
+ * each additional byte contributes 7 more size bits. Returns the parsed
+ * type code, uncompressed size, and the offset just past the header.
+ */
+export function readPackObjectHeader(data, offset) {
+    if (offset >= data.length) {
+        return Result.err(new PackParseError({
+            reason: "truncated-object-header",
+            message: "truncated pack object header",
+            offset,
+        }));
+    }
+    let byte = data[offset++];
+    const type = (byte >> TYPE_FIELD_SHIFT) & TYPE_FIELD_MASK;
+    let size = byte & SIZE_LOW_NIBBLE_MASK;
+    let shift = SIZE_LOW_NIBBLE_BITS;
+    while ((byte & VARINT_CONTINUE) !== 0) {
+        if (offset >= data.length) {
+            return Result.err(new PackParseError({
+                reason: "truncated-object-header",
+                message: "truncated pack object header",
+                offset,
+            }));
+        }
+        byte = data[offset++];
+        size |= (byte & VARINT_VALUE_MASK) << shift;
+        shift += VARINT_VALUE_BITS;
+    }
+    return Result.ok({ type, size, offset });
+}
+/**
+ * Inflate one zlib stream embedded in the pack at `offset`.
+ *
+ * The pack's 20-byte trailer is sliced off before inflation so the deflate
+ * engine never sees it. `bytesWritten` on the `Inflate` engine reports how
+ * many input bytes were consumed, which is the only reliable way to advance
+ * `offset` to the next entry — multiple deflate streams sit back-to-back
+ * inside the pack and there's no length prefix at this layer.
+ *
+ * @param expectedSize Uncompressed size reported by the object header. When
+ *   provided, used to right-size the inflate chunk buffer and to assert the
+ *   output length post-hoc.
+ */
+export function decompressAt(data, offset, expectedSize) {
+    const slice = data.subarray(offset, data.length - PACK_TRAILER_SIZE);
+    const input = Buffer.from(slice);
+    const engine = new zlib.Inflate({
+        chunkSize: expectedSize !== undefined ? Math.max(expectedSize + 16, 1024) : 16384,
+    });
+    let output;
+    try {
+        output = engine._processChunk(input, zlib.constants.Z_FINISH);
+    }
+    catch (cause) {
+        engine.close();
+        return Result.err(new PackParseError({
+            reason: "inflate-failed",
+            message: `failed to inflate pack object: ${cause?.message ?? cause}`,
+            offset,
+            cause,
+        }));
+    }
+    const consumed = engine.bytesWritten;
+    engine.close();
+    if (expectedSize !== undefined && output.length !== expectedSize) {
+        return Result.err(new PackParseError({
+            reason: "inflated-size-mismatch",
+            message: `object inflated to ${output.length} bytes, expected ${expectedSize}`,
+            offset,
+        }));
+    }
+    const value = new Uint8Array(output.buffer, output.byteOffset, output.byteLength);
+    return Result.ok({ value, offset: offset + consumed });
+}
+/**
+ * Walk every entry in `pack` and return a map of resolved objects keyed by
+ * SHA-1.
+ *
+ * For non-delta entries, the inflated bytes are hashed and stored. For
+ * `OBJ_OFS_DELTA` the base is looked up via `byOffset` (always present, since
+ * pack ordering guarantees the base appears earlier in the stream). For
+ * `OBJ_REF_DELTA` the base may be either earlier or later — unresolved ones
+ * accumulate in `pendingRefDeltas` and are retried until either all resolve
+ * or a pass makes no progress (cyclic / out-of-pack reference).
+ *
+ * @param targets Optional set of "wanted" SHAs. If supplied, the parser
+ *   returns as soon as every target has been materialized — even mid-pack.
+ */
+export function parsePackfile(pack, targets) {
+    if (pack.length < PACK_HEADER_SIZE + PACK_TRAILER_SIZE) {
+        return Result.err(new PackParseError({
+            reason: "truncated-packfile",
+            message: "packfile too small",
+            offset: 0,
+        }));
+    }
+    const signature = pack.subarray(0, PACK_SIGNATURE_SIZE);
+    if (!bytesEqual(signature, PACK_SIGNATURE)) {
+        return Result.err(new PackParseError({
+            reason: "invalid-signature",
+            message: `not a packfile, starts with ${Array.from(signature).join(",")}`,
+            offset: 0,
+        }));
+    }
+    const view = new DataView(pack.buffer, pack.byteOffset, pack.byteLength);
+    const version = view.getUint32(VERSION_OFFSET);
+    const count = view.getUint32(COUNT_OFFSET);
+    if (!SUPPORTED_PACK_VERSIONS.has(version)) {
+        return Result.err(new PackParseError({
+            reason: "unsupported-version",
+            message: `unsupported pack version ${version}`,
+            offset: VERSION_OFFSET,
+        }));
+    }
+    const bySha = new Map();
+    const byOffset = new Map();
+    let offset = PACK_HEADER_SIZE;
+    let pendingRefDeltas = [];
+    function store(typeNumber, content, objectOffset) {
+        const type = OBJ_NAMES.get(typeNumber);
+        if (!type) {
+            return Result.err(new PackParseError({
+                reason: "unknown-object-type",
+                message: `unknown object type ${typeNumber}`,
+                offset: objectOffset,
+            }));
+        }
+        const sha = sha1OfObject(typeNumber, content);
+        if (sha.isErr())
+            return Result.err(sha.error);
+        const object = { type, content };
+        bySha.set(sha.value, object);
+        byOffset.set(objectOffset, object);
+        return Result.ok(sha.value);
+    }
+    function foundTargets() {
+        return targets !== undefined && [...targets].every((sha) => bySha.has(sha));
+    }
+    for (let i = 0; i < count; i++) {
+        const objectOffset = offset;
+        const header = readPackObjectHeader(pack, offset);
+        if (header.isErr())
+            return Result.err(header.error);
+        offset = header.value.offset;
+        if (OBJ_NAMES.has(header.value.type)) {
+            const result = decompressAt(pack, offset, header.value.size);
+            if (result.isErr())
+                return Result.err(result.error);
+            const stored = store(header.value.type, result.value.value, objectOffset);
+            if (stored.isErr())
+                return Result.err(stored.error);
+            if (foundTargets())
+                return Result.ok(bySha);
+            offset = result.value.offset;
+        }
+        else if (header.value.type === OBJ_OFS_DELTA) {
+            const varint = readVarintBe(pack, offset);
+            if (varint.isErr())
+                return Result.err(varint.error);
+            offset = varint.value.offset;
+            const base = byOffset.get(objectOffset - varint.value.value);
+            if (!base) {
+                return Result.err(new PackParseError({
+                    reason: "unresolved-ofs-delta-base",
+                    message: "unresolved ofs-delta base object",
+                    offset: objectOffset,
+                }));
+            }
+            const result = decompressAt(pack, offset, header.value.size);
+            if (result.isErr())
+                return Result.err(result.error);
+            const applied = applyDelta(base.content, result.value.value);
+            if (applied.isErr())
+                return Result.err(applied.error);
+            const typeNumber = typeNumberOf(base.type);
+            if (typeNumber.isErr())
+                return Result.err(typeNumber.error);
+            const stored = store(typeNumber.value, applied.value, objectOffset);
+            if (stored.isErr())
+                return Result.err(stored.error);
+            if (foundTargets())
+                return Result.ok(bySha);
+            offset = result.value.offset;
+        }
+        else if (header.value.type === OBJ_REF_DELTA) {
+            if (offset + REF_DELTA_SHA_SIZE > pack.length) {
+                return Result.err(new PackParseError({
+                    reason: "truncated-ref-delta-base",
+                    message: "truncated ref-delta base sha",
+                    offset,
+                }));
+            }
+            const baseSha = encodeHex(pack.subarray(offset, offset + REF_DELTA_SHA_SIZE));
+            offset += REF_DELTA_SHA_SIZE;
+            const result = decompressAt(pack, offset, header.value.size);
+            if (result.isErr())
+                return Result.err(result.error);
+            pendingRefDeltas.push({ offset: objectOffset, baseSha, delta: result.value.value });
+            offset = result.value.offset;
+        }
+        else {
+            return Result.err(new PackParseError({
+                reason: "unknown-object-type",
+                message: `unknown object type ${header.value.type}`,
+                offset: objectOffset,
+            }));
+        }
+    }
+    while (pendingRefDeltas.length > 0) {
+        const remaining = [];
+        let resolved = 0;
+        for (const delta of pendingRefDeltas) {
+            const base = bySha.get(delta.baseSha);
+            if (!base) {
+                remaining.push(delta);
+                continue;
+            }
+            const applied = applyDelta(base.content, delta.delta);
+            if (applied.isErr())
+                return Result.err(applied.error);
+            const typeNumber = typeNumberOf(base.type);
+            if (typeNumber.isErr())
+                return Result.err(typeNumber.error);
+            const stored = store(typeNumber.value, applied.value, delta.offset);
+            if (stored.isErr())
+                return Result.err(stored.error);
+            if (foundTargets())
+                return Result.ok(bySha);
+            resolved++;
+        }
+        if (resolved === 0) {
+            return Result.err(new PackParseError({
+                reason: "unresolved-ref-delta-base",
+                message: `unresolved ref-delta base object(s): ${remaining.map((item) => item.baseSha).slice(0, 3).join(", ")}`,
+            }));
+        }
+        pendingRefDeltas = remaining;
+    }
+    return Result.ok(bySha);
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/protocol/index.js

@@ -0,0 +1,3 @@
+export * from "./pkt_line.js";
+export * from "./refs.js";
+export * from "./upload_pack.js";

package/esm/protocol/pkt_line.js

@@ -0,0 +1,103 @@
+/**
+ * @module pkt-line
+ *
+ * Encode/decode Git's framing format. A pkt-line is a 4-byte ASCII-hex length
+ * prefix followed by `length - 4` payload bytes. Three reserved length values
+ * carry no payload and act as control markers (flush / delim / response-end).
+ *
+ * Spec: https://git-scm.com/docs/protocol-common
+ */
+import { Result } from "better-result";
+import { PktLineError } from "../errors.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** Width of the ASCII-hex length prefix that opens every pkt-line. */
+const PKT_LENGTH_PREFIX_SIZE = 4;
+/** Numeric base for the length prefix (lowercase hex). */
+const PKT_LENGTH_HEX_BASE = 16;
+/** Hard cap on total pkt-line size (length prefix + payload) per the spec. */
+const MAX_PKT_LINE_LENGTH = 0xffff;
+/** Sentinel length signalling end-of-section. Payload is empty. */
+const FLUSH_PKT_LENGTH = 0;
+/** Sentinel length separating header from body in protocol v2 requests. */
+const DELIM_PKT_LENGTH = 1;
+/** Sentinel length marking the end of a v2 response stream. */
+const RESPONSE_END_PKT_LENGTH = 2;
+/** Encoded `"0000"` flush packet — closes a section in v0 and v2. */
+export const FLUSH_PKT = encoder.encode("0000");
+/** Encoded `"0001"` delim packet — only valid in protocol v2. */
+export const DELIM_PKT = encoder.encode("0001");
+/** Encoded `"0002"` response-end packet — only valid in protocol v2. */
+export const RESPONSE_END_PKT = encoder.encode("0002");
+/**
+ * Wrap `payload` in a pkt-line frame.
+ *
+ * An empty payload returns the flush packet rather than a 4-byte zero-length
+ * frame, matching `git`'s convention.
+ *
+ * @param payload Raw bytes to frame. Pass any trailing `\n` you want preserved.
+ * @returns The framed bytes, or {@link PktLineError} if the total would exceed
+ *   {@link MAX_PKT_LINE_LENGTH}.
+ */
+export function pktLine(payload) {
+    if (payload.length === 0) {
+        return Result.ok(FLUSH_PKT);
+    }
+    const length = payload.length + PKT_LENGTH_PREFIX_SIZE;
+    if (length > MAX_PKT_LINE_LENGTH) {
+        return Result.err(new PktLineError({
+            reason: "pkt-line-too-long",
+            message: `pkt-line too long: ${length}`,
+        }));
+    }
+    const prefix = encoder.encode(length.toString(PKT_LENGTH_HEX_BASE).padStart(PKT_LENGTH_PREFIX_SIZE, "0"));
+    const out = new Uint8Array(length);
+    out.set(prefix, 0);
+    out.set(payload, PKT_LENGTH_PREFIX_SIZE);
+    return Result.ok(out);
+}
+/**
+ * Decode a sequence of pkt-lines from `buf`.
+ *
+ * Returns one entry per frame. Control packets (flush/delim/response-end) have
+ * `payload: null`. Data packets expose `payload` as a subarray view into `buf` —
+ * no bytes are copied. Trailing `\n` bytes inside payloads are preserved; callers
+ * that want them stripped must do so explicitly.
+ *
+ * @param buf Bytes containing zero or more concatenated pkt-lines.
+ * @param offset Starting byte index in `buf` (default `0`).
+ * @returns The decoded frames in order, or {@link PktLineError} on a bad length
+ *   prefix or a frame that runs past `buf`'s end.
+ */
+export function parsePktLines(buf, offset = 0) {
+    const lines = [];
+    while (offset + PKT_LENGTH_PREFIX_SIZE <= buf.length) {
+        const lengthOffset = offset;
+        const lengthHex = decoder.decode(buf.subarray(offset, offset + PKT_LENGTH_PREFIX_SIZE));
+        const length = Number.parseInt(lengthHex, PKT_LENGTH_HEX_BASE);
+        if (!Number.isFinite(length) || !/^[0-9a-fA-F]{4}$/.test(lengthHex)) {
+            return Result.err(new PktLineError({
+                reason: "invalid-length-prefix",
+                message: `invalid pkt-line length: ${lengthHex}`,
+                offset: lengthOffset,
+            }));
+        }
+        if (length === FLUSH_PKT_LENGTH || length === DELIM_PKT_LENGTH ||
+            length === RESPONSE_END_PKT_LENGTH) {
+            offset += PKT_LENGTH_PREFIX_SIZE;
+            lines.push({ offset, payload: null });
+            continue;
+        }
+        if (length < PKT_LENGTH_PREFIX_SIZE || offset + length > buf.length) {
+            return Result.err(new PktLineError({
+                reason: "truncated-pkt-line",
+                message: `truncated pkt-line length ${length}`,
+                offset: lengthOffset,
+            }));
+        }
+        const payload = buf.subarray(offset + PKT_LENGTH_PREFIX_SIZE, offset + length);
+        offset += length;
+        lines.push({ offset, payload });
+    }
+    return Result.ok(lines);
+}